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
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 gridORIX.Tokenstores one sRGB hex value per appearance. Keeping the values as data is what allowsContrastTests(inPackages/SheetUI/Tests/SheetUITests/AccessibilityTests.swift) to compute WCAG 2.1 contrast ratios for every pair the UI draws.ORIX.Paletteexposes each token as a dynamicColor. The dark value is used when the effective appearance matchesdarkAqua,vibrantDarkoraccessibilityHighContrastDarkAqua(Color.init(light:dark:)).GridPaletteis separate because the grid is drawn with CoreGraphics, not SwiftUI: it resolves a full set ofNSColoronce 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:
accentis never a text colour and never sits under white text. In light mode#0891B2reaches only 3.23–3.68:1 on the surfaces and 3.68:1 under white (the "Before" column of accessibility.md). UseaccentTextfor text andaccentFillfor prominent buttons. In dark modeaccentTextequalsaccent.- 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
accentas text or as a button tint (accessibility.md states this limit). A count made on 2026-11-21 withgrep -rhoE "ORIX\.Palette\.[A-Za-z]+" Packages/*/Sources App/Sourcesfinds 160 uses ofPalette.accent, 10 ofaccentTextand 2 ofaccentFill; the count says nothing about whether eachaccentuse 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) andxs(8) carry most of the layout, which is what makes the chrome dense.xxs,Typeface.label,Typeface.displayandMotion.standardare defined but not referenced at the time of writing. - Many views set a literal font size instead of a
Typefacetoken (for exampleToolButtonuses.system(size: 13, weight: .medium),SectionHeader10.5 pt semibold,ValueTable11.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 returnsnilwhen 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:
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 aresurface. - 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.AppearanceinApp/Sources/AppSettings.swift); Light and Dark setNSApp.appearancetoaqua/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.mdstates 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.