Design system
Everything 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, the icon in icon-design.md.
Tokens
All tokens live in the ORIX namespace. Colours are dynamic (NSColor.dynamic(light:dark:)): one sRGB value for Aqua, one for Dark Aqua.
Colour roles (ORIX.Palette)
| Role | Light | Dark | Use |
|---|---|---|---|
accent / accentNS |
#4F46E5 |
#818CF8 |
Selected states, caret, selected-object outline, header/footer editing frame. Also the asset catalogue's AccentColor. |
secondary |
#D97706 |
#FBBF24 |
The amber counterpart of the accent. |
canvas / canvasNS |
#E9EAF0 |
#0E1017 |
The desk behind the pages. |
chrome |
#F7F7FA |
#171922 |
Bars, sidebar, inspector, window background. |
surface |
#FFFFFF |
#1E2130 |
Fields and wells. |
surfaceRaised |
#FFFFFF |
#262A3B |
Raised panels. |
hairline |
#DCDDE5 |
#2C3042 |
One-pixel separators and field borders. |
text |
#16181D |
#ECEDF3 |
Primary text. |
textSecondary |
#5B6170 |
#9BA1B5 |
Labels, status bar. |
textTertiary |
#8A8FA3 |
#6C7289 |
Hints, ruler ticks, disabled-looking details. |
positive |
#15803D |
#4ADE80 |
Success. |
warning |
#B45309 |
#FBBF24 |
Warnings, the "Tracking" pill. |
critical |
#BE123C |
#FB7185 |
Errors. |
selectionNS |
#4F46E5 at 26 % |
#818CF8 at 26 % |
Text selection (the canvas applies its own opacity: 28 % in the key window, 14 % otherwise). |
accentGradient |
#7C74FF → #4F46E5 → #3730A3, top-leading to bottom-trailing (same in both appearances) |
Selected mode capsule, sheet header badge, prominent buttons. |
The 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.
Colours 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.
Spacing (ORIX.Space)
xxs |
xs |
s |
m |
l |
xl |
xxl |
|---|---|---|---|---|---|---|
| 2 | 4 | 8 | 12 | 16 | 24 | 32 |
Radii (ORIX.Radius)
s |
m |
l |
xl |
|---|---|---|---|
| 5 | 8 | 12 | 18 |
Type ramp (ORIX.Font)
All are the system font; sizes are fixed point sizes.
| Token | Size | Weight | Design |
|---|---|---|---|
caption |
10.5 | medium | default |
sectionTitle |
10.5 | semibold | default |
label |
11.5 | regular | default |
body |
12.5 | regular | default |
title |
15 | semibold | default |
display |
26 | bold | serif |
Many views also set sizes inline (.font(.system(size: 11)) in the status bar, for example); the ramp is the reference, not an enforced limit.
Motion (ORIX.Motion)
| Token | Value | Use |
|---|---|---|
quick |
ease-out, 0.16 s | Small state changes, scrolling the page list to the current page. |
standard |
spring, response 0.32, damping 0.86 | Showing and hiding the sidebar and the inspector. |
The code does not read the system "Reduce Motion" setting.
Components
General (Components.swift)
| Component | Purpose |
|---|---|
BarButton |
Square borderless toolbar button with hover and "on" states. |
BarDivider |
Thin vertical separator between toolbar groups. |
InspectorSection |
Titled group in an inspector. |
InspectorRow |
Label on the left, control on the right. |
NumberField |
Compact numeric field with a stepper; commits on Return or when focus leaves. |
ColorMenu |
Swatch menu for text, highlight and fill colours. |
ColorPanelBridge |
Connects the system colour panel to a callback. |
Pill |
Small tinted capsule label ("Tracking"). |
EmptyState |
Symbol, title and message for an empty panel. |
ORIXButtonStyle |
Prominent (gradient) or quiet action button. |
Inspector controls (InspectorControls.swift)
| Component | Purpose |
|---|---|
LengthUnit |
Inches or centimetres for page geometry; the model always stores points. |
FormatScope |
What typography controls edit: the selection (direct formatting) or a named style. |
InspectorGroup |
Titled, collapsible group whose open state is remembered on this Mac. |
OverrideMarker |
Dot next to a property set here rather than inherited; clicking removes the override. |
PropertyRow |
Label (with optional override marker) and control. |
InspectorNote |
Caption under a group of controls. |
CommitField |
NSTextField-backed field that commits when editing ends, before a click in the document moves the selection. |
ValueField |
Numeric field with stepper; each stepper click commits at once. |
LengthField |
Length shown in the current unit, stored in points. |
InspectorTextField |
Text field in the inspector's field chrome. |
InspectorPopup, ChoicePopup |
Pop-up button with free menu content, or over a fixed list of values. |
GlyphButton |
Text glyph in a toolbar-sized toggle (states without an SF Symbol). |
IconSegments, TextSegments |
Rows of mutually exclusive icon or text choices. |
SwitchRow |
Labelled switch. |
InspectorButton |
Quiet full-width or compact action button. |
SwatchMenu |
Colour swatch opening a palette menu; "None" is a struck-through swatch. |
Sheets and tool panels (SheetComponents.swift)
| Component | Purpose |
|---|---|
SheetScaffold |
Common frame of every sheet: header with a gradient symbol badge, content, footer whose buttons answer Return and Escape. |
FieldLabel, LabeledField |
Caption above a field; a labelled field stacked vertically. |
WellBackground |
Rounded panel on the sheet surface (previews, lists). |
Notice |
Information, warning or error message with an icon. |
FlowLayout |
Wrapping left-to-right layout. |
Chip |
Neutral chip for badges, keys and counts. |
CollapsibleGroup |
Collapsible group with title, count and trailing content. |
PanelButton |
Full-width secondary button for tool panels. |
Window layout
DocumentWindowController creates a 1360 × 880 window (minimum 760 × 520) with a transparent title bar and full-size content. WorkspaceView fills it:
| Region | Size | Content |
|---|---|---|
Mode bar (ModeBar) |
38 pt high | Sidebar toggle, the six mode capsules, the "Tracking" pill, inspector toggle. Doubles as the window drag area. |
Format bar (FormatBar) |
one row | Paragraph style, font, character and paragraph commands, insert menu. |
Sidebar (SidebarView) |
252 pt wide | Tabs: Outline, Pages, Find, Review. |
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. |
Canvas (CanvasHost → EditorCanvasView) |
flexible, at least 320 pt | Pages on the desk: 22 pt between pages, 26 pt around. |
Inspector (InspectorView) |
284 pt wide | Nine icon tabs: Typography, Styles, Document, Table, Object, References, Publish, Auditor, Intelligence. |
Status bar (StatusBar) |
26 pt high | Page x of y, word and character counts, selection count, status message, "Edited", import notes, language, zoom. |
Regions are separated by one-pixel hairline rules. Sheets are presented from SheetHost according to DocumentSession.activeSheet.
Modes
WorkspaceMode (DocumentSession.swift) changes which panels are shown; it does not change the document. applyMode(from:):
| Mode | Effect on entering |
|---|---|
| Writing | None. |
| Page Layout | Inspector on the Document tab, ruler shown, sidebar on Pages. |
| Review | Sidebar shown on Review, markup shown. |
| Academic | Inspector on References, sidebar on Outline. |
| Publishing | Inspector on Publish, sidebar on Pages. |
| 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. |
Accessibility conventions
Conventions that the components apply (visible in the three DesignSystem files and the workspace):
- A label for every icon-only control.
BarButton,GlyphButton,ColorMenu,SwatchMenuand the inspector tab buttons use their help text asaccessibilityLabeland as tooltip. - 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. - Not by colour alone. The selected inspector tab has a bar under it;
Noticecarries an icon and a spoken prefix; "None" inSwatchMenuis struck through. - Headers. Section titles in inspectors and sheets carry
.isHeader. - Decorative images are hidden (
accessibilityHidden(true)on sheet badges, notice and chip icons); the ruler is hidden as a whole. - 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. - Keyboard. Sheet footers answer Return and Escape; every command of
EditorCommandis reachable from the main menu, most with a shortcut.
Not 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.