SPB Git

Repository Public

design-system.md 13.9 KB

# Design system

The visual language of ORIX Sheet is defined in code, in one file: Packages/SheetUI/Sources/SheetUI/Design/Tokens.swift (namespace ORIX, plus GridPalette for the custom-drawn grid). There is no separate design file (Figma, Sketch) in the repository; this document describes what the Swift sources contain. Feature packages (Packages/Feature*) consume the same tokens through SheetUI.

Related documents: brand guidelines, icon design, accessibility, localization, grid engine, chart engine.

# How tokens are structured

swift
ORIX.Tokens.accent            // ORIX.Token(light: 0x0891B2, dark: 0x22D3EE): data, testable
ORIX.Palette.accent           // SwiftUI Color that follows the window appearance
GridPalette.resolve(dark:increaseContrast:)   // NSColor set for CoreGraphics drawing of the grid
  • ORIX.Token stores one sRGB hex value per appearance. Keeping the values as data is what allows ContrastTests (in Packages/SheetUI/Tests/SheetUITests/AccessibilityTests.swift) to compute WCAG 2.1 contrast ratios for every pair the UI draws.
  • ORIX.Palette exposes each token as a dynamic Color. The dark value is used when the effective appearance matches darkAqua, vibrantDark or accessibilityHighContrastDarkAqua (Color.init(light:dark:)).
  • GridPalette is separate because the grid is drawn with CoreGraphics, not SwiftUI: it resolves a full set of NSColor once per appearance and once more for the Increase Contrast option.

# Colour tokens

Token Light Dark Role (from the source comments and usage)
canvas #F4F5FA #0A0D18 window background behind panels
surface #FFFFFF #141828 panels, cards, bars
surfaceRaised #EEF0F7 #1D2236 hover state, table headers, raised areas
hairline #DDE0EA #262C42 1 pt separators and card borders
textPrimary #0E1222 #F2F4FB main text
textSecondary #596078 #A3AAC2 explanations, table headers
textTertiary #62697F #8A91AB section headers, metric labels
success #0D7A4B #34D399 positive state, as text or glyph
warning #995700 #FBBF24 warning state
danger #C62633 #FF6B76 error state
accent #0891B2 #22D3EE cyan accent for fills, glyphs, focus and selection
accentText #0A6F8C #22D3EE the accent used as a text colour
accentFill #0A6F8C #0E7490 background of prominent buttons under white text
accentSecondary #5B5BF0 #8484FF indigo secondary

Source: Packages/SheetUI/Sources/SheetUI/Design/Tokens.swift (ORIX.Tokens).

The asset catalog's AccentColor (App/Resources/Assets.xcassets/AccentColor.colorset) is the same cyan expressed as sRGB components: 0.031 / 0.569 / 0.698 (light) and 0.133 / 0.827 / 0.933 (dark), i.e. #0891B2 and #22D3EE to three decimals.

Reference colours, used to outline the ranges of the formula being edited, are a fixed cycle of seven: #2F6FED, #D9480F, #7B3FE4, #0E9F6E, #C2255C, #0891B2, #B7791F (ORIX.referenceColors). They are the same in light and dark; their contrast is not part of ContrastTests.

# Grid palette

Element Light Dark Light, Increase Contrast Dark, Increase Contrast
background white #10131F unchanged unchanged
gridline #E4E7EE #242A3D #8A91A8 #6C7493
header background #F6F7FA #171B2B unchanged unchanged
header, selected #D9F1F7 #1F3B4A unchanged unchanged
header text #596078 #9AA2BC #23283A #E3E7F5
header text, selected #066F89 #67E3F9 #04495B #B5F3FF
header border #D8DCE6 #2A3047 #6B7289 #8C94B2
cell text #0E1222 #ECEFF8 #000000 #FFFFFF
selection fill #0891B2 at 10 % #22D3EE at 14 % #0891B2 at 20 % #22D3EE at 26 %
selection border #0891B2 #22D3EE #05596E #7BE9FB
frozen-pane line #858CA3 #626B8F #2B3147 #C5CBE0
error text #D4313F #FF6B76 #A61B28 #FF9AA2

Source: Packages/SheetUI/Sources/SheetUI/Design/Tokens.swift (GridPalette.resolve).

These are the defaults of an unformatted sheet. Cell fills, fonts and colours chosen by the user in a workbook are document data, not tokens.

