design-system

1# Design system
2 
3A design system is a short list of **tokens** in code and one page that
4says which token to use when. Every screen uses tokens, never raw values.
5Then a change in one place changes the whole app, and an agent can review a
6screen against one page.
7 
8Start from `mac-design`. Tokens cover only what the system does not:
9the accent, custom surfaces, radii, motion, overlays, and custom controls.
10 
11The app keeps Apple's look. Only the accent color changes. For parts of
12your own (a custom sidebar, buttons, icons), call the Skill tool with
13`design-kit`. To copy the look of an app the user names, call it with
14`design-from-app`.
15 
16The template already has the base in `Sources/<App>/UI/`:
17 
18- `Theme.swift`: the accent colors (`Theme.all`), the saved choice
19  (`ThemeStore`), the tokens `Palette.accent`, `Palette.accentText`,
20  `Palette.onAccent`, and `.themed()`, which tints every scene.
21- `AppearanceSettings.swift`: Settings > Appearance, where people pick the
22  accent. Light and dark mode follow the Mac. Apple advises against an
23  app-specific mode setting; add a System/Light/Dark picker only when the
24  owner asks for one, with System as the default. [HIG Dark Mode]
25- `Grid.swift`: spacing (see the `layout-grid` skill).
26 
27## 1. Pick the accent
28 
29Read `## Look` in `docs/BRIEF.md`. With no color named, keep `system`: it
30follows the accent color the person set for their Mac.
31 
32For a brand color, set `ThemeStore.brand` to a `Theme` with three shades:
33…