SPB Git

Repository Public

design-system.md 10.0 KB 169 lines markdown

1<!--2ORIX Docs3File: docs/design/design-system.md4Description: Design tokens and components as they exist in App/Sources/DesignSystem, workspace modes and layout regions, accessibility conventions.5Author: Simon-Pierre Boucher6Contact: contact@spboucher.ai7-->8# Design system910Everything here is read from the code: tokens in `App/Sources/DesignSystem/Tokens.swift`, components in `Components.swift`, `InspectorControls.swift` and `SheetComponents.swift`, the window layout in `App/Sources/Workspace/WorkspaceView.swift`. The brand side is in [brand-guidelines.md](brand-guidelines.md), the icon in [icon-design.md](icon-design.md).1112## Tokens1314All tokens live in the `ORIX` namespace. Colours are dynamic (`NSColor.dynamic(light:dark:)`): one sRGB value for Aqua, one for Dark Aqua.1516### Colour roles (`ORIX.Palette`)1718| Role | Light | Dark | Use |19|---|---|---|---|20| `accent` / `accentNS` | `#4F46E5` | `#818CF8` | Selected states, caret, selected-object outline, header/footer editing frame. Also the asset catalogue's `AccentColor`. |21| `secondary` | `#D97706` | `#FBBF24` | The amber counterpart of the accent. |22| `canvas` / `canvasNS` | `#E9EAF0` | `#0E1017` | The desk behind the pages. |23| `chrome` | `#F7F7FA` | `#171922` | Bars, sidebar, inspector, window background. |24| `surface` | `#FFFFFF` | `#1E2130` | Fields and wells. |25| `surfaceRaised` | `#FFFFFF` | `#262A3B` | Raised panels. |26| `hairline` | `#DCDDE5` | `#2C3042` | One-pixel separators and field borders. |27| `text` | `#16181D` | `#ECEDF3` | Primary text. |28| `textSecondary` | `#5B6170` | `#9BA1B5` | Labels, status bar. |29| `textTertiary` | `#8A8FA3` | `#6C7289` | Hints, ruler ticks, disabled-looking details. |30| `positive` | `#15803D` | `#4ADE80` | Success. |31| `warning` | `#B45309` | `#FBBF24` | Warnings, the "Tracking" pill. |32| `critical` | `#BE123C` | `#FB7185` | Errors. |33| `selectionNS` | `#4F46E5` at 26 % | `#818CF8` at 26 % | Text selection (the canvas applies its own opacity: 28 % in the key window, 14 % otherwise). |34| `accentGradient` | `#7C74FF` → `#4F46E5` → `#3730A3`, top-leading to bottom-trailing (same in both appearances) | | Selected mode capsule, sheet header badge, prominent buttons. |3536The **page itself is not themed**: paper is drawn white in both appearances and document colours come from the document (`PageRenderer`, `EditorCanvasView.draw`). Only the surroundings follow the appearance; the page's shadow is stronger in Dark Aqua.3738Colours outside the palette that the canvas uses directly: `systemYellow` for find matches, `systemRed` for spelling marks, and the six reviewer colours of `ReviewColors` for tracked changes.3940### Spacing (`ORIX.Space`)4142| `xxs` | `xs` | `s` | `m` | `l` | `xl` | `xxl` |43|---|---|---|---|---|---|---|44| 2 | 4 | 8 | 12 | 16 | 24 | 32 |4546### Radii (`ORIX.Radius`)4748| `s` | `m` | `l` | `xl` |49|---|---|---|---|50| 5 | 8 | 12 | 18 |5152### Type ramp (`ORIX.Font`)5354All are the system font; sizes are fixed point sizes.5556| Token | Size | Weight | Design |57|---|---|---|---|58| `caption` | 10.5 | medium | default |59| `sectionTitle` | 10.5 | semibold | default |60| `label` | 11.5 | regular | default |61| `body` | 12.5 | regular | default |62| `title` | 15 | semibold | default |63| `display` | 26 | bold | serif |6465Many views also set sizes inline (`.font(.system(size: 11))` in the status bar, for example); the ramp is the reference, not an enforced limit.6667### Motion (`ORIX.Motion`)6869| Token | Value | Use |70|---|---|---|71| `quick` | ease-out, 0.16 s | Small state changes, scrolling the page list to the current page. |72| `standard` | spring, response 0.32, damping 0.86 | Showing and hiding the sidebar and the inspector. |7374The code does not read the system "Reduce Motion" setting.7576## Components7778### General (`Components.swift`)7980| Component | Purpose |81|---|---|82| `BarButton` | Square borderless toolbar button with hover and "on" states. |83| `BarDivider` | Thin vertical separator between toolbar groups. |84| `InspectorSection` | Titled group in an inspector. |85| `InspectorRow` | Label on the left, control on the right. |86| `NumberField` | Compact numeric field with a stepper; commits on Return or when focus leaves. |87| `ColorMenu` | Swatch menu for text, highlight and fill colours. |88| `ColorPanelBridge` | Connects the system colour panel to a callback. |89| `Pill` | Small tinted capsule label ("Tracking"). |90| `EmptyState` | Symbol, title and message for an empty panel. |91| `ORIXButtonStyle` | Prominent (gradient) or quiet action button. |9293### Inspector controls (`InspectorControls.swift`)9495| Component | Purpose |96|---|---|97| `LengthUnit` | Inches or centimetres for page geometry; the model always stores points. |98| `FormatScope` | What typography controls edit: the selection (direct formatting) or a named style. |99| `InspectorGroup` | Titled, collapsible group whose open state is remembered on this Mac. |100| `OverrideMarker` | Dot next to a property set here rather than inherited; clicking removes the override. |101| `PropertyRow` | Label (with optional override marker) and control. |102| `InspectorNote` | Caption under a group of controls. |103| `CommitField` | `NSTextField`-backed field that commits when editing ends, before a click in the document moves the selection. |104| `ValueField` | Numeric field with stepper; each stepper click commits at once. |105| `LengthField` | Length shown in the current unit, stored in points. |106| `InspectorTextField` | Text field in the inspector's field chrome. |107| `InspectorPopup`, `ChoicePopup` | Pop-up button with free menu content, or over a fixed list of values. |108| `GlyphButton` | Text glyph in a toolbar-sized toggle (states without an SF Symbol). |109| `IconSegments`, `TextSegments` | Rows of mutually exclusive icon or text choices. |110| `SwitchRow` | Labelled switch. |111| `InspectorButton` | Quiet full-width or compact action button. |112| `SwatchMenu` | Colour swatch opening a palette menu; "None" is a struck-through swatch. |113114### Sheets and tool panels (`SheetComponents.swift`)115116| Component | Purpose |117|---|---|118| `SheetScaffold` | Common frame of every sheet: header with a gradient symbol badge, content, footer whose buttons answer Return and Escape. |119| `FieldLabel`, `LabeledField` | Caption above a field; a labelled field stacked vertically. |120| `WellBackground` | Rounded panel on the sheet surface (previews, lists). |121| `Notice` | Information, warning or error message with an icon. |122| `FlowLayout` | Wrapping left-to-right layout. |123| `Chip` | Neutral chip for badges, keys and counts. |124| `CollapsibleGroup` | Collapsible group with title, count and trailing content. |125| `PanelButton` | Full-width secondary button for tool panels. |126127## Window layout128129`DocumentWindowController` creates a 1360 × 880 window (minimum 760 × 520) with a transparent title bar and full-size content. `WorkspaceView` fills it:130131| Region | Size | Content |132|---|---|---|133| Mode bar (`ModeBar`) | 38 pt high | Sidebar toggle, the six mode capsules, the "Tracking" pill, inspector toggle. Doubles as the window drag area. |134| Format bar (`FormatBar`) | one row | Paragraph style, font, character and paragraph commands, insert menu. |135| Sidebar (`SidebarView`) | 252 pt wide | Tabs: Outline, Pages, Find, Review. |136| Ruler (`RulerView`) | 22 pt high | Page and margins, ticks (inches, or centimetres for A and B papers), column gaps, indents and tab stops of the current paragraph. |137| Canvas (`CanvasHost` → `EditorCanvasView`) | flexible, at least 320 pt | Pages on the desk: 22 pt between pages, 26 pt around. |138| Inspector (`InspectorView`) | 284 pt wide | Nine icon tabs: Typography, Styles, Document, Table, Object, References, Publish, Auditor, Intelligence. |139| Status bar (`StatusBar`) | 26 pt high | Page x of y, word and character counts, selection count, status message, "Edited", import notes, language, zoom. |140141Regions are separated by one-pixel `hairline` rules. Sheets are presented from `SheetHost` according to `DocumentSession.activeSheet`.142143## Modes144145`WorkspaceMode` (`DocumentSession.swift`) changes which panels are shown; it does not change the document. `applyMode(from:)`:146147| Mode | Effect on entering |148|---|---|149| Writing | None. |150| Page Layout | Inspector on the Document tab, ruler shown, sidebar on Pages. |151| Review | Sidebar shown on Review, markup shown. |152| Academic | Inspector on References, sidebar on Outline. |153| Publishing | Inspector on Publish, sidebar on Pages. |154| Focus | Mode bar, format bar, sidebar, ruler, inspector and status bar hidden; paragraphs other than the caret's are dimmed; an "Exit Focus" button and Escape return to Writing; the previous panel visibility is restored on leaving. |155156## Accessibility conventions157158Conventions that the components apply (visible in the three DesignSystem files and the workspace):159160* **A label for every icon-only control.** `BarButton`, `GlyphButton`, `ColorMenu`, `SwatchMenu` and the inspector tab buttons use their help text as `accessibilityLabel` and as tooltip.161* **State as a trait or value, not only as colour.** Toggles add `.isSelected`; collapsible groups report "Expanded" / "Collapsed" as value; a swatch reports its hex value or "None"; pop-ups report the current choice.162* **Not by colour alone.** The selected inspector tab has a bar under it; `Notice` carries an icon and a spoken prefix; "None" in `SwatchMenu` is struck through.163* **Headers.** Section titles in inspectors and sheets carry `.isHeader`.164* **Decorative images are hidden** (`accessibilityHidden(true)` on sheet badges, notice and chip icons); the ruler is hidden as a whole.165* **Stable identifiers** for UI tests: `document-canvas`, `cmd-<command>`, `mode-<mode>`, `inspector-tab-<tab>`, `sheet-primary`, `sheet-cancel`, `status-pages`, `status-words`, `pages-panel`, `page-thumbnail-<n>`, and others passed by the callers.166* **Keyboard.** Sheet footers answer Return and Escape; every command of `EditorCommand` is reachable from the main menu, most with a shortcut.167168Not done by the design system: Dynamic Type or user-scaled chrome text (sizes are fixed), a response to "Reduce Motion" or "Increase Contrast". The accessibility of the document text itself is described in [text-engine.md](../architecture/text-engine.md#14-accessibility).169
Files main
Menu

Theme