# Measured contrast (WCAG 2.1)

The figures below are copied from accessibility.md, which records the output of ContrastTests. The test fails under 4.5:1 for text and under 3:1 for glyphs and structural lines, in both appearances. This document did not re-run the test.

Pair Ratio
textPrimary on surfaces 16–18.6:1
textSecondary on surfaces 5.5–8.4:1
textTertiary on surface / canvas / raised, light 5.46 / 5.01 / 4.79
textTertiary on raised, dark 5.04
accentText on surface / canvas / raised, light 5.73 / 5.26 / 5.03
white label on accentFill, light 5.73
white label on accentFill, dark 5.36
danger as text on surface / canvas / raised, light 5.64 / 5.18 / 4.95
warning as text on surface / canvas / raised, light 5.65 / 5.19 / 4.96
success as text on surface / canvas / raised, light 5.38 / 4.94 / 4.73
accent as glyph or selection border, light 3.2–3.7
accent as glyph or selection border, dark 8.7–10.7
grid text on grid background, light / dark 18.6 / 16.1
grid header text on header, light / dark 5.82 / 6.73
selected header text on selected header, light / dark 4.91 / 7.82
grid error text on grid background, light / dark 4.87 / 6.71
frozen-pane line on grid, light / dark 3.35 / 3.54
ordinary gridline on grid, light / dark (decoration, below 3:1 on purpose) 1.24 / 1.30
gridline on grid with Increase Contrast, light 3.14

Source: docs/development/accessibility.md, section "Colour contrast (WCAG 2.1)".

Consequences that are rules of the system:

  • accent is never a text colour and never sits under white text. In light mode #0891B2 reaches only 3.23–3.68:1 on the surfaces and 3.68:1 under white (the "Before" column of accessibility.md). Use accentText for text and accentFill for prominent buttons. In dark mode accentText equals accent.
  • Ordinary gridlines and hairlines are decoration and are allowed below 3:1; the Increase Contrast option of macOS raises them.
  • Not measured: colours inside feature panels, and any place where a feature uses accent as text or as a button tint (accessibility.md states this limit). A count made on 2026-11-21 with grep -rhoE "ORIX\.Palette\.[A-Za-z]+" Packages/*/Sources App/Sources finds 160 uses of Palette.accent, 10 of accentText and 2 of accentFill; the count says nothing about whether each accent use is a fill, a glyph or text.

# Spacing, radius, typography, motion

Group Token Value Uses found in Packages/*/Sources and App/Sources
Space xxs 4 pt 0
Space xs 8 pt 86
Space sm 12 pt 137
Space md 16 pt 44
Space lg 24 pt 12
Space xl 32 pt 6
Radius chip 6 pt 48
Radius control 8 pt 57
Radius card 14 pt 21
Typeface label system 11 pt semibold 0
Typeface body system 13 pt 27
Typeface value system 13 pt medium, monospaced digits 9
Typeface caption system 11 pt, monospaced digits 84
Typeface mono system monospaced 12 pt 18
Typeface title system 20 pt semibold 1
Typeface display system 30 pt bold 0
Motion quick ease-out, 0.14 s 3
Motion standard spring, response 0.3, damping 0.86 0

