# Design System — design.md ## Overview This design system is a **cool-professional, teal-anchored** component library and documentation website. The base atmosphere is a **soft gray page floor** (`--color-bg-page-primary` — #F1F1F1) carrying **crisp white containers** (`--color-bg-container-primary` — #FFFFFF) that step deeper through the neutral hierarchy (soft gray #F1F1F1 → mid gray #D6D6D6) — clinical, precise, never warm. The brand voltage comes from **signature teal** (`--color-action-primary-bg` — #0E6E8F light / #3CA5C6 dark), a cyan-blue that reads trustworthy and technical without corporate-blue flatness. The action colour is deliberately theme-dependent: no single teal step can clear 3:1 against both a light page and a near-black one while also carrying a 4.5:1 label, so light mode takes a deep fill under a light label and dark mode inverts to a light fill under a dark label. The system runs a **single typeface throughout**: **Nunito Sans** at weight 300 (display/hero) → 600 (headings) → 500/400 (body/UI), with one site-chrome exception — the header wordmark sits at 700, one step above title-body's 600, so the name reads heavier than the nav pills beside it (the Site header pattern owns the detail). There is no serif face, and monospace appears only in sanctioned code contexts through `--font-family-code` — the typographic personality is clean, rounded, and approachable rather than editorial. The single face is this theme's choice, not a structural limit: the scale chains through two family roles (`--font-family-heading` for the display and heading tiers, `--font-family-body` for the body tiers), both resolving to `--font-family-primary` here, so a consumer can split heading and body faces by overriding the roles (see Font Family below). The **three-tier token architecture** is the defining structural rule: 1. **Primitives** (`--primitive-*`) — raw hex/px values. Source of truth. Never used directly in components. 2. **Semantic tokens** (`--color-*`, `--radius-*`, `--gap-*`, `--padding-*`, `--border-*`, `--font-*`, `--motion-*`, `--icon-size-*`, `--shadow-*` — `CATEGORY_PREFIXES` in `scripts/generate-token-registry.mjs` is the authoritative list) — usage-intent variables consumed by components. Always use these. 3. **Component CSS classes** (`.ds-button`, `.ds-badge`, etc.) — per-component scope, referencing semantic tokens. The system is **light/dark-first**: every semantic color token has a light-theme value and a dark-theme override. The switch is driven by `data-theme="dark"` on the root element. Status colors (positive, warning, error, info) stay perceptually stable across themes; surfaces and text invert. **Key Characteristics:** - Soft gray page floor (`--color-bg-page-primary` — #F1F1F1) with near-black primary text (`--color-text-primary` — #050505 light / #F1F1F1 dark), and crisp white containers lifting off it. - Teal primary action (`--color-action-primary-bg` — #0E6E8F light / #3CA5C6 dark). Used exclusively on primary CTA buttons, focus rings, and the selected item of a mutually exclusive set (the teal selection convention: SegmentedControl's active segment, Pagination's current page, Stepper's active step, the site header's current-section pill), with one sanctioned data-viz exception: teal leads the default chart series palette. Never decorative elsewhere. - Single-family system (Nunito Sans in the shipped theme). Weight 300 for Mega/Display (marketing), 600 for headings, 500/400 for body and UI labels; 700 appears once, on the site header's wordmark. - Container hierarchy as depth signal — standard containers carry no drop shadows. Depth is conveyed by stepping through `--color-bg-container-primary` → `secondary` → `tertiary`; the only shadows are the `--shadow-floating`/`--shadow-modal` tokens on floating surfaces and the interactive-card hover lift. - Five semantic status variants running through every feedback component: `info` (blue), `positive` (green), `warning` (orange), `error` (red), `neutral` (gray). - Border radius is hierarchical: `--radius-100` (4px) for badges, `--radius-300` (12px) for inputs and standard containers, `--radius-600` (24px) for the sanctioned soft-container set the Border Radius Scale table below enumerates (navigation tiles, chat surfaces, Panel, the floating sidebar), `--radius-pill` (999px) for buttons. - Material Symbols Rounded as the shipped icon set (a theme choice, not a structural limit — see the icon style hooks and the node-accepting icon props), on a four-step size scale — `--icon-size-500` (20px) / `md` (24px, default) / `lg` (32px) / `xl` (48px). Optical size tracks the step automatically. - One GPU-rendered surface: **ShaderField**, an ambient field of soft light sources that sample the colour tokens at runtime, so it re-themes with everything else. It is scenery rather than interface, it reports how it resolved so a caller can keep a fallback painted, and its `prefers-reduced-motion` check lives in JavaScript, where the CSS guard cannot reach (Carousel's autoplay gate makes the same move). - Accessibility-first: ARIA roles, semantic HTML, and keyboard navigation in every interactive component. ### Preset themes The playground's saved looks are shippable build artifacts, not demos. `THEME_PRESETS` in `website/src/lib/theme/presets.ts` is the registry of complete themes — every lever holds a position, never inherits one: the action brand (with an optional theme-dependent `brandDark`), neutral tint, radius scale and pill switch, spacing `density`, `typeScale`, `motionScale`, the `elevation` variant, the body and heading typefaces, the ambient accent sextet (`accents`), hand-tuned ramp re-keys (`advanced`), and per-preset extras — colour corrections with dark-only variants where the derived ramp's shape inverts, but any token is fair game (Forest re-pitches the display-tier weight tokens for its heavier display face). The ambient accent sextet is part of every theme's declaration: the six `--color-core-accent-*` roles ship as hexes per preset and drive the background blobs and chart series 2–7 together. One pure composer, `presetOverrides(preset, theme)`, turns a preset into its exact override map; the playground's live preview and the generated stylesheets both call it, so the preview and the shipped theme cannot disagree. `scripts/generate-preset-stylesheets.mjs` writes each preset to `src/tokens/presets/.css` — an `html[data-brand=""]` block carrying the light declarations and an `html[data-brand=""][data-theme="dark"]` block carrying the dark ones, emitted even when identical so the cascade is self-evident — plus a `presets.css` aggregate that only imports them all. The files ship in the npm package under the `tokens/presets/` subpath. The contract: import `tokens/presets/presets.css` after `tokens/tokens.css`, set one `data-brand` attribute on ``, and the whole app rethemes end to end — light and dark included, zero runtime JavaScript. Specificity does the work: `html[data-brand]` outranks the token files' `:root` and `[data-theme]` blocks, and the preset's dark block outranks its light one. The documentation website loads the bundle from its root layout, so any page rethemes the moment the attribute is set. Two build gates guard the surface. `scripts/validate-preset-stylesheets.mjs` regenerates in memory and byte-compares every file, holds the folder to `THEME_PRESETS` in both directions, and parses one preset's CSS back into declarations to prove it equals the composer's output. `scripts/validate-theme-presets.mjs` is the completeness gate — the "one attribute, full theme" guarantee: every override name must resolve to a real token or primitive, the action family must be overridden or provably intended-default (the brand equals `DEFAULT_BRAND`, which the action lever short-circuits to the shipped token files), the resolved action-primary bg/text pairing must hold WCAG AA 4.5:1 in both themes (a preset that deliberately cannot would be pinned in the script's `SANCTIONED_AA_GAPS` with its ratio and reason, never silently passed — the map is empty today, every shipped preset holds AA), and the density/type/motion/elevation levers must be present on every preset — as must all six ambient accent roles, in both themes, with no intended-default exemption. --- ## Colors ### Token Tiers Never reference `--primitive-*` tokens inside components. Always use the semantic layer (`--color-*`). The chain is enforced in the other direction too: every semantic colour token's value must be a `var(--primitive-*)` reference — never a raw hex/rgba literal — so that overriding a primitive re-themes everything built on it (`scripts/validate-token-references.mjs` fails the build otherwise). The hex values noted throughout this section are the resolved values of those primitives. The primitive colour scales share one shape. The neutral scale and the seven chromatic ramps (red, orange, yellow, green, teal, blue, purple) all run **00–11**, light to dark — relative luminance decreases strictly down every chromatic ramp, build-enforced by `scripts/validate-theme-mirrors.mjs`. Step 07 is each chromatic ramp's hand-drawn key colour; the 00 and 11 end caps are generated tint/shade extensions (the blend method and factors are documented above the ramps in `tokens-primitives.css`). Translucent neutral variants follow the **`-aNN` grammar** — NN is the alpha × 100, so `--primitive-neutral-09-a80` is neutral-09 at 80% opacity — and the suffix is held to the rgba() value's actual alpha by `scripts/validate-token-references.mjs`. ### Action / Brand The action roles are the one token family that splits per theme by design (see Overview): the primary roles run a deep light-mode fill under a light label and invert for dark (the neutral roles stay grey-on-grey in each theme), and hover/active walk away from the page — deepening in light, brightening in dark. - **Primary bg** (`--color-action-primary-bg` — #0E6E8F light / #3CA5C6 dark): Teal. Every primary CTA button fill, focus rings, active input borders, and selected-state fills under the teal selection convention. The most-recognized brand color. - **Primary bg hover** (`--color-action-primary-bg-hover` — #0A4E66 light / #6DBCD6 dark): Hover shift on primary buttons. - **Primary bg active** (`--color-action-primary-bg-active` — #052F3E light / #9ED4E5 dark): Press/active shift on primary buttons. - **Primary text** (`--color-action-primary-text` — #CFEAF3 light / #052F3E dark): Text/icon color on the primary fill — light teal on the deep light-mode fill, deep teal on the light dark-mode fill. - **Primary text active** (`--color-action-primary-text-active` — #F1F1F1 light / #052F3E dark): Text on hovered/active primary button. - **Primary border** (`--color-action-primary-border` — #052F3E light / #3CA5C6 dark): Outline on secondary (outlined) Buttons and CircularButtons. - **Secondary border** (`--color-action-primary-border-secondary` — #0E6E8F light / #2C9AB9 dark): Brighter border step — the completed-step border and connector in Stepper. - **Tertiary border** (`--color-action-primary-border-tertiary` — #0E6E8F light / #6DBCD6 dark): Hover ring on RadioButton. - **Tertiary text** (`--color-action-primary-text-tertiary` — #0A4E66 light / #6DBCD6 dark): Teal-coloured text for tertiary/ghost button labels. - **Passive bg** (`--color-action-passive-bg` — rgba(241,241,241,0.01)): Near-transparent ghost button fill. - **Passive bg hover** (`--color-action-passive-bg-hover` — rgba(214,214,214,0.8)): Gray hover on ghost/tertiary buttons. - **Passive text** (`--color-action-passive-text` — #050505 light / #F1F1F1 dark): Ghost button label color. - **Neutral bg** (`--color-action-neutral-bg` — #D6D6D6 light / #232323 dark): Solid grey fill for the `neutral` button variants — unlike passive, the background is always shown at rest. - **Neutral bg hover** (`--color-action-neutral-bg-hover` — #BCBCBC light / #303030 dark): Hover shift on neutral buttons — deepening in light, brightening in dark, like the primary family. - **Neutral bg active** (`--color-action-neutral-bg-active` — #A2A2A2 light / #6D6D6D dark): Press/active shift on neutral buttons. - **Neutral text** (`--color-action-neutral-text` — #050505 light / #F1F1F1 dark): Text/icon color on the neutral fill. ### Surfaces - **Page primary** (`--color-bg-page-primary` — #F1F1F1 light / #050505 dark): The floor of every screen. - **Container primary** (`--color-bg-container-primary` — #FFFFFF light / rgba(14,14,14,0.8) dark): First elevation above page — sidebars, section bands, card fills. In light mode this is crisp white lifting off the gray page floor. - **Container secondary** (`--color-bg-container-secondary` — #F1F1F1 light / #303030 dark): Second elevation — nested containers, divider fills. - **Container tertiary** (`--color-bg-container-tertiary` — #D6D6D6 light / #232323 dark): Third elevation — pressed states, control tracks (Slider, ProgressBar, Meter, Spinner, Gauge), deepest nesting. - **Container border** (`--color-bg-container-border` — #D6D6D6 light / #232323 dark): Hairline borders on containers. - **Container inverse** (`--color-bg-container-inverse` — #0E0E0E light / #F1F1F1 dark): High-contrast inverted surface — ImageCompare's handle label, the calendar and Gantt "today" markers. Always paired with `--color-text-on-inverse`. - **Glass** (`--color-bg-glass` — rgba(255,255,255,0.9) light / rgba(14,14,14,0.66) dark): The floating-surface fill — deliberately translucent in both themes so the page's colours reach the surface. Always paired with `backdrop-filter: blur(24px)`, which is what keeps content readable through it; the blur radius is a documented constant, not a token. Used by the site chat panel, AppSidebar's floating variant, CommandPalette's panel, and the chart family's tooltips. - **Divider** (`--color-divider` — rgba(214,214,214,0.8) light / rgba(35,35,35,0.8) dark): Horizontal/vertical rule between sections. ### Chat surfaces Chat surfaces get their own colour roles so they can be re-themed without touching the container ramp. The four bubble roles currently alias the container-secondary / text-primary pair — deliberately identical today, separable later; the context fill is its own tint. - **Sent bg** (`--color-chat-bubble-sent-bg` → `--color-bg-container-secondary`): Fill of the person's outgoing bubble. - **Sent text** (`--color-chat-bubble-sent-text` → `--color-text-primary`): Text inside the sent bubble. - **Received bg** (`--color-chat-bubble-received-bg` → `--color-bg-container-secondary`): Fill of a received bubble, when the agent's turn renders as a bubble at all. - **Received text** (`--color-chat-bubble-received-text` → `--color-text-primary`): Text inside the received bubble. - **Context bg** (`--color-chat-context-bg` → `--primitive-neutral-01` light / `--primitive-neutral-09` dark): Fill of the Composer's context note — the quietest tint per theme, the nearest neutral to each shell that still separates from it. Its own role rather than a container alias because it deliberately sits off the container ramp. ChatMessage consumes only the four bubble roles above — never the container tokens directly. Teal is never a bubble fill; the action colour keeps its CTA meaning. ### Calendar surfaces EventCalendar's day cells and event pills get their own colour roles, for the same reason chat surfaces do — tunable without touching the container ramp. The family exists because the dark container ramp's steps are too far apart for calendar density: a `#303030` cell field glares against the near-black calendar container, and a hover that lands between the cell and pill fills swallows both. Cells rest one quiet step off the container and step one gentle notch away from the pill fill on hover — lighter in dark, darker in light; a hovered cell keeps its hover while the pointer is on a pill inside it, so the pill's own hover fill and hover-only border ring are what separate it. - **Cell bg** (`--color-calendar-cell-bg` — `--primitive-neutral-01` light / `--primitive-neutral-08-a80` dark): Resting fill of an in-month day cell. - **Cell bg hover** (`--color-calendar-cell-bg-hover` — `--primitive-neutral-02-a80` light / `--primitive-neutral-07-a80` dark): The clickable cell's hover — one gentle step lighter in dark, one gentle step darker in light, always away from the pill fill. - **Event bg** (`--color-calendar-event-bg` → `--color-bg-container-primary`): Resting fill of an event pill — the calendar container's own surface, so pills read as windows down to it. - **Event bg hover** (`--color-calendar-event-bg-hover` → `--color-calendar-cell-bg`): A hovered pill takes the *resting* cell tint — always one step off the hovered cell it sits on (darker than that cell in dark, lighter in light). The "+N more" overflow row's hover shares it, so every interactive row inside a cell separates the same way. - **Event border** (`--color-calendar-event-border` — `--primitive-neutral-04` light / `--primitive-neutral-06` dark): The hover-only hairline ring on the pill under the pointer — an obvious mid-grey that reads against both cell states, while resting pills carry a transparent border so the ring appears with no layout shift. Its own role because the container border colour sinks into the dark cell fill. ### Overlay & Controls - **Scrim** (`--color-scrim` — rgba(0,0,0,0.5) light / rgba(0,0,0,0.7) dark): Modal backdrop behind Dialog, AlertDialog, Drawer and CommandPalette. Darker in dark mode so the modal still separates from the near-black floor. - **Control thumb** (`--color-control-thumb` — chains to `--color-action-primary-text` in both themes): The circular thumb inside toggle switches (ToggleSwitch, SelectionCard's toggle indicator). Riding the on-action ink means every theme's AA-held action pairing keeps the thumb legible on its track — a light action fill (Smoke, Volt) gets a dark thumb automatically, where a fixed near-white value vanished into it. ### Text - **Primary** (`--color-text-primary` — #050505 light / #F1F1F1 dark): Headlines and primary content. - **Secondary** (`--color-text-secondary` — #303030 light / #BCBCBC dark): Emphasized body, card subheadings. - **Tertiary** (`--color-text-tertiary` — #6D6D6D light / #A2A2A2 dark): Labels, helper text, captions. - **Inverse** (`--color-text-inverse` — #A2A2A2 light / #303030 dark): De-emphasized secondary labels; inverts in dark mode. - **On inverse** (`--color-text-on-inverse` — #F1F1F1 light / #0E0E0E dark): Text sitting on `--color-bg-container-inverse` surfaces (ImageCompare's handle label, the "today" markers). ### Icons - **Primary** (`--color-icon-primary` — #6D6D6D light / #D6D6D6 dark): Default icon fill — tertiary buttons, input icons, nav icons. - **Secondary** (`--color-icon-secondary` — #A2A2A2 light / #A2A2A2 dark): De-emphasized icons. ### Status (stable across themes — backgrounds invert, borders and text swap to their dark-mode pairs) | Variant | bg (light) | border | text (light) | bg (dark) | text (dark) | |---|---|---|---|---|---| | `positive` | #ECFCF7 | `#06D6A0` | #024336 | #024336 | #ECFCF7 | | `warning` | #FFF3EC | `#EF8247` | #552716 | #552716 | #FFF3EC | | `error` | #FDEFF3 | `#EF476F` | #571727 | #571727 | #FDEFF3 | | `info` | #EEF3FD | `#1E47B0` | #081633 | #081633 | #EEF3FD | | `neutral` | #D6D6D6 | `#303030` | #232323 | #232323 | #F1F1F1 | Each role also carries an **icon step** (`--color-status--icon`): the glyph colour for status indicators sitting on plain container surfaces (AgentPlan's step indicators, ToolCall's state glyph, SourceTrail's rows). The text step is tuned for its tinted status background and washes out on a bare container — in dark mode the near-white text tints all read as grey. Light uses the deep inks — green-08 #05A67C, orange-08 #C65E33, red-08 #C93A5C, blue-06 #345AC4, neutral-06 #6D6D6D — and dark brightens to mid-ramp hues that hold at least 3:1 on the dark container floor: green-07 #06D6A0, orange-07 #EF8247, red-06 #F16385, blue-05 #5475D4, neutral-04 #A2A2A2. ### Trend (theme-split — the "number went up / went down" role) - Up: `--color-trend-up` — #024336 (green-10) light / #06D6A0 (green-07, the mint accent) dark - Down: `--color-trend-down` — #571727 (red-10) light / #EF476F (red-07, the coral accent) dark Stat deltas and any table mover colour through these, never through the accents directly: on light surfaces the vivid accents fall below readable contrast, so the light half uses the deep status inks, while the dark half keeps the accents, which read well on dark fills. The role exists so that "went up" has one colour everywhere it appears. ### Core Accents (data-viz, decorative — not for semantic status) - Coral: `--color-core-accent-coral` #EF476F - Amber: `--color-core-accent-amber` #EF8247 - Gold: `--color-core-accent-gold` #FFD166 - Mint: `--color-core-accent-mint` #06D6A0 - Cobalt: `--color-core-accent-cobalt` #1E47B0 - Violet: `--color-core-accent-violet` #9E47EF ### AI (reserved for AI entry points and surfaces) The red → blue → teal gradient is the system's "a model answers here" signal, the AI counterpart to the action teal: ordinary actions keep the flat `--color-action-primary-bg`, AI affordances carry the gradient, and the gradient is never used for an ordinary action's job — or decoratively. Inside shared list chrome the reservation changes form rather than lapsing: an AI affordance in a uniform list never restyles its own row (a one-off row treatment would break the list before it signalled anything), but it may wear the gradient as a **passive mark** — a non-interactive ringed badge at the row's trailing edge, signalling the destination without touching the row's shape. The site palette's ask-the-chat row is the reference: its label stays the visitor's own query in the list's plain face, and the AI-ring chip rides the CommandPalette `trailing` slot (see that spec for the slot's contract). Always used as gradient stops (AiButton's ring and glow are the reference), never as flat fills for ordinary chrome. | Token | Light | Dark | |---|---|---| | `--color-ai-gradient-start` | `red-05` #F37F9B | `red-05` #F37F9B | | `--color-ai-gradient-mid` | `blue-05` #5475D4 | `blue-05` #5475D4 | | `--color-ai-gradient-end` | `teal-07` #118AB2 | `teal-07` #118AB2 | | `--color-ai-button-bg` | `neutral-00` #FFFFFF | `true-black` #000000 | One luminous set serves both themes: the stops are bright enough to stay luminous on dark surfaces, while the deeper inks the light theme once used read as a heavy dark border on white. The teal stop sits deeper than the red and blue ones so the gradient ends on the same weight the action colour carries. The family carries one solid fill alongside the stops: `--color-ai-button-bg` (`neutral-00` #FFFFFF light / `true-black` #000000 dark), the AI button's field. It is the theme's extreme surface — brighter than the light page floor, deeper than the dark one — so the AI entry point punches out of whatever it floats over rather than frosting into it. Reserved with the rest of the family: it fills AiButton's pill and the passive marks that wear its face (the site palette's ask chip), nothing else. --- ## Typography ### Font Family The shipped theme resolves every role to **Nunito Sans**. No serif face, and no bundled monospace face — code contexts (CodeBlock, ToolCall names, Prose inline code) use the system mono stack codified as `--font-family-code`. The main font stack is `'Nunito Sans', sans-serif` via `--font-family-primary`. Nunito Sans is a rounded humanist sans-serif. The rounded terminals give UI elements a friendly, approachable quality without sacrificing technical clarity. Inter is an acceptable substitute for prototyping; avoid Helvetica or Arial, which strip the rounded character. **Family roles.** No type-scale step references `--font-family-primary` directly. The scale chains through two role aliases in `tokens-typography.css`, split along the tier boundary the Hierarchy table below draws: | Role token | Resolves to | Feeds | |---|---|---| | `--font-family-heading` | `var(--font-family-primary)` | The display and heading tiers — Mega 1/2, Display 1/2, Sub Display, Heading 1–3 | | `--font-family-body` | `var(--font-family-primary)` | The body tiers — Title Body, Paragraph Em, Paragraph, Paragraph SM (+ Em), Overline, Caption | Both roles default to the primary family, which is what keeps the three levers coherent: override `--font-family-primary` and the whole system re-fonts as one face (this site's position); override `--font-family-heading` alone and headings take a display face while running text keeps the primary; override both roles and the primary token stops mattering. Title Body sits on the body role deliberately — it is a bold label inside working UI (card titles, table column heads), and a consumer pairing a serif display face with a sans text face wants that label in the text face, not the serif. **Sourcing.** The typeface is deliberately not bundled with the npm package. The website self-hosts it via `next/font/google` (fetched from Google Fonts at build time and served first-party), Storybook loads it with a Google Fonts ``, and package consumers load it however their stack prefers — then swap the whole system to another face by overriding `--font-family-primary`, or split faces through the family roles above. Material Symbols Rounded, by contrast, ships inside the package as a self-hosted woff2, so icons need no external setup. ### Type scale ladders Every style bundle's `-size` (and pixel `-line-height`) resolves through two shared ladders in `tokens-typography.css`, named by the same rule as the spacing scale (rank = px / 4 x 100): `--font-size-300` (12px) up to `--font-size-3300` (132px), and `--font-line-height-400` (16px) up to `--font-line-height-1100` (44px). This is the type-size unlock: override a ladder step and every tier that reads it rescales together, without touching the tier bundles. The display tiers' unitless leadings (0.92-1.15) are ratios, not lengths, and stay in their bundles. ### Hierarchy | Token prefix | Size | ≤768px | Weight | Line Height | Letter Spacing | Use | |---|---|---|---|---|---|---| | `--font-mega-1-*` | 132px | 64px | 300 | 0.92 | +2% | Marketing hero — never in app UI | | `--font-mega-2-*` | 116px | 56px | 300 | 0.92 | +2% | Marketing hero — never in app UI | | `--font-display-1-*` | 96px | 48px | 300 | 1.05 | +2% | Large marketing section heads | | `--font-display-2-*` | 64px | 40px | 300 | 1.1 (1.15 ≤768px) | +1.5% | Marketing section heads | | `--font-sub-display-*` | 30px | 24px | 300 | 44px (36px ≤768px) | +1.5% | Sub-section heads on marketing pages | | `--font-heading-1-*` | 30px | — | 600 | 44px | +1.5% | Page-level h1 in app/docs | | `--font-heading-2-*` | 26px | — | 600 | 32px | +1.5% | Section headings in app/docs | | `--font-heading-3-*` | 22px | — | 600 | 28px | +1.5% | Sub-section headings in app/docs | | `--font-title-body-*` | 16px | — | 600 | 24px | −1% | Card titles, table column heads, bold labels | | `--font-paragraph-emphasis-*` | 16px | — | 500 | 24px | −1% | Emphasized body, button labels, input labels | | `--font-paragraph-*` | 16px | — | 400 | 24px | 0 | Default running text | | `--font-paragraph-sm-emphasis-*` | 14px | — | 500 | 20px | 0 | Compact button labels, badge text, form helpers (emphasized) | | `--font-paragraph-sm-*` | 14px | — | 400 | 20px | 0 | Secondary body, helper text | | `--font-overline-*` | 14px | — | 600 | 20px | +8% | Uppercase labels — eyebrows, map callout titles, code-language chips | | `--font-caption-*` | 12px | — | 400 | 16px | 0 | Footnotes and disclaimers — the floor of the scale | The ≤768px column is not a separate token set: the same `--font-*-size` tokens re-resolve inside a single `@media (max-width: 768px)` block at the bottom of `tokens-typography.css`. Anything set in display-tier tokens collapses automatically on mobile; the heading and body tiers never step (marked —). The Size and Weight columns, like everything token-owned, are the shipped theme's positions — the presets' `typeScale` lever and weight `extraOverrides` can move them per theme. ### Principles - Mega and Display sizes (Mega 1/2, Display 1/2, Sub Display) are **marketing-only** — they belong on the documentation homepage and landing pages, never inside application UI or component pages. One sanctioned exception: the site chat's welcome ask line is set in `--font-sub-display-*`, because the empty widget is a landing moment, not working UI — the pair reads as small-semibold greeting over large-light invitation, the weight-contrast rule at welcome scale. The exception ends where the conversation starts: nothing in a live thread uses the display tier. - Headings 1–3 use weight 600. Display styles use weight 300 in the shipped theme, and **never bold a display size within a theme** — the lightness is intentional and gives the shipped system its modern, airy character. Weight is a per-preset position like size: a preset may re-pitch the display tiers through its `extraOverrides` (Forest sets them to 600/500 to suit its heavier display face), but nothing inside a theme bolds a display token at the use site. - **Display leading is unitless, and loosens as the size drops**: 0.92 on Mega, 1.05 on Display 1, 1.1 on Display 2 (1.15 on mobile, where the same headline wraps to more lines). Set solid, a display line reads as a poster on one line and closes up on two — and these headlines wrap, because a page title is a sentence. The heading and body tiers state leading in px instead, because at those sizes the line box is a rhythm the whole page snaps to. - Positive letter-spacing (+1.5–2%) applies to all display and heading sizes. Negative letter-spacing (−1%) applies to title-body and paragraph-em — this tightening is what makes UI labels feel crisp. - Buttons use `--font-paragraph-emphasis-*` (default) and `--font-paragraph-sm-emphasis-*` (compact). Always weight 500 on interactive controls. - Overline is the uppercase label face, and always pairs with `text-transform: uppercase` at the use site — the tokens set the metrics, never the casing. Its +8% tracking is the one positive letter-spacing outside the display and heading tiers, because capitals at label size need air to stay legible. A component may keep the metrics and swap the family (MapCallout sets its title in the code face). - Caption (12px) is the floor, and it is for text the reader can find but never has to read to use the screen: the site chat's disclaimer line, a footnote under a chart. Never on a control, never for helper text (that is Paragraph SM), never for running copy. --- ## Page Layout & Heading Hierarchy This section documents how to apply the typographic scale when building new pages in the documentation website. Following these rules ensures every page reads with the same visual hierarchy. ### Heading Roles | Level | Token | Size | Weight | Role | |---|---|---|---|---| | Page title (`h1`) | `--font-display-2-*` | 64px | 300 | Route title — rendered once per page at the top, outside the markdown body | | Major section (`h2`) | `--font-sub-display-*` | 30px | 300 | Top-level content sections (e.g. Colors, Typography) | | Sub-section (`h3`) | `--font-heading-3-*` | 22px | 600 | Named groupings within a section (e.g. Token Tiers, Action / Brand) | | Minor heading (`h4`) | `--font-title-body-*` | 16px | 600 | Inline labels or additional sub-groups | ### The Weight-Contrast Rule **Weight contrast is the primary differentiator between adjacent heading levels — not size alone.** - `h2` is 30px / weight 300 (light). `h3` is 22px / weight 600 (bold). The 8px size gap alone is not enough — the jump from 300 → 600 is what makes the hierarchy unmistakable at a glance. - Never use the same weight for two consecutive heading levels. A heading that is only slightly smaller than the one above it, at the same weight, will look like a duplicate rather than a sub-item. - The correct pairing is always: **light heading above, bold heading below** at the major → minor transition. ### Section Dividers `h2` elements carry a `border-bottom: var(--border-025) solid var(--color-divider)` by default to visually close the preceding section. Do not insert `
` elements between sections — they duplicate the divider. The border on `h2` is the only section separator needed. **The header-divider rhythm is fixed**: heading, then `--padding-500` (20px) of clearance, then the rule, then `--gap-1000` (40px) before the section's content. The rule belongs to the heading, so the tight side is above it and the generous side is below — inverted spacing (a rule floating far under its heading, or content hugging the rule) reads as the rule labelling the content instead. SectionTitle owns the heading-to-rule half; the page's section layout owns the 40px below, usually as the section container's gap. A page whose sections run a tighter internal gap must make up the difference on the divider itself (margin-bottom on the title — /overview and /docs/get-started are the precedent) rather than letting the rule sit closer to the content than everywhere else. The hand-rolled equivalents (the case-study and journal `resumeSectionHeader`-style headers) follow the same geometry. The one deliberate exception is markdown article bodies (the /blueprints renderers — see Applying to Markdown Pages below): their h2s head running article copy, not page sections, so they run a tighter internal rhythm (8px above the rule, 16px below) that would read as page-section spacing nowhere else. ### Applying to Markdown Pages When a page renders markdown (via `react-markdown` or similar), apply these heading styles using `:global()` selectors scoped to the markdown body container: ```css /* h2 — major section, light and airy */ .markdownBody :global(h2) { font-size: var(--font-sub-display-size); /* 30px */ font-weight: var(--font-sub-display-weight); /* 300 */ padding-bottom: var(--primitive-padding-200); /* 8px above the rule */ border-bottom: var(--border-025) solid var(--color-divider); margin-top: var(--gap-1500); /* 60px above, 40px on mobile — semantic, so the section rhythm collapses with the token */ margin-bottom: var(--primitive-gap-400); /* 16px below */ } /* h3 — sub-section, bold contrast */ .markdownBody :global(h3) { font-size: var(--font-heading-3-size); /* 22px */ font-weight: var(--font-heading-3-weight); /* 600 */ margin-top: var(--primitive-gap-1000); /* 40px above */ margin-bottom: var(--primitive-gap-200); /* 8px below */ } /* h4 — minor heading, same weight as h3, smaller size */ .markdownBody :global(h4) { font-size: var(--font-title-body-size); /* 16px */ font-weight: var(--font-title-body-weight); /* 600 */ margin-top: var(--primitive-gap-400); margin-bottom: var(--primitive-gap-100); } ``` ### Responsive Collapse The display tier collapses **in the token layer**, once, at 768px (see the Hierarchy table): page titles (`--font-display-2-*`) go 64px → 40px and section heads (`--font-sub-display-*`) go 30px → 24px with no per-page CSS. Pages that reference the tokens are responsive by default — never re-hardcode a mobile font size in a page module. One sanctioned exception, marked with a `ds-allow(typography)` directive at the site: the chat panel's welcome ask line repeats the sub-display step as a *container* query on the panel's own width (`SiteChat.module.css`), because the docked panel is phone-width on desktop windows the viewport media query calls large — the panel wears the phone scale below a 768px container, and only the fullscreen takeover on a wide window keeps the 30px size. It restates the same 24px/36px pair, and the two must move together. - Headings 1–3 and the body tiers do **not** step; 22–30px headings stay readable on phones. - The weight contrast rule still applies; do not change weights at any breakpoint. - The one sanctioned exception: a mega-1 hero (home page, 404) may keep a hand-tuned two-stage ramp (132 → 64 → 40) in its own module, commented as a deliberate override. --- ## Spacing & Layout ### Base Units - **Gap (flex/grid spacing):** 4px-based scale via `--gap-*` tokens. - **Padding (internal element padding):** 2px-based micro scale via `--padding-*` tokens. - **Borders:** 1px hairline (`--border-025`) and 2px emphasis (`--border-050`). ### Gap Scale | Token | Value | Typical Use | |---|---|---| | `--gap-050` | 2px | Tightest inline spacing (icon + label micro-gap) | | `--gap-100` | 4px | Compact component internals | | `--gap-200` | 8px | Standard icon-to-label gap, button icon spacing | | `--gap-300` | 12px | Form field stack spacing | | `--gap-400` | 16px | Card internal element spacing | | `--gap-500` | 20px | Section element spacing | | `--gap-1000` | 40px | Card-to-card spacing, major internal gaps | | `--gap-1500` | 60px (40px ≤768px) | Between component groups | | `--gap-2000` | 80px (60px ≤768px) | Between major page sections | | `--gap-3000` | 120px (80px ≤768px) | Page-level section breaks | The three section-rhythm steps (`xxl`–`xxxxl`) compress one notch down the primitive scale below 768px, in a `@media` block at the bottom of `tokens-light.css` — the same single token-layer breakpoint typography uses. Steps `xl` and below never change. ### Padding Scale | Token | Value | Typical Use | |---|---|---| | `--padding-050` | 2px | Badge vertical padding | | `--padding-100` | 4px | Micro insets | | `--padding-150` | 6px | Compact button/input vertical | | `--padding-200` | 8px | Standard button vertical, badge horizontal | | `--padding-300` | 12px | Compact button horizontal, compact input horizontal | | `--padding-400` | 16px | Standard input horizontal, card inner padding baseline | | `--padding-500` | 20px | Standard button horizontal | | `--padding-1000` | 40px | Large card insets | | `--padding-1500` | 60px (40px ≤768px) | Section-level insets | ### Layout Philosophy Whitespace communicates hierarchy. Dense elements use micro-gaps (2–8px); comfortable reading areas use md/lg gaps (16–20px); major layout regions use xl–xxxxl (40–120px). The system relies on spacing contrast rather than dividers — overuse of `--color-divider` is a design smell. --- ## Composition Tokens constrain values; this section constrains choices. Element-level rules (colors, radii, type) make components consistent — these rules make **pages** consistent. Every rule here is stated so that a page assembled from the components lands right on the first pass, without per-page taste decisions. ### The rhythm ladder Page-level vertical space is a statement of relatedness: the gap between two things says how related they are. The ladder is exhaustive — these five roles are the *only* page-level gaps. A spacing value that is not on the ladder is component-internal spacing, and belongs to a component. | Role | Token | Value | Meaning | |---|---|---|---| | Section break | `--gap-2000` | 80px (60px ≤768px) | Separates page regions. The only gap between sections. | | Heading bind | `--gap-1000` | 40px, flat | Ties a heading to the content it introduces. | | Intro bind | `--gap-500` | 20px | Ties a tagline or lede to its body copy. | | Group bind | `--gap-200` | 8px | Ties a label to the items it names. | | Column gutters | `--layout-*` | presets | Gutters and rail widths are facts of the layout, set once at the shell — never per-page choices. | Because the ladder's meanings differ by a full visual step (80 / 40 / 20 / 8), a reader can recover the page structure from spacing alone. Never use an off-ladder gap to "fine-tune" a page-level relationship: if 40px feels wrong between a heading and its content, the content is wrong, not the gap. ### The dashboard rung set Rule 7 below says tiling is a template's decision; a dashboard is that template. When a page is an app shell laying Panels in a grid, the ladder gains one inner rung set, worked out on the labs marketing rebuild and stated here so every dashboard lands on the same density: | Role | Token | Value | Meaning | |---|---|---|---| | Card gutter | `--gap-500` | 20px | Between Panels, in every direction. | | Card inset | `--padding-500` | 20px | A Panel's own padding — the gutter and the inset match, so the grid reads as one fabric. | | Region gap | `--gap-400` | 16px | Between a Panel's regions: header to chart, chart to legend row. | | Cluster gap | `--gap-200` / `--gap-300` | 8 / 12px | Within a cluster: icon to text, tiles in a legend row, buttons in a toolbar. | The recurring mistake this prevents: reaching for the 2px and 4px tokens (`--gap-050`, `--gap-100`) for cluster spacing — both spacing audits on the labs rebuild found the same error, and at cluster scale those values read as touching, not spaced. ### Composition rules 1. **Parent owns spacing.** Siblings are spaced by their container's `gap`, never by margins on the children. A child that carries its own outer margin breaks in every context except the one it was tuned for. 2. **One level of chrome.** Components that carry their own container (charts, tables, calendars) sit bare under a heading — never wrapped in a card. A card wrapper is only for content with no chrome of its own. Two levels of container on one element is always a bug — and so is the over-correction: bare means without a wrapper, never with the component's own borders and background stripped to fake flatness. The component keeps exactly the chrome it ships with. 3. **Dividers are the last resort.** Separation comes from whitespace (the ladder) and containers first; a divider is only for where spacing contrast cannot do the job — long uniform lists, table rows. A divider under a heading that whitespace already separates is decoration, and decoration is not a divider's job. Next to content that draws its own lines (bordered tables, calendars), a section heading always separates by whitespace alone — on a line-heavy page, every added line is noise. 4. **Constrain the column, not the content.** A page has one content max-width; anything wider than its column (tables, diagrams, code) scrolls inside its own container. Never cap the width of a paragraph — cap the column it sits in. 5. **A header is one region.** A page title and its tagline bind at the heading tier (40px), never separated by a section break. The first section break on a page sits *below* the complete header group. 6. **Page rhythm stops at a component's edge.** The ladder governs the space *between* components and headings; a component's internal spacing is its own spec's business. Composing a page never involves reaching into a component to adjust its insides. 7. **Sections stack.** A page is one column of full-width sections; side-by-side placement is for the items *inside* a band (a metrics row of Stats), not for sections themselves. Tiling sections into a grid is a template's decision to make, never a page-by-page one — tested both ways on a dense dashboard, the stack reads calmer and the grid reads cramped. ### Template screens A template rebuilds a whole product screen from the system alone, and the family has conventions beyond the page rules above — worked out across the marketing dashboard, sales pipeline, roadmap planner, and relay console rounds of review, and stated here so the next screen lands right without re-learning them: 1. **A reference product is direction, never a blueprint.** A template may start from another product's screen, but it is composed from this system's idioms, and the standard for every choice is the rendered siblings, not the reference. Furniture the reference has and the family lacks — a status badge beside the title, an avatar cluster in the header, drawn imitation browser chrome, a bespoke rollup strip — does not come along: a piece with no sibling precedent is left out by default, not invented. 2. **One job per control species, one size per row.** A data view's filter row is matching compact `Dropdown` selects (160px, the marketing dashboard's convention) beside the component's own search — never a mix of segmented controls, filter chips, and inputs doing the same job in one row. A *stage toolbar* — the strip floating over an immersive stage, the relay console's precedent — may pair one view-flip `SegmentedControl` with the filter cluster, at the default size with wider selects, because it is read at arm's length over a map rather than at table density; the filters themselves stay one species. What survives every toolbar: controls sharing a row share one size, and no job is done by two species in the same row. 3. **The stage earns the viewport.** The screen's point — the table, the board, the chart — takes the room. A KPI band is a choice, not template furniture: both the sales pipeline and the roadmap planner shipped without one, because the stage deserved the screen. When metric tiles do appear, they follow the dashboard rung set above. 4. **People are initials.** Demo humans render through the Avatar's initials fallback — never generated portrait imagery or photographs. The fiction stays legible as fiction, and the rows stay quiet. 5. **The content column caps at 1680px — unless the stage is the content.** The family's shell centres a 1680px column inside the viewport-tall shell. A screen whose stage *is* the content — a map, a projection instrument — may run the full viewport width instead (the relay console's call); it is a stage decision, made once per screen, never a per-section one. --- ## Shapes ### Border Radius Scale **Concentric containers.** A container wrapping a radiused element derives its own radius as the inner radius plus the inset between them, never an independent value — parallel curves are what make the nesting read deliberate, and a theme that squares the pill token squares both at once. The Composer's shell is the founding case (its spec section owns the derivation); SegmentedControl's track (`calc(var(--radius-pill) + var(--padding-100))`) and the site's BrandSwitcher trigger follow it. At the shipped 999px pill the sum saturates and nothing changes. | Token | Value | Use | |---|---|---| | `--radius-050` | 2px | Reserved — rare micro elements | | `--radius-100` | 4px | Badges (`ds-badge`) | | `--radius-200` | 8px | Small sub-elements, inner nested surfaces | | `--radius-300` | 12px | Inputs, cards (standard), modals | | `--radius-400` | 16px | Large feature cards, hero containers | | `--radius-600` | 24px | Card/EntityCard navigation tiles, Panel, chat bubbles and chat card furniture (MessageCard, ToolCall, AgentPlan, InterruptCard), AppSidebar's floating variant, CommandPalette's panel, oversized hero containers, page-level sections | | `--radius-1200` | 48px | Pill containers, oversized decorative elements | | `--radius-pill` | 999px | All buttons, every variant, toggle thumbs | **Key rule:** Buttons are always `--radius-pill` (pill shape). Inputs are always `--radius-300` (12px), with one sanctioned departure: the Composer shell holds its own component-local `--ds-composer-radius` (29px) for concentric geometry with its send button (see the Composer spec). Card and EntityCard — the navigational tiles — use the larger `--radius-600` (24px) to read as destinations rather than form surfaces, and the chat's card furniture (MessageCard, ToolCall, AgentPlan, InterruptCard) shares that 24px shell with the bubbles around it, so a conversation's surfaces read as one family. This contrast — rounded pill CTAs vs softer-cornered inputs vs generously rounded tiles — is intentional and consistent. ### Icon Size Scale | Token | Value | Use | |---|---|---| | `--icon-size-500` | 20px | Compact controls, inline affordances, chips, list chevrons | | `--icon-size-600` | 24px | Default — the size an icon is unless told otherwise | | `--icon-size-800` | 32px | Feature icons — EntityCard, section headers | | `--icon-size-1200` | 48px | Marketing and empty-state illustration icons | **The icon tile pattern** — an icon on a filled circle, for KPI cards and table cells: a `--radius-pill` disc in `--color-bg-container-tertiary` holding a `--icon-size-500` glyph in `--color-text-primary`, at 40px (stat and KPI headers) or 32px (table cells and list rows). It is a page pattern, not a component: four declarations in module CSS, worked out on the labs marketing rebuild. Components set **`--icon-size`**, never `font-size`: ```css .ds-thing__icon { --icon-size: var(--icon-size-500); } ``` **Node-accepting icon props** — every `icon`-shaped prop in the library (item-level entries like a tab's or a menu row's included) is typed `string | React.ReactNode`: a string renders as a Material Symbol glyph, and any other node renders as-is inside the same wrapper span, minus the `material-symbols-rounded` class. That contract is the bring-your-own-icons paved path — the repo imports no icon set, and a consumer passes Lucide (or any other) elements directly; a custom SVG should draw with `currentColor` so it inherits text colour the way the bundled glyphs do. Props with a string default (TreeView's `folder`/`draft`, Toast's variant glyphs, ThreadPanel's `edit_square`) keep resolving those defaults when the prop is omitted. New components must ship icon props on this contract, never string-only. **Icon style hooks** — the bundled woff2 is the full Material Symbols variable font, and `src/fonts/material-symbols.css` exposes every Google axis as a consumed custom property, settable at any scope: `--material-symbols-fill` (0 line / 1 filled), `--material-symbols-weight` (100–700 stroke), `--material-symbols-grade` (−50–200 contrast). `opsz` is deliberately absent from `font-variation-settings` so `font-optical-sizing: auto` feeds the rendered size into the axis (an explicit value would pin it). Two shipped applications of the hooks: `[data-theme="dark"]` sets grade −25 so light-on-dark glyphs do not bloom, and `.icon-filled` is the one-icon shorthand for the fill axis. These are consumer-override hooks with fallbacks, not registry tokens — the fallback values in that file are their defaults. `.material-symbols-rounded` reads that one property for `font-size`, `width`, and `height` together, so the glyph and its layout box can never disagree. It *consumes* the variable and never declares it — which is what keeps a component rule from colliding with the icon font's own styles. Setting `font-size` directly on an icon is a bug: it changes the glyph without changing the box. **The scale starts at 20px, and that floor is not arbitrary.** Material Symbols is a variable font whose `opsz` (optical size) axis ranges 20–48. Optical sizing thickens strokes as an icon gets smaller; below 20 the axis clamps, so a 14px icon would be drawn with 20px-tuned strokes and scaled down, reading thin and fragile. Every step therefore sits inside the axis range, and `font-optical-sizing: auto` lets the browser track the step automatically — `opsz` is deliberately omitted from `font-variation-settings`, because an explicit axis value there would override the automatic behaviour. **Documented exceptions.** Glyphs that live *inside* a control's geometry rather than acting as icons stay off the scale: the check inside ToggleSwitch's 20×20 thumb and SelectionCard's toggle (14px, 12px compact), and the miniature component mock-ups in the website's component index cards. Each is commented in place. **Dark mode** applies `GRAD: -25` to counter the optical bloom of light glyphs on dark surfaces — it thins strokes without changing glyph width, which is what `wght` would do. --- ## Elevation & Depth The system uses **color-block first, shadow rare** philosophy. Depth is communicated through the container background hierarchy, not box shadows. | Level | Treatment | Use | |---|---|---| | Page floor | `--color-bg-page-primary` — no border, no shadow | Body background, app root | | Container primary | `--color-bg-container-primary` — no border | Sidebars, card fills, section bands | | Container secondary | `--color-bg-container-secondary` — optional `--color-bg-container-border` border | Nested cards, inner panels | | Container tertiary | `--color-bg-container-tertiary` — no shadow | Pressed/active states, deepest UI surfaces | | Input | `--color-input-bg-primary` with `--color-input-border-primary` hairline | Text inputs, textareas, dropdowns | | Status containers | Colored bg + colored border per variant | Alerts, toasts, badges | Standard containers never carry shadows. The only shadows in the system are two semantic elevation tokens, defined per theme (stronger opacity in dark mode so they read against the #050505 floor): - **`--shadow-floating`** (`0 4px 16px rgba(0,0,0,0.12)` light / `0.55` dark) — anchored floating surfaces: menus, popovers, pickers, floating panels, chart tooltips, toasts. Any component that floats over the page without a scrim takes this token; grep `--shadow-floating` for the current set rather than trusting a list here. - **`--shadow-modal`** (`0 8px 32px rgba(0,0,0,0.2)` light / `0.6` dark) — modal surfaces: Dialog, AlertDialog, and Drawer panels and Lightbox's media, paired with the `--color-scrim` backdrop. Never write a literal *elevation* shadow in component CSS — use one of these two tokens or no shadow at all. Hairline inset rings and focus halos built with `box-shadow` are not elevation and are permitted: Swatch and ColorPicker use inset rings to keep pale swatches legible, and Slider's thumb carries a `box-shadow` focus halo. (One documented elevation exception: the interactive Card hover lift — see Do's and Don'ts.) --- ## Motion Motion is quiet and functional — it confirms an interaction, reveals structure, or signals loading. Interface motion never decorates. The one sanctioned exception is the **ambient background**, which is scenery rather than interface: it belongs to no control, communicates no state, and sits behind everything at `z-index: -1` (see the Ambient background section below). The whole vocabulary is defined in `tokens-motion.css` (theme-agnostic, single `:root` like typography): nine `--motion-duration-*` tokens and five `--motion-ease-*` curves. Compose a duration with an easing instead of writing literal values — never hardcode `0.2s ease` in component CSS. **Durations — core scale** (day-to-day UI): | Token | Value | Use | |---|---|---| | `--motion-duration-fast` | 150ms | Quick feedback: hovers, icons, tooltips, nav links | | `--motion-duration-base` | 200ms | The default — color/opacity/border transitions | | `--motion-duration-slow` | 300ms | Structural change: accordion, sidebar width, toast enter | | `--motion-duration-slower` | 600ms | Deliberate page-entrance reveals | **Durations — extended** (special-purpose; named so they stop being magic numbers, but reach for the core four first): `--motion-duration-instant` (75ms, below the threshold where a change reads as motion — it takes the edge off the Composer growing a line, nothing more), `--motion-duration-deliberate` (400ms, carousel slide), `--motion-duration-loop-spin` (1000ms, spinner rotation), `--motion-duration-loop-shimmer` (1800ms, skeleton shimmer and the agent label sweep), `--motion-duration-loop-matrix` (1400ms, the twelve-slot cycle every AgentStatus dot pattern shares). **Easings:** | Token | Value | Use | |---|---|---| | `--motion-ease-standard` | `ease` | General default for color/opacity transitions | | `--motion-ease-emphasized` | `cubic-bezier(0.4, 0, 0.2, 1)` | Size/layout changes (sidebar width, accordion height) | | `--motion-ease-entrance` | `cubic-bezier(0.16, 1, 0.3, 1)` | Expressive decelerate for enter animations (modals, dropdowns, toasts) | | `--motion-ease-linear` | `linear` | Continuous motion (spinner, progress bars) | | `--motion-ease-spring` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Playful overshoot (toggle switch thumb) | **Reduced motion contract:** `tokens-motion.css` collapses every duration token to 0.01ms under `prefers-reduced-motion: reduce`, and a universal guard flattens remaining hardcoded transitions/animations. Components that consume the tokens respect the preference automatically — never write component-level `prefers-reduced-motion` queries. **Migration status:** all component and website CSS composes the tokens — a literal duration or easing survives only where a `ds-allow(motion)` directive sanctions it in place (Skeleton's shimmer curve, the ambient AI glows, the decorative background floats; grep `ds-allow(motion)` for the current set — a count here would only rot). JS-driven timings (hover show/hide delays and the hover exit grace, toast auto-dismiss and the exit-animation unmount sync, carousel autoplay, transient feedback resets, scroll settle, the streaming reveal's rate floor and drain window, the summary panel's think beat and reveal budget…) have their own single home: the shared constants in `src/tokens/motion.ts`, published as `rift-ds/tokens/motion` — the module is the authoritative list. Most are schedule timings rather than animation durations, which the reduced-motion guard deliberately does not touch (the summary panel's think beat is one: it still stages under the preference, because it schedules a swap rather than pacing motion); components use them as defaults, overridable per instance through props. A component that animates from a JavaScript timer or frame loop checks the preference itself, since the CSS guard cannot see JS — or rides a library default that does: the recharts-backed charts animate their marks in under recharts' own `isAnimationActive: 'auto'` guard, which the chart-set spec owns (a literal `true` would override it). A grep for `prefers-reduced-motion` in `src/components` is therefore the inventory of *self-checking* components only (Carousel never starts autoplay under it, and StreamingText skips its reveal so each chunk appears whole; they are examples, not the set) — the delegated recharts set never contains the string. ### Ambient background The website's background is **ShaderField** — the published component, not a bespoke site surface. Its rendering contract is specified in the Components chapter; what follows is only why an animated ambient surface is allowed at all, and how the site composes it: a document-top absolute band (540px standard, 900px under the home page's extended marker, the full viewport only under the full-bleed one) that scrolls away with the page opening rather than following the viewport. Three properties make this an exception that does not erode the rule: - **It is scenery, not interface.** Nothing about it is a signal, so its motion cannot be mistaken for feedback. - **It degrades to the CSS blobs.** The site keeps eight blurred CSS discs painted underneath on every page — ported 1:1 to the shader's coordinate space, so the field and its fallback are the same picture, give or take the framing `crop` gives the field on a narrow viewport — and drives their visibility from the status ShaderField reports. No WebGL2, a lost GPU context, a renderer that stalls before its first frame, or the config's kill switch all land on the same quiet fallback. The blobs are hidden while the renderer is still resolving, rather than painted and then swapped. The deliberate cost is that a machine which cannot run the shader shows bare page floor for that first moment before the blobs fade in. - **It honours reduced motion in JavaScript.** This is the part worth knowing, and it is the component's job rather than the site's: the guard in `tokens-motion.css` is CSS-only and cannot see a `requestAnimationFrame` loop. The rule against component-level `prefers-reduced-motion` queries still holds for everything that consumes the duration tokens; a JS animation loop is outside that contract by construction. Each blob carries a 14–22s drift period inherited from the CSS blobs it replaced, scaled by the config's `speed` parameter — so the cycles you actually see are those periods divided by `speed`, not the raw numbers. Every tuneable value — the eight field parameters and the eight blob definitions — lives in `website/src/data/shader-background.json`, validated against the token registry so the field can never sample a token that does not exist. --- ## Components **Overlay behaviors are shared, not per-component.** The modal overlays (Dialog, AlertDialog, Drawer, CommandPalette, Lightbox) delegate their invisible machinery to the internal hooks in `src/behaviors/` — one implementation of each behavior, so an edge-case fix lands once. The contract: Escape routes through a layer stack and dismisses only the topmost open overlay (a non-dismissible top layer swallows it — nothing beneath can close through a blocking modal); focus is trapped over the *visible* focusable elements, and restored on close or unmount only when the previously focused element still exists in the document; everything outside the open overlay is made `inert`, so a screen reader's virtual cursor cannot browse the page behind a modal; and the page scroll lock has two strategies — `pin` (default: the body is fixed in place at its scroll offset, because iOS Safari ignores `overflow: hidden` on the body — a touch, or a field focusing under the soft keyboard, still scrolls a hidden-overflow page out from under an overlay; counted, so stacked modals release it only when the last one closes) and `cancel-events` (CommandPalette's: the scrollbar stays rendered and scroll input is cancelled outside the panel's own list). The pin's counter is the layer's one published subpath (`rift-ds/behaviors/useScrollLock` — everything else in `src/behaviors/` stays internal): host chrome with overlays of its own joins the same counter through `acquireScrollLock`/`releaseScrollLock`, because two body locks that cannot see each other unlock the page under whichever overlay closes last — a site nav drawer closing beneath an open Dialog is the canonical case, and the website's `lib/scroll-lock.ts` is that consumer. The stack owns the document-level *dismissal* listeners for these five — CommandPalette keeps one listener of its own for the global Cmd+K hotkey, which must hear the keyboard while the palette is closed, and Lightbox one for its gallery arrow keys, gated on open (its spec owns it) — and the non-modal overlays still gate an outside-click listener on their open state until they migrate onto the stack. ### Button **`ds-button`** — The primary interactive element. Always pill-shaped (`--radius-pill`), and the label never wraps (`white-space: nowrap`, shared with AiButton) — a squeezed layout shortens around the button rather than folding the pill into two lines. Text uses `--font-paragraph-emphasis-*` (default) or `--font-paragraph-sm-emphasis-*` (compact). Icon size: 24px (default), 20px (compact). Transitions: background-color, border-color, and opacity at `--motion-duration-base` / `--motion-ease-standard`. A trailing icon (`iconRight`) nudges 2px right on hover at `--motion-duration-fast` / `--motion-ease-entrance` — a small confirmation that the button leads somewhere; never on disabled buttons. Disabled state: `opacity: 0.4`, `cursor: not-allowed` — never hidden. | Variant | Fill | Border | Text | |---|---|---|---| | `primary` | `--color-action-primary-bg` (#0E6E8F light / #3CA5C6 dark) | none | `--color-action-primary-text` (#CFEAF3 light / #052F3E dark) | | `secondary` | transparent | `--color-action-primary-border` (#052F3E light / #3CA5C6 dark) 1px | `--color-text-primary` | | `tertiary` | `--color-action-passive-bg` (near-transparent) | none | `--color-action-passive-text` | | `neutral` | `--color-action-neutral-bg` (#D6D6D6 light / #232323 dark) | none | `--color-action-neutral-text` | | `destructive` | transparent | `--color-core-accent-coral` (#EF476F) 1px | `--color-core-accent-coral` | Hover: primary and secondary → `--color-action-primary-bg-hover`; neutral → `--color-action-neutral-bg-hover`; destructive → fills with its coral border colour. Active: primary and secondary → `--color-action-primary-bg-active`; neutral → `--color-action-neutral-bg-active`. Hover and active walk away from the page — deepening in light mode, brightening in dark — so the pressed fill never sinks toward the floor behind it. `neutral` is the filled-but-quiet option: a solid grey pill for actions that deserve a button's full silhouette without the action teal's weight — unlike `tertiary`, its background is always shown at rest. Sizes: `default` (padding 8px × 20px), `compact` (padding 6px × 12px). **A tertiary button never stands alone in an action row.** Its transparent resting field has no visible edge, so a lone tertiary reads as misaligned text rather than as an action. An action row leads with a primary or secondary button, and tertiary follows it — nav lists and icon rows, where every entry is deliberately passive, are the exception, not action rows. Loading state: `loading` puts a `variant="inherit"` Spinner in the left icon slot (24px default / 16px compact), keeps the variant's full-colour appearance (no disabled dim), blocks interaction (`pointer-events: none`, `cursor: progress`, `disabled` attribute), and sets `aria-busy`. A loading `href` button renders the `