SPB Git

Repository Public

design-system.md 10.0 KB

# 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, SwatchMenu and the inspector tab buttons use their help text as accessibilityLabel and 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; Notice carries an icon and a spoken prefix; "None" in SwatchMenu is 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 EditorCommand is 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.

Files main
Menu

Theme