Source: values from Tokens.swift; use counts from grep -rhoE "ORIX\.(Space|Radius|Typeface|Motion)\.[A-Za-z]+" Packages/*/Sources App/Sources | sort | uniq -c, run on 2026-11-21 (packages still being edited may change the counts).

Observations that follow from the counts:

  • The spacing scale is a 4-pt grid; sm (12) and xs (8) carry most of the layout, which is what makes the chrome dense. xxs, Typeface.label, Typeface.display and Motion.standard are defined but not referenced at the time of writing.
  • Many views set a literal font size instead of a Typeface token (for example ToolButton uses .system(size: 13, weight: .medium), SectionHeader 10.5 pt semibold, ValueTable 11.5 and 12 pt). The typography tokens are therefore a baseline, not an exhaustive list of sizes on screen.
  • The typeface is always the system font (San Francisco). Numbers use monospaced digits wherever values are compared in a column (value, caption, MetricChip, ValueTable).
  • Chrome text uses fixed point sizes and does not follow a system text-size setting; the grid has its own zoom (75–200 %) instead. See accessibility.md.
  • Motion: SheetUI has one animation, the appearance of the find bar, and it goes through ORIX.Motion.respecting(_:), which returns nil when Reduce Motion is on.

# Components

All in Packages/SheetUI/Sources/SheetUI/Chrome/Components.swift, public, usable by feature packages.

Component What it is Token usage
ToolButton 28 × 26 pt icon button (SF Symbol, 13 pt). Optional on/off state. on: accentText glyph on accent at 16 % with Radius.chip; hover: surfaceRaised; with Differentiate Without Colour or Increase Contrast an on button gains a 1.5 pt accentText outline (and a heavy glyph with Differentiate Without Colour)
ToolDivider 1 × 18 pt vertical separator in toolbars hairline
SectionHeader upper-cased 10.5 pt semibold header with 0.6 kerning textTertiary; exposed as a header to accessibility
InspectorSection header + content block of an inspector padding Space.sm horizontal, Space.xs vertical and between rows
ORIXCard container for studio panels surface fill, hairline border, Radius.card, padding Space.md
EmptyStateView icon (34 pt light), title (15 pt semibold), message (max 360 pt wide), optional action icon accent, title textPrimary, message textSecondary, button .borderedProminent tinted accentFill, padding Space.xl
MetricChip label + value pill, 11 pt medium, monospaced digits label textTertiary, value textPrimary
ValueTable read-only, selectable table of strings; numeric-looking cells right-aligned header rows on surfaceRaised with textSecondary; body rows alternate surface and canvas at 50 %; hairline rules; Radius.control

Source: Packages/SheetUI/Sources/SheetUI/Chrome/Components.swift.

Every text-taking component has two initialisers: one that looks the argument up in the SheetUI string catalog, and a localized: variant that shows the text verbatim (for packages with their own catalog). See localization.md.

# Layout principles

The workbook window (WorkbookView) is a vertical stack with 1 pt hairline rules between bars. Solid arrows give the top-to-bottom order of the stack; dotted arrows show what the split view contains, left to right:

flowchart TD
    T["FormatToolbar"] --> F["FormulaBar"]
    F --> S["HSplitView"]
    S -.->|contains| N["NavigatorSidebar<br/>(optional)"]
    S -.->|contains| C["Centre: grid or studio<br/>min width 360"]
    S -.->|contains| I["Inspector<br/>(optional, 230-420 wide)"]
    S --> B["SheetTabsBar<br/>(full width, below the split view)"]

SVG fallback: Workbook window layout

Facts from Packages/SheetUI/Sources/SheetUI/Chrome/WorkbookView.swift:

  • One formatting toolbar, one formula bar; no ribbon. The competitive analysis (docs/research/competitive-analysis.md) records this as a retained product decision: "one formatting toolbar, contextual inspectors, studios that take over the centre of the window when a task needs room".
  • The centre has layout priority and a minimum width of 360 pt; the inspector is 230–420 pt wide (ideal 280); the grid area keeps at least 180 pt of height and a bottom pane at least 140 pt (ideal 240).
  • The window background is canvas; bars and the inspector are surface.
  • Sidebar and inspector are optional (session.showSidebar, session.inspectorPane). How feature panes register is described in architecture/overview.md.

# Light and dark

  • Every token has both values; nothing in the token file is appearance-specific logic other than the resolution described above.
  • Settings offers System / Light / Dark (AppSettings.Appearance in App/Sources/AppSettings.swift); Light and Dark set NSApp.appearance to aqua / darkAqua, System clears it.
  • The grid redraws with GridPalette.resolve(dark:increaseContrast:) when the appearance or the Increase Contrast option changes (accessibility.md).
  • Verified by eye in both appearances on screenshots of the main window (accessibility.md). Increase Contrast, Differentiate Without Colour and Reduce Motion were not switched on during a run; only the palette code paths are covered by unit tests.

# What the design system does not contain

  • No shared Swift package across the ORIX family: docs/research/technology-evaluation.md states that each sibling app ships its own tokens and that the shared palette is "reused here without a runtime dependency".
  • No elevation/shadow tokens, no icon set of its own (SF Symbols are used), no token for chart colours in Tokens.swift (chart palettes live in the charts package; see chart engine).
  • The SVG fallbacks of the documentation diagrams (docs/assets/diagrams/make_diagrams.py) use their own neutral colours; they are not ORIX tokens.
Files main
Menu

Theme