SPB Git

Repository Public

design-system.md 13.9 KB 242 lines markdown

1# Design system23The visual language of ORIX Sheet is defined in code, in one file:4`Packages/SheetUI/Sources/SheetUI/Design/Tokens.swift` (namespace `ORIX`, plus `GridPalette` for the5custom-drawn grid). There is no separate design file (Figma, Sketch) in the repository; this6document describes what the Swift sources contain. Feature packages (`Packages/Feature*`) consume7the same tokens through `SheetUI`.89Related documents: [brand guidelines](brand-guidelines.md), [icon design](icon-design.md),10[accessibility](../development/accessibility.md), [localization](../development/localization.md),11[grid engine](../architecture/grid-engine.md), [chart engine](../architecture/chart-engine.md).1213## How tokens are structured1415```swift16ORIX.Tokens.accent            // ORIX.Token(light: 0x0891B2, dark: 0x22D3EE): data, testable17ORIX.Palette.accent           // SwiftUI Color that follows the window appearance18GridPalette.resolve(dark:increaseContrast:)   // NSColor set for CoreGraphics drawing of the grid19```2021- `ORIX.Token` stores one sRGB hex value per appearance. Keeping the values as data is what allows22  `ContrastTests` (in `Packages/SheetUI/Tests/SheetUITests/AccessibilityTests.swift`) to compute23  WCAG 2.1 contrast ratios for every pair the UI draws.24- `ORIX.Palette` exposes each token as a dynamic `Color`. The dark value is used when the effective25  appearance matches `darkAqua`, `vibrantDark` or `accessibilityHighContrastDarkAqua`26  (`Color.init(light:dark:)`).27- `GridPalette` is separate because the grid is drawn with CoreGraphics, not SwiftUI: it resolves a28  full set of `NSColor` once per appearance and once more for the Increase Contrast option.2930## Colour tokens3132| Token | Light | Dark | Role (from the source comments and usage) |33|---|---|---|---|34| `canvas` | `#F4F5FA` | `#0A0D18` | window background behind panels |35| `surface` | `#FFFFFF` | `#141828` | panels, cards, bars |36| `surfaceRaised` | `#EEF0F7` | `#1D2236` | hover state, table headers, raised areas |37| `hairline` | `#DDE0EA` | `#262C42` | 1 pt separators and card borders |38| `textPrimary` | `#0E1222` | `#F2F4FB` | main text |39| `textSecondary` | `#596078` | `#A3AAC2` | explanations, table headers |40| `textTertiary` | `#62697F` | `#8A91AB` | section headers, metric labels |41| `success` | `#0D7A4B` | `#34D399` | positive state, as text or glyph |42| `warning` | `#995700` | `#FBBF24` | warning state |43| `danger` | `#C62633` | `#FF6B76` | error state |44| `accent` | `#0891B2` | `#22D3EE` | cyan accent for fills, glyphs, focus and selection |45| `accentText` | `#0A6F8C` | `#22D3EE` | the accent used as a text colour |46| `accentFill` | `#0A6F8C` | `#0E7490` | background of prominent buttons under white text |47| `accentSecondary` | `#5B5BF0` | `#8484FF` | indigo secondary |4849Source: `Packages/SheetUI/Sources/SheetUI/Design/Tokens.swift` (`ORIX.Tokens`).5051The asset catalog's `AccentColor` (`App/Resources/Assets.xcassets/AccentColor.colorset`) is the same52cyan expressed as sRGB components: 0.031 / 0.569 / 0.698 (light) and 0.133 / 0.827 / 0.933 (dark),53i.e. `#0891B2` and `#22D3EE` to three decimals.5455Reference colours, used to outline the ranges of the formula being edited, are a fixed cycle of56seven: `#2F6FED`, `#D9480F`, `#7B3FE4`, `#0E9F6E`, `#C2255C`, `#0891B2`, `#B7791F`57(`ORIX.referenceColors`). They are the same in light and dark; their contrast is not part of58`ContrastTests`.5960### Grid palette6162| Element | Light | Dark | Light, Increase Contrast | Dark, Increase Contrast |63|---|---|---|---|---|64| background | white | `#10131F` | unchanged | unchanged |65| gridline | `#E4E7EE` | `#242A3D` | `#8A91A8` | `#6C7493` |66| header background | `#F6F7FA` | `#171B2B` | unchanged | unchanged |67| header, selected | `#D9F1F7` | `#1F3B4A` | unchanged | unchanged |68| header text | `#596078` | `#9AA2BC` | `#23283A` | `#E3E7F5` |69| header text, selected | `#066F89` | `#67E3F9` | `#04495B` | `#B5F3FF` |70| header border | `#D8DCE6` | `#2A3047` | `#6B7289` | `#8C94B2` |71| cell text | `#0E1222` | `#ECEFF8` | `#000000` | `#FFFFFF` |72| selection fill | `#0891B2` at 10 % | `#22D3EE` at 14 % | `#0891B2` at 20 % | `#22D3EE` at 26 % |73| selection border | `#0891B2` | `#22D3EE` | `#05596E` | `#7BE9FB` |74| frozen-pane line | `#858CA3` | `#626B8F` | `#2B3147` | `#C5CBE0` |75| error text | `#D4313F` | `#FF6B76` | `#A61B28` | `#FF9AA2` |7677Source: `Packages/SheetUI/Sources/SheetUI/Design/Tokens.swift` (`GridPalette.resolve`).7879These are the defaults of an unformatted sheet. Cell fills, fonts and colours chosen by the user in80a workbook are document data, not tokens.8182### Measured contrast (WCAG 2.1)8384The figures below are copied from [accessibility.md](../development/accessibility.md), which records85the output of `ContrastTests`. The test fails under 4.5:1 for text and under 3:1 for glyphs and86structural lines, in both appearances. This document did not re-run the test.8788| Pair | Ratio |89|---|---|90| `textPrimary` on surfaces | 16–18.6:1 |91| `textSecondary` on surfaces | 5.5–8.4:1 |92| `textTertiary` on surface / canvas / raised, light | 5.46 / 5.01 / 4.79 |93| `textTertiary` on raised, dark | 5.04 |94| `accentText` on surface / canvas / raised, light | 5.73 / 5.26 / 5.03 |95| white label on `accentFill`, light | 5.73 |96| white label on `accentFill`, dark | 5.36 |97| `danger` as text on surface / canvas / raised, light | 5.64 / 5.18 / 4.95 |98| `warning` as text on surface / canvas / raised, light | 5.65 / 5.19 / 4.96 |99| `success` as text on surface / canvas / raised, light | 5.38 / 4.94 / 4.73 |100| `accent` as glyph or selection border, light | 3.2–3.7 |101| `accent` as glyph or selection border, dark | 8.7–10.7 |102| grid text on grid background, light / dark | 18.6 / 16.1 |103| grid header text on header, light / dark | 5.82 / 6.73 |104| selected header text on selected header, light / dark | 4.91 / 7.82 |105| grid error text on grid background, light / dark | 4.87 / 6.71 |106| frozen-pane line on grid, light / dark | 3.35 / 3.54 |107| ordinary gridline on grid, light / dark (decoration, below 3:1 on purpose) | 1.24 / 1.30 |108| gridline on grid with Increase Contrast, light | 3.14 |109110Source: `docs/development/accessibility.md`, section "Colour contrast (WCAG 2.1)".111112Consequences that are rules of the system:113114- **`accent` is never a text colour and never sits under white text.** In light mode `#0891B2`115  reaches only 3.23–3.68:1 on the surfaces and 3.68:1 under white (the "Before" column of116  accessibility.md). Use `accentText` for text and `accentFill` for prominent buttons. In dark mode117  `accentText` equals `accent`.118- Ordinary gridlines and hairlines are decoration and are allowed below 3:1; the Increase Contrast119  option of macOS raises them.120- **Not measured:** colours inside feature panels, and any place where a feature uses `accent` as121  text or as a button tint (accessibility.md states this limit). A count made on 2026-11-21 with122  `grep -rhoE "ORIX\.Palette\.[A-Za-z]+" Packages/*/Sources App/Sources` finds 160 uses of123  `Palette.accent`, 10 of `accentText` and 2 of `accentFill`; the count says nothing about whether124  each `accent` use is a fill, a glyph or text.125126## Spacing, radius, typography, motion127128| Group | Token | Value | Uses found in `Packages/*/Sources` and `App/Sources` |129|---|---|---|---|130| Space | `xxs` | 4 pt | 0 |131| Space | `xs` | 8 pt | 86 |132| Space | `sm` | 12 pt | 137 |133| Space | `md` | 16 pt | 44 |134| Space | `lg` | 24 pt | 12 |135| Space | `xl` | 32 pt | 6 |136| Radius | `chip` | 6 pt | 48 |137| Radius | `control` | 8 pt | 57 |138| Radius | `card` | 14 pt | 21 |139| Typeface | `label` | system 11 pt semibold | 0 |140| Typeface | `body` | system 13 pt | 27 |141| Typeface | `value` | system 13 pt medium, monospaced digits | 9 |142| Typeface | `caption` | system 11 pt, monospaced digits | 84 |143| Typeface | `mono` | system monospaced 12 pt | 18 |144| Typeface | `title` | system 20 pt semibold | 1 |145| Typeface | `display` | system 30 pt bold | 0 |146| Motion | `quick` | ease-out, 0.14 s | 3 |147| Motion | `standard` | spring, response 0.3, damping 0.86 | 0 |148149Source: values from `Tokens.swift`; use counts from150`grep -rhoE "ORIX\.(Space|Radius|Typeface|Motion)\.[A-Za-z]+" Packages/*/Sources App/Sources | sort | uniq -c`,151run on 2026-11-21 (packages still being edited may change the counts).152153Observations that follow from the counts:154155- The spacing scale is a 4-pt grid; `sm` (12) and `xs` (8) carry most of the layout, which is what156  makes the chrome dense. `xxs`, `Typeface.label`, `Typeface.display` and `Motion.standard` are157  defined but not referenced at the time of writing.158- Many views set a literal font size instead of a `Typeface` token (for example `ToolButton` uses159  `.system(size: 13, weight: .medium)`, `SectionHeader` 10.5 pt semibold, `ValueTable` 11.5 and160  12 pt). The typography tokens are therefore a baseline, not an exhaustive list of sizes on screen.161- The typeface is always the system font (San Francisco). Numbers use monospaced digits wherever162  values are compared in a column (`value`, `caption`, `MetricChip`, `ValueTable`).163- Chrome text uses fixed point sizes and does not follow a system text-size setting; the grid has164  its own zoom (75–200 %) instead. See [accessibility.md](../development/accessibility.md).165- Motion: SheetUI has one animation, the appearance of the find bar, and it goes through166  `ORIX.Motion.respecting(_:)`, which returns `nil` when Reduce Motion is on.167168## Components169170All in `Packages/SheetUI/Sources/SheetUI/Chrome/Components.swift`, public, usable by feature packages.171172| Component | What it is | Token usage |173|---|---|---|174| `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) |175| `ToolDivider` | 1 × 18 pt vertical separator in toolbars | `hairline` |176| `SectionHeader` | upper-cased 10.5 pt semibold header with 0.6 kerning | `textTertiary`; exposed as a header to accessibility |177| `InspectorSection` | header + content block of an inspector | padding `Space.sm` horizontal, `Space.xs` vertical and between rows |178| `ORIXCard` | container for studio panels | `surface` fill, `hairline` border, `Radius.card`, padding `Space.md` |179| `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` |180| `MetricChip` | label + value pill, 11 pt medium, monospaced digits | label `textTertiary`, value `textPrimary` |181| `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` |182183Source: `Packages/SheetUI/Sources/SheetUI/Chrome/Components.swift`.184185Every text-taking component has two initialisers: one that looks the argument up in the SheetUI186string catalog, and a `localized:` variant that shows the text verbatim (for packages with their own187catalog). See [localization.md](../development/localization.md).188189## Layout principles190191The workbook window (`WorkbookView`) is a vertical stack with 1 pt `hairline` rules between bars.192Solid arrows give the top-to-bottom order of the stack; dotted arrows show what the split view contains, left to right:193194<!-- diagram: design-system-window-layout -->195```mermaid196flowchart TD197    T["FormatToolbar"] --> F["FormulaBar"]198    F --> S["HSplitView"]199    S -.->|contains| N["NavigatorSidebar<br/>(optional)"]200    S -.->|contains| C["Centre: grid or studio<br/>min width 360"]201    S -.->|contains| I["Inspector<br/>(optional, 230-420 wide)"]202    S --> B["SheetTabsBar<br/>(full width, below the split view)"]203```204205SVG fallback: ![Workbook window layout](../assets/diagrams/design-system-window-layout.svg)206207Facts from `Packages/SheetUI/Sources/SheetUI/Chrome/WorkbookView.swift`:208209- One formatting toolbar, one formula bar; no ribbon. The competitive analysis210  ([docs/research/competitive-analysis.md](../research/competitive-analysis.md)) records this as a211  retained product decision: "one formatting toolbar, contextual inspectors, studios that take over212  the centre of the window when a task needs room".213- The centre has layout priority and a minimum width of 360 pt; the inspector is 230–420 pt wide214  (ideal 280); the grid area keeps at least 180 pt of height and a bottom pane at least 140 pt215  (ideal 240).216- The window background is `canvas`; bars and the inspector are `surface`.217- Sidebar and inspector are optional (`session.showSidebar`, `session.inspectorPane`). How feature218  panes register is described in [architecture/overview.md](../architecture/overview.md).219220## Light and dark221222- Every token has both values; nothing in the token file is appearance-specific logic other than the223  resolution described above.224- Settings offers System / Light / Dark (`AppSettings.Appearance` in `App/Sources/AppSettings.swift`);225  Light and Dark set `NSApp.appearance` to `aqua` / `darkAqua`, System clears it.226- The grid redraws with `GridPalette.resolve(dark:increaseContrast:)` when the appearance or the227  Increase Contrast option changes (accessibility.md).228- Verified by eye in both appearances on screenshots of the main window (accessibility.md). Increase229  Contrast, Differentiate Without Colour and Reduce Motion were not switched on during a run; only230  the palette code paths are covered by unit tests.231232## What the design system does not contain233234- No shared Swift package across the ORIX family: `docs/research/technology-evaluation.md` states235  that each sibling app ships its own tokens and that the shared palette is "reused here without a236  runtime dependency".237- No elevation/shadow tokens, no icon set of its own (SF Symbols are used), no token for chart238  colours in `Tokens.swift` (chart palettes live in the charts package; see239  [chart engine](../architecture/chart-engine.md)).240- The SVG fallbacks of the documentation diagrams (`docs/assets/diagrams/make_diagrams.py`) use241  their own neutral colours; they are not ORIX tokens.242
Files main
Menu

Theme