Add visual design language (IBM/Carbon-inspired) and schedule it as M1.5

Defines the visual contract before the design-application work, so M2+ build on settled tokens. - docs/architecture/09-visual-design.md: principles + deliberate divergences (square chrome, free color/theming), token system (IBM Plex type, 8px spacing, role-based color, motion), component conventions, and a source-repo map for extending the research - docs/architecture/visual-specimen.html: standalone kitchen-sink specimen with a live theme x accent switcher; doubles as the tokens.css sandbox - IMPLEMENTATION-PLAN: new M1.5 'Visual design foundation' milestone, plus ground-rule/cross-cutting/reference wiring - index links: 00-overview, CLAUDE.md, AGENTS.md (architecture playbook now 00-09) Applying the design to the M1 surfaces is deferred to a separate session.
2026-08-08 02:02:33 +00:00 · 2026-06-05 00:25:11 +03:00
parent ca54bb66b1
commit 094e5f6e4e
6 changed files with 823 additions and 6 deletions
@@ -59,7 +59,7 @@ src/
 styles/              # Global CSS (tokens, base)
 docs/
 ├── spec/            # Authoritative behavioral specification (00–10) — the WHAT
-├── architecture/    # Architecture playbook (00–08) — the HOW (self-contained)
+├── architecture/    # Architecture playbook (00–09) — the HOW (self-contained)
 └── IMPLEMENTATION-PLAN.md
 ```

@@ -8,8 +8,9 @@ See @AGENTS.md for project overview, architecture rules, and the AI developer pr
 - **[docs/spec/](docs/spec/)** — authoritative behavioral specification (sections 00–10):
  the **what**. This is the contract; implement to it.
 - **[docs/architecture/](docs/architecture/00-overview.md)** — architecture playbook
-  (00–08): the **how** (state, persistence, modals, routing, rendering, inference,
-  relationships, vega-editor techniques). Self-contained — no external repo needed.
+  (00–09): the **how** (state, persistence, modals, routing, rendering, inference,
+  relationships, vega-editor techniques, visual design). Self-contained — no external
+  repo needed.
 - **[docs/IMPLEMENTATION-PLAN.md](docs/IMPLEMENTATION-PLAN.md)** — incremental milestone
  plan (M0–M6), MVP boundary, per-milestone tests + manual checks, and an architecture
  reference index.
@@ -27,7 +27,9 @@ doc before implementing.
 - **Modals via a registry + coordinator + shell** (see [Architecture 03](architecture/03-modal-system.md)),
  not ad-hoc conditional rendering.
 - **CSS Modules + design tokens** (`styles/tokens.css`); themes flip
-  `[data-theme]`. Vega theme follows the UI theme.
+  `[data-theme]`. Vega theme follows the UI theme. The design language behind the
+  tokens — type, spacing, color roles, components, themes — is defined in
+  [Architecture 09](architecture/09-visual-design.md) and established in M1.5.
 - **Editor: Monaco**, **self-hosted from npm + raw `monaco-editor` API** (not the
  CDN loader / `@monaco-editor/react` wrapper — decided; rationale in
  [Architecture 08](architecture/08-vega-editor-techniques.md#decision--monaco-integration-self-hosted-raw-api)).
@@ -44,6 +46,7 @@ doc before implementing.
 |---|-----------|---------|------|
 | **M0** | Skeleton ✅ | Repo builds, tests run, empty shell renders | — |
 | **M1** | **MVP core loop** | Author a Vega-Lite snippet, see it render live, it persists | §02, §03A–C, §04, §09A |
+| **M1.5** | Visual design foundation | Apply the design language: tokens, IBM Plex, restyled M1 surfaces, chart theme | [arch 09](architecture/09-visual-design.md) |
 | **M2** | Editor robustness | Draft/Published, validation, schema autocomplete, fit modes | §03D–E, §04, §07(editor) |
 | **M3** | Datasets | Named reusable data + reference resolution in preview | §05, §03F, §09B |
 | **M4** | Chart Builder | No-JSON chart composition from a dataset | §06 |
@@ -51,7 +54,8 @@ doc before implementing.
 | **M6** | Shell polish | Resize/toggle panes, routing, shortcuts, toasts, a11y, offline | §01, §10 |

 **MVP boundary = end of M1** (a genuinely usable single-user chart authoring loop).
-M2 makes it *robust*; M3–M6 make it *complete*. Ship/dogfood after M1, iterate.
+M1.5 makes it *look right*; M2 makes it *robust*; M3–M6 make it *complete*.
+Ship/dogfood after M1, iterate.

 ---

@@ -109,6 +113,43 @@ preview, and have it survive reload. Single source kind: inline-data specs only

 ---

+## M1.5 · Visual design foundation  →  *make the MVP look like itself*
+
+**Goal:** apply our design language so the running MVP looks deliberate, and every
+later milestone builds on settled tokens instead of placeholders. The expensive part
+(the design decisions) is already done — this milestone is *application*, not
+invention. See [Architecture 09 · Visual Design Language](architecture/09-visual-design.md)
+and the companion `visual-specimen.html`.
+
+**Styles**
+- Port the settled specimen tokens into `styles/tokens.css` (IBM-Plex type scale,
+  8px-based spacing, role-based color, square chrome, motion); light + dark themes
+  via `[data-theme]`.
+- Self-host **IBM Plex Sans + Mono** in `styles/base.css` via `@fontsource`
+  (offline/PWA — never a CDN).
+
+**App**
+- Restyle the four M1 surfaces against the tokens: App shell, SnippetLibrary,
+  SpecEditor (Monaco theme follows `[data-theme]`), LivePreview. Tokens only — no
+  raw hexes, no hardcoded hues in components.
+- Establish the reusable component conventions (buttons, fields, list rows, status,
+  focus ring) that M2–M6 reuse.
+
+**Core**
+- Align `src/core/vega-themes.ts`: chart `Config` per theme + a categorical
+  `range.category` palette (clone `carbon-design-system/carbon-charts` for the
+  sequence — see Architecture 09 §7).
+
+**Tests**
+- Light: the design is mostly visual — a token/theme smoke check, trust the eye.
+
+**Manual checks**
+- The real app looks deliberate in both themes; theme flip repaints UI + chart.
+- Keyboard focus ring visible; text/UI contrast passes AA in light and dark.
+- No placeholder styling remains on the M1 surfaces.
+
+---
+
 ## M2 · Editor robustness

 **Goal:** the editor becomes trustworthy — draft vs published, schema-aware
@@ -223,7 +264,8 @@ the reference.

 **App**
 - Settings **modal** (Appearance/Editor/Performance/Formatting), Apply/Cancel/Reset,
-  dirty indicator; wire render-debounce + theme + date-format through to the app.
+  dirty indicator; wire render-debounce + theme + date-format through to the app
+  (the themes themselves already exist from M1.5 — this adds the switcher UI).
 - Header **Import**/**Export** (direct file dialog / download, no modal).
 - Date formatting util (smart/iso/custom) used by the library list.

@@ -261,6 +303,10 @@ offline reload works; install as standalone; reduced-motion honored.

 ## Cross-cutting, do-as-you-go

+- **Build to the design language:** the foundation lands in M1.5; from M2 on, every
+  new component uses the [Architecture 09](architecture/09-visual-design.md) tokens
+  and conventions — no placeholder styling, no raw hues. Staying on it is the
+  do-as-you-go part.
 - **i18n** (optional, deferred): if translation is wanted, split a portable i18n
  registry (no React) from the app-layer bindings, mirroring the `core` ↔ `app`
  boundary. M1–M6 can ship English-only with date formatting locale-aware (§10).
@@ -286,3 +332,4 @@ The **how** behind each milestone is documented self-containedly in
 | Column type inference + dataset profiling | [06 · Type Inference & Profiling](architecture/06-type-inference.md) |
 | Unique names + import auto-suffix, snippet↔dataset links, rename propagation | [07 · Naming & Relationships](architecture/07-naming-and-relationships.md) |
 | Monaco setup, Vega-Lite schema service, editor patterns mined from vega/editor | [08 · Vega Editor Techniques](architecture/08-vega-editor-techniques.md) |
+| Design language: tokens, type, spacing, color roles, components, themes | [09 · Visual Design Language](architecture/09-visual-design.md) |
@@ -29,6 +29,7 @@
 | 06 | [Type Inference & Profiling](06-type-inference.md) | Pure, portable column-type inference (number/text/date/boolean) and the dataset profile shape. |
 | 07 | [Naming & Relationships](07-naming-and-relationships.md) | Unique-name enforcement + import auto-suffix; the bidirectional snippet↔dataset name link; rename propagation into specs. |
 | 08 | [vega/editor Techniques](08-vega-editor-techniques.md) | Reference brief: borrowable Monaco-schema wiring, vega-embed lifecycle, two-tier validation, and data-flow/debounce techniques distilled from the official Vega-Lite editor — plus where we do better. |
+| 09 | [Visual Design Language](09-visual-design.md) | The *visual* contract: principles inspired by IBM/Carbon, deliberate divergences (square chrome, free color/theming), the token system (Plex type, 8px spacing, role-based color, motion), component conventions, and where to mine the Carbon/IBM source repos for more. Companion: [`visual-specimen.html`](visual-specimen.html). |

 ## The non-negotiable layering (every doc assumes this)

@@ -0,0 +1,203 @@
+# 09 · Visual Design Language
+
+> **Status:** foundational design pass. This is the *visual* contract — the
+> counterpart to `docs/spec/` (behavior) and the rest of `docs/architecture/`
+> (structure). `styles/tokens.css`, `styles/base.css`, component CSS Modules, and
+> `src/core/vega-themes.ts` implement *to this doc*.
+>
+> **Companion:** [`visual-specimen.html`](./visual-specimen.html) — a standalone,
+> openable "kitchen sink" that renders every token and element with a live
+> theme/accent switcher. Edit tokens there first, eyeball them, then port the
+> settled values into `styles/tokens.css`.
+
+Astrolabe's look is **inspired by the IBM Design Language / Carbon**, but Carbon is
+**not a dependency** — we transcribe the values we want and reinterpret the
+principles in our own words. We borrow IBM's *engineered structure*; we keep
+*color and theming free*.
+
+---
+
+## 1. Principles
+
+IBM's four design principles map almost exactly onto Astrolabe's SOUL ("the spec is
+the star; the UI is a thin, considered shell"). Restated for us:
+
+1. **Considered** — *remove everything gratuitous.* No decoration that isn't
+   carrying meaning. Whitespace is a feature.
+2. **Unified** — a *small fixed kit* (one type family, a neutral ramp, one accent,
+   a handful of components) reused systematically. Identity comes from consistency,
+   not novelty per screen.
+3. **Executed** — *everything communicates, including what we leave out.* Alignment,
+   rhythm, and empty space are decisions, not leftovers.
+4. **Progressive** — *every element reduces friction.* If it doesn't help the user
+   read, edit, or find a snippet faster, it doesn't earn its place.
+
+…plus our own, where we part ways with IBM:
+
+5. **Structure is rigorous; color is free.** The grid, type scale, spacing, and
+   square geometry are systematic and fixed. Color, accent, and theming are the
+   *expressive* layer — open, swappable, and meant to be played with.
+
+---
+
+## 2. Deliberate divergences from Carbon
+
+What we **borrow** vs. where we **diverge** — recorded so future readers know these
+were choices, not drift:
+
+| Topic | IBM/Carbon | Astrolabe |
+|---|---|---|
+| Adoption | A framework + component lib | **Inspiration only.** Transcribed tokens, our own components |
+| Structure (grid, type, spacing) | 8px mini unit, modular type scale | **Borrowed wholesale** — it's the rigorous part worth having |
+| UI chrome corners | ~0–2px (near-square) | **Fully square, `radius: 0`** — one notch more austere/engineered |
+| Icons | Rounded exteriors, 2px soft corners + 90° interiors | **Kept rounded** (use Carbon's icon set) — the one warm, human touch |
+| Color | "Blue at the core"; other hues only for purpose | **Dropped.** Color/theming is free and expressive; accent is a token, many themes welcome |
+| Neutrals | Carbon gray ramp | **Borrowed** — accessible, well-tuned, a good legible base |
+| Motion | Productive vs. expressive | **Productive only** — subtle, purposeful, reduced-motion-aware |
+
+---
+
+## 3. Tokens
+
+All tokens are CSS custom properties on `:root`, themed by overriding them on
+`[data-theme]` (and, for accent, `[data-accent]`). The specimen is the live source
+of truth for values until they're ported to `styles/tokens.css`.
+
+### 3.1 Typography — IBM Plex
+
+- **Families:** `IBM Plex Sans` for UI, `IBM Plex Mono` for the editor, code,
+  numeric/tabular data, and inline spec fragments. Self-hosted in production via
+  `@fontsource/ibm-plex-sans` + `@fontsource/ibm-plex-mono` (offline/PWA — never a
+  CDN). The specimen uses a CDN purely for preview convenience.
+- **Scale (px), from Carbon's modular scale:** `12 · 14 · 16 · 18 · 20 · 24 · 28 ·
+  32 · 42`. Body is **14/20** (already our `--font-size-base`). Captions/labels 12.
+- **Weights:** 400 regular, 600 semibold for emphasis/headings; 300 light reserved
+  for large display only.
+- **Breathing room:** Plex *"requires space to breathe."* Don't over-tighten —
+  body line-height ≥ 1.4, default tracking (no negative letter-spacing on text).
+  Flush-left, clear hierarchy.
+
+### 3.2 Spacing — the 8px base unit
+
+IBM's product/web rule: *"the 8px mini unit guides everything."* Every gap, pad,
+and size is a relationship of 8 (with 2/4 as fine sub-steps):
+
+`--space-1: 2px · --space-2: 4px · --space-3: 8px · --space-4: 12px · --space-5:
+16px · --space-6: 24px · --space-7: 32px · --space-8: 48px · --space-9: 64px`.
+
+> Note: this renumbers our current M0 scale to anchor on 8. The migration is
+> mechanical (search/replace `--space-*` usages) and lands with the design pass.
+
+### 3.3 Color — role-based, theme-free
+
+Color is expressed as **roles**, never raw hexes, so themes can repaint the whole
+UI by swapping one set of values. Borrowed from Carbon's layering model:
+
+| Role token | Meaning |
+|---|---|
+| `--bg` | App canvas (lowest layer) |
+| `--layer-01` / `--layer-02` | Raised surfaces (panels, cards, popovers) — elevation by lightness step, not shadow |
+| `--border` / `--border-strong` | Subtle and prominent separators |
+| `--text` / `--text-secondary` / `--text-placeholder` | Text hierarchy |
+| `--accent` / `--accent-hover` / `--accent-contrast` | The expressive accent — **swappable**; UI must never hardcode a hue |
+| `--focus` | Focus-ring color (defaults to `--accent`) |
+| `--support-error / -success / -warning / -info` | Status only — color = meaning |
+
+- **Neutrals** use the Carbon gray ramp (`#f4f4f4 … #161616`) — accessible and
+  legible. **Accent and theming are open**: the specimen ships several accents
+  (indigo, teal, amber, rose) and light/dark themes to prove the system is free,
+  not blue-bound. Pick, add, or invent themes freely.
+- **Status palette** (borrowed, stable): error `#da1e28`, success `#198038`,
+  warning `#f1c21b`, info `#0043ce` — tuned per theme for contrast.
+- **Contrast:** target WCAG AA (4.5:1 text, 3:1 large/UI). Accent-on-`--bg` and
+  text-on-`--accent` must both pass for any shipped theme.
+
+### 3.4 Shape & elevation
+
+- `--radius: 0` for all chrome (buttons, fields, cards, panels). Square is the look.
+- **Icons are exempt** — they keep their rounded geometry (Carbon icon set, 2px
+  corners). Icons are SVG, not chrome, so `--radius` doesn't touch them.
+- **Elevation is lightness, not shadow.** Stack `--bg → --layer-01 → --layer-02`.
+  Shadows, if ever used, are minimal and reserved for true overlays (modals,
+  popovers).
+- **Borders are 1px**, `--border` subtle by default.
+
+### 3.5 Motion
+
+- **Durations (productive):** `--dur-fast: 70ms`, `--dur-fast-2: 110ms`,
+  `--dur-moderate: 150ms`. Nothing slower in the core UI.
+- **Easing:** standard productive `cubic-bezier(0.2, 0, 0.38, 0.9)`.
+- **Restraint:** animate only what's vital (state changes, entrances of meaningful
+  elements). No gratuitous motion. All transitions are already neutralized under
+  `@media (prefers-reduced-motion: reduce)` in `base.css`.
+
+---
+
+## 4. Component conventions
+
+- **Buttons:** square, 32px (compact) / 40px (default) tall. Variants: **primary**
+  (filled `--accent`), **secondary** (bordered), **ghost** (text-only),
+  **danger** (filled `--support-error`). 600-weight label. Clear hover/active and
+  a visible focus ring.
+- **Focus ring:** a 2px `--focus` outline (offset 1–2px). Always visible on
+  keyboard focus — accessibility is non-negotiable (principle 4).
+- **Fields** (text, textarea, select, search): square, 1px `--border`, `--layer-01`
+  fill, accent border + focus ring on focus. Mono font for spec/JSON inputs.
+- **List rows** (snippet library): compact, full-row hover (`--layer-01`),
+  active row marked by an accent left-border + `--layer-01` fill, secondary
+  metadata in `--text-secondary`. Row-level actions reveal on hover.
+- **Status indicators:** a small dot/tag for draft vs. published; a dataset glyph
+  when references exist. Status colors only.
+- **Toasts:** `--layer-02`, 1px border in the support color, square, brief.
+- **Code / editor surfaces:** `--font-mono`, `--layer-01`, generous line-height.
+
+---
+
+## 5. Charts (`src/core/vega-themes.ts`)
+
+The chart `Config` is themed to match the app, per theme:
+
+- `background: transparent` (inherits the surface), Plex font for titles/labels,
+  axis/grid colors derived from the neutral ramp + `--text-secondary`.
+- **Categorical palette** for `range.category` is part of the *free color* layer —
+  a distinct, colorblind-sequenced set (Carbon's data-viz palette is a good
+  starting point, but not mandatory). Light and dark variants. This is where
+  expressive color earns its keep.
+- Config is applied **at embed time**, never baked into the user's stored spec.
+
+---
+
+## 6. Implementation map
+
+| Artifact | Role |
+|---|---|
+| [`visual-specimen.html`](./visual-specimen.html) | Living preview + token sandbox. Iterate here first |
+| `styles/tokens.css` | The settled tokens (currently placeholders) — port from the specimen |
+| `styles/base.css` | Font wiring (`@fontsource`), reset, reduced-motion |
+| component `*.module.css` | Consume tokens only; no raw hexes, no hardcoded hue |
+| `src/core/vega-themes.ts` | Chart `Config` per theme; categorical palettes |
+
+**Order of work:** settle the specimen → port tokens to `tokens.css` → self-host
+Plex in `base.css` → restyle existing M1 components against the tokens → align
+`vega-themes.ts`. Verify by rendering the real app, not just the specimen.
+
+---
+
+## 7. Inspiration sources — where to look for more
+
+We treat IBM/Carbon as inspiration, so we mine its **source repos**, not the live
+doc sites. The sites (`carbondesignsystem.com`, `ibm.com/design/language`) are
+JS-rendered and don't fetch cleanly — **clone the repo and read it locally instead.**
+Convention: clone under `/Users/oleh/code/reference/` with
+`git clone --depth 1 https://github.com/carbon-design-system/<repo>.git`.
+
+| Need | Repo | Where it lives |
+|---|---|---|
+| **Principles / the "why"** (philosophy, 2x grid, color rationale, type, motion, icon geometry) | `design-language-website` | `src/pages/`: `philosophy/principles.mdx`, `2x-grid.mdx`, `color.mdx`, `typography/*.mdx`, `animation/overview.mdx`, `iconography/ui-icons/design.mdx` (~1.4 GB clone — image-heavy; the MDX is what we want) |
+| **Token values** (gray/blue ramps, type scale, font families, motion durations/easings, theme role→value maps) | `carbon` | `packages/colors/src/colors.ts`, `packages/type/src/{scale,fontFamily,fontWeight}.ts`, `packages/motion/src/index.ts`, `packages/themes/src/{white,g100}.ts` |
+| **Component-level usage guidance** | `carbon-website` | `src/pages/**/*.mdx` |
+| **Data-viz categorical chart palette** (for `vega-themes.ts` `range.category`) | `carbon-charts` | *not yet cloned* — clone when we do the chart-theming pass |
+
+> The decisions we made *from* these sources are captured above (§1–6) and in the
+> specimen, so we don't need to re-derive them — only return to the repos to extend
+> the research (e.g. the chart palette, or a component pattern we haven't tackled).
@@ -0,0 +1,565 @@
+<!doctype html>
+<html lang="en" data-theme="light" data-accent="indigo">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Astrolabe · Visual Specimen</title>
+
+    <!--
+      Standalone design specimen for docs/architecture/09-visual-design.md.
+      NOT part of the app — a kitchen sink to eyeball the tokens and catch
+      technical bugs before porting values into styles/tokens.css.
+
+      Fonts: IBM Plex via CDN for preview convenience ONLY. Production self-hosts
+      via @fontsource (offline/PWA). If offline, system fallbacks kick in.
+    -->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@300;400;600&display=swap"
+      rel="stylesheet"
+    />
+
+    <style>
+      /* ============================================================
+         TOKENS — the design contract (docs/architecture/09)
+         ============================================================ */
+      :root {
+        /* Type */
+        --font-sans: 'IBM Plex Sans', system-ui, -apple-system, sans-serif;
+        --font-mono: 'IBM Plex Mono', ui-monospace, 'SF Mono', Menlo, monospace;
+
+        /* Spacing — 8px base unit (2/4 as sub-steps) */
+        --space-1: 2px;
+        --space-2: 4px;
+        --space-3: 8px;
+        --space-4: 12px;
+        --space-5: 16px;
+        --space-6: 24px;
+        --space-7: 32px;
+        --space-8: 48px;
+        --space-9: 64px;
+
+        /* Shape — square chrome */
+        --radius: 0px;
+        --border-width: 1px;
+
+        /* Motion — productive only */
+        --dur-fast: 70ms;
+        --dur-fast-2: 110ms;
+        --dur-moderate: 150ms;
+        --ease: cubic-bezier(0.2, 0, 0.38, 0.9);
+
+        /* Status (light defaults; overridden in dark) */
+        --support-error: #da1e28;
+        --support-success: #198038;
+        --support-warning: #f1c21b;
+        --support-info: #0043ce;
+        --on-status: #ffffff;
+      }
+
+      /* --- Neutral roles: LIGHT theme (Carbon gray ramp) --- */
+      [data-theme='light'] {
+        --bg: #ffffff;
+        --layer-01: #f4f4f4;
+        --layer-02: #e0e0e0;
+        --border: #e0e0e0;
+        --border-strong: #c6c6c6;
+        --text: #161616;
+        --text-secondary: #525252;
+        --text-placeholder: #a8a8a8;
+      }
+
+      /* --- Neutral roles: DARK theme --- */
+      [data-theme='dark'] {
+        --bg: #161616;
+        --layer-01: #262626;
+        --layer-02: #393939;
+        --border: #393939;
+        --border-strong: #525252;
+        --text: #f4f4f4;
+        --text-secondary: #a8a8a8;
+        --text-placeholder: #6f6f6f;
+        --support-error: #fa4d56;
+        --support-success: #42be65;
+        --support-warning: #f1c21b;
+        --support-info: #78a9ff;
+        --on-status: #161616;
+      }
+
+      /* --- Accent: the FREE, swappable layer (theme-aware) --- */
+      [data-accent='indigo'] { --accent: #5b54e6; --accent-hover: #4a43d6; --accent-contrast: #fff; }
+      [data-accent='teal']   { --accent: #0f766e; --accent-hover: #0c5f59; --accent-contrast: #fff; }
+      [data-accent='amber']  { --accent: #b45309; --accent-hover: #92400e; --accent-contrast: #fff; }
+      [data-accent='rose']   { --accent: #be123c; --accent-hover: #9f1239; --accent-contrast: #fff; }
+      /* Brighter accents on the dark canvas (compound selector wins on specificity) */
+      [data-theme='dark'][data-accent='indigo'] { --accent: #8b85f0; --accent-hover: #a29bf5; --accent-contrast: #161616; }
+      [data-theme='dark'][data-accent='teal']   { --accent: #2dd4bf; --accent-hover: #5eead4; --accent-contrast: #161616; }
+      [data-theme='dark'][data-accent='amber']  { --accent: #fbbf24; --accent-hover: #fcd34d; --accent-contrast: #161616; }
+      [data-theme='dark'][data-accent='rose']   { --accent: #fb7185; --accent-hover: #fda4af; --accent-contrast: #161616; }
+
+      :root { --focus: var(--accent); }
+
+      /* ============================================================
+         BASE
+         ============================================================ */
+      * { box-sizing: border-box; }
+      html, body { margin: 0; }
+      body {
+        font-family: var(--font-sans);
+        font-size: 14px;
+        line-height: 1.45;
+        color: var(--text);
+        background: var(--bg);
+        transition: background var(--dur-moderate) var(--ease), color var(--dur-moderate) var(--ease);
+      }
+      @media (prefers-reduced-motion: reduce) {
+        *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
+      }
+      h1, h2, h3, h4 { margin: 0; font-weight: 600; line-height: 1.25; }
+      code, pre, .mono { font-family: var(--font-mono); }
+      a { color: var(--accent); }
+
+      /* Shared focus ring (accessibility — always visible on keyboard focus) */
+      :where(button, input, select, textarea, [tabindex], a):focus-visible {
+        outline: 2px solid var(--focus);
+        outline-offset: 2px;
+      }
+
+      /* ============================================================
+         CONTROL BAR
+         ============================================================ */
+      .controls {
+        position: sticky; top: 0; z-index: 10;
+        display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-5);
+        padding: var(--space-4) var(--space-6);
+        background: var(--layer-01);
+        border-bottom: var(--border-width) solid var(--border);
+      }
+      .controls strong { font-size: 13px; }
+      .controls .group { display: flex; align-items: center; gap: var(--space-3); }
+      .controls label { font-size: 12px; color: var(--text-secondary); text-transform: uppercase; letter-spacing: 0.04em; }
+      .seg { display: inline-flex; border: var(--border-width) solid var(--border-strong); }
+      .seg button {
+        font: inherit; font-size: 13px; cursor: pointer;
+        padding: var(--space-2) var(--space-4);
+        background: var(--bg); color: var(--text);
+        border: none; border-right: var(--border-width) solid var(--border-strong);
+      }
+      .seg button:last-child { border-right: none; }
+      .seg button[aria-pressed='true'] { background: var(--accent); color: var(--accent-contrast); }
+      .swatch-btn { width: 22px; height: 22px; border: 2px solid transparent; cursor: pointer; padding: 0; }
+      .swatch-btn[aria-pressed='true'] { border-color: var(--text); }
+
+      /* ============================================================
+         LAYOUT
+         ============================================================ */
+      main { max-width: 1080px; margin: 0 auto; padding: var(--space-8) var(--space-6) var(--space-9); }
+      section { margin-bottom: var(--space-9); }
+      section > h2 {
+        font-size: 12px; text-transform: uppercase; letter-spacing: 0.08em;
+        color: var(--text-secondary); font-weight: 600;
+        padding-bottom: var(--space-3); margin-bottom: var(--space-6);
+        border-bottom: var(--border-width) solid var(--border);
+      }
+      .row { display: flex; flex-wrap: wrap; gap: var(--space-5); align-items: center; }
+      .stack { display: flex; flex-direction: column; gap: var(--space-4); }
+      .muted { color: var(--text-secondary); }
+      .cap { font-size: 12px; color: var(--text-secondary); }
+
+      /* ----- Typography specimen ----- */
+      .type-row { display: flex; align-items: baseline; gap: var(--space-5); padding: var(--space-2) 0; }
+      .type-row .tag { width: 120px; flex: 0 0 120px; font-family: var(--font-mono); font-size: 12px; color: var(--text-secondary); }
+      .t-display { font-size: 42px; font-weight: 300; line-height: 1.15; }
+      .t-h1 { font-size: 32px; }
+      .t-h2 { font-size: 24px; }
+      .t-h3 { font-size: 20px; }
+      .t-h4 { font-size: 16px; }
+      .t-body { font-size: 14px; }
+      .t-caption { font-size: 12px; color: var(--text-secondary); }
+      .t-code { font-family: var(--font-mono); font-size: 13px; }
+
+      /* ----- Color swatches ----- */
+      .swatches { display: grid; grid-template-columns: repeat(auto-fill, minmax(120px, 1fr)); gap: var(--space-4); }
+      .swatch { border: var(--border-width) solid var(--border); }
+      .swatch .chip { height: 56px; }
+      .swatch .meta { padding: var(--space-3); background: var(--layer-01); font-size: 11px; }
+      .swatch .meta .name { display: block; font-weight: 600; }
+      .swatch .meta .val { font-family: var(--font-mono); color: var(--text-secondary); }
+
+      /* ----- Spacing scale ----- */
+      .space-row { display: flex; align-items: center; gap: var(--space-4); }
+      .space-row .tag { width: 80px; font-family: var(--font-mono); font-size: 12px; color: var(--text-secondary); }
+      .space-bar { height: 16px; background: var(--accent); }
+
+      /* ----- Elevation ----- */
+      .elev { padding: var(--space-6); border: var(--border-width) solid var(--border); }
+      .elev .inner { padding: var(--space-5); }
+
+      /* ----- Buttons ----- */
+      .btn {
+        font: inherit; font-weight: 600; font-size: 14px; cursor: pointer;
+        display: inline-flex; align-items: center; gap: var(--space-3);
+        height: 40px; padding: 0 var(--space-5);
+        border: var(--border-width) solid transparent; border-radius: var(--radius);
+        transition: background var(--dur-fast) var(--ease), border-color var(--dur-fast) var(--ease);
+      }
+      .btn.sm { height: 32px; font-size: 13px; padding: 0 var(--space-4); }
+      .btn-primary { background: var(--accent); color: var(--accent-contrast); }
+      .btn-primary:hover { background: var(--accent-hover); }
+      .btn-secondary { background: transparent; color: var(--text); border-color: var(--border-strong); }
+      .btn-secondary:hover { background: var(--layer-01); }
+      .btn-ghost { background: transparent; color: var(--accent); }
+      .btn-ghost:hover { background: var(--layer-01); }
+      .btn-danger { background: var(--support-error); color: var(--on-status); }
+      .btn-danger:hover { filter: brightness(0.92); }
+      .btn:disabled { opacity: 0.4; cursor: not-allowed; }
+
+      /* ----- Fields ----- */
+      .field { display: flex; flex-direction: column; gap: var(--space-2); max-width: 280px; }
+      .field label { font-size: 12px; color: var(--text-secondary); }
+      .input, .select, .textarea {
+        font: inherit; font-size: 14px; color: var(--text);
+        background: var(--layer-01); border: var(--border-width) solid var(--border-strong);
+        border-radius: var(--radius); padding: var(--space-3) var(--space-4);
+      }
+      .input::placeholder, .textarea::placeholder { color: var(--text-placeholder); }
+      .input:focus, .select:focus, .textarea:focus { outline: 2px solid var(--focus); outline-offset: -1px; border-color: var(--accent); }
+      .textarea { font-family: var(--font-mono); font-size: 13px; min-height: 96px; resize: vertical; }
+      .search { position: relative; max-width: 280px; }
+      .search .input { width: 100%; padding-left: 36px; }
+      .search svg { position: absolute; left: 10px; top: 50%; transform: translateY(-50%); color: var(--text-secondary); }
+
+      /* checkbox / radio / toggle */
+      .check { display: inline-flex; align-items: center; gap: var(--space-3); cursor: pointer; }
+      .check input { accent-color: var(--accent); width: 16px; height: 16px; }
+      .toggle { position: relative; width: 40px; height: 22px; flex: 0 0 40px; }
+      .toggle input { opacity: 0; width: 0; height: 0; }
+      .toggle .track { position: absolute; inset: 0; background: var(--border-strong); transition: background var(--dur-fast) var(--ease); }
+      .toggle .knob { position: absolute; top: 3px; left: 3px; width: 16px; height: 16px; background: #fff; transition: transform var(--dur-fast) var(--ease); }
+      .toggle input:checked + .track { background: var(--accent); }
+      .toggle input:checked + .track + .knob { transform: translateX(18px); }
+      .toggle input:focus-visible + .track { outline: 2px solid var(--focus); outline-offset: 2px; }
+
+      /* ----- Tags / status ----- */
+      .tag-pill { display: inline-flex; align-items: center; gap: var(--space-2); font-size: 12px; padding: var(--space-1) var(--space-3); border: var(--border-width) solid var(--border-strong); }
+      .dot { width: 8px; height: 8px; border-radius: 50%; display: inline-block; }
+      .dot.draft { background: var(--support-warning); }
+      .dot.published { background: var(--support-success); }
+      .badge { display: inline-flex; align-items: center; gap: var(--space-2); font-size: 12px; font-weight: 600; padding: var(--space-1) var(--space-3); color: var(--on-status); }
+
+      /* ----- Snippet list rows ----- */
+      .list { border: var(--border-width) solid var(--border); max-width: 320px; }
+      .item { display: flex; align-items: center; gap: var(--space-3); padding: var(--space-3) var(--space-4); border-left: 2px solid transparent; cursor: pointer; }
+      .item + .item { border-top: var(--border-width) solid var(--border); }
+      .item:hover { background: var(--layer-01); }
+      .item.active { background: var(--layer-01); border-left-color: var(--accent); }
+      .item .main { flex: 1 1 auto; min-width: 0; }
+      .item .name { font-size: 13px; font-weight: 500; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+      .item .sub { font-size: 11px; color: var(--text-secondary); display: flex; align-items: center; gap: var(--space-2); }
+      .item .del { opacity: 0; border: none; background: none; color: var(--text-secondary); cursor: pointer; padding: var(--space-1); display: flex; }
+      .item:hover .del { opacity: 1; }
+      .item .del:hover { color: var(--support-error); }
+
+      /* ----- Panel / card ----- */
+      .panel { background: var(--layer-01); border: var(--border-width) solid var(--border); padding: var(--space-6); max-width: 320px; }
+      .panel h4 { margin-bottom: var(--space-4); }
+      .meta-row { display: flex; justify-content: space-between; font-size: 13px; padding: var(--space-2) 0; }
+      .meta-row .k { color: var(--text-secondary); }
+
+      /* ----- Tabs ----- */
+      .tabs { display: inline-flex; border-bottom: var(--border-width) solid var(--border); }
+      .tabs button { font: inherit; font-size: 13px; cursor: pointer; background: none; border: none; color: var(--text-secondary); padding: var(--space-3) var(--space-5); border-bottom: 2px solid transparent; margin-bottom: -1px; }
+      .tabs button[aria-selected='true'] { color: var(--text); border-bottom-color: var(--accent); font-weight: 600; }
+
+      /* ----- Toasts ----- */
+      .toast { display: flex; align-items: center; gap: var(--space-3); background: var(--layer-02); border: var(--border-width) solid var(--border); border-left-width: 3px; padding: var(--space-3) var(--space-5); font-size: 13px; max-width: 360px; }
+      .toast.info { border-left-color: var(--support-info); }
+      .toast.success { border-left-color: var(--support-success); }
+      .toast.warning { border-left-color: var(--support-warning); }
+      .toast.error { border-left-color: var(--support-error); }
+
+      /* ----- Code surface ----- */
+      .code { background: var(--layer-01); border: var(--border-width) solid var(--border); padding: var(--space-5); font-family: var(--font-mono); font-size: 13px; line-height: 1.6; overflow: auto; white-space: pre; }
+
+      /* ----- Motion demo ----- */
+      .motion-box { width: 56px; height: 56px; background: var(--accent); transition: transform var(--dur-moderate) var(--ease), opacity var(--dur-moderate) var(--ease); }
+      .motion-stage.go .motion-box { transform: translateX(220px); opacity: 0.4; }
+    </style>
+  </head>
+
+  <body>
+    <div class="controls">
+      <strong>Astrolabe · Visual Specimen</strong>
+      <div class="group">
+        <label>Theme</label>
+        <div class="seg" id="theme">
+          <button data-theme-val="light" aria-pressed="true">Light</button>
+          <button data-theme-val="dark" aria-pressed="false">Dark</button>
+        </div>
+      </div>
+      <div class="group">
+        <label>Accent</label>
+        <div class="row" id="accent" style="gap: var(--space-3)">
+          <button class="swatch-btn" data-accent-val="indigo" aria-pressed="true" style="background: #5b54e6" title="Indigo"></button>
+          <button class="swatch-btn" data-accent-val="teal" aria-pressed="false" style="background: #0f766e" title="Teal"></button>
+          <button class="swatch-btn" data-accent-val="amber" aria-pressed="false" style="background: #b45309" title="Amber"></button>
+          <button class="swatch-btn" data-accent-val="rose" aria-pressed="false" style="background: #be123c" title="Rose"></button>
+        </div>
+      </div>
+      <span class="cap">Structure is rigorous · color is free — swap freely.</span>
+    </div>
+
+    <main>
+      <!-- TYPOGRAPHY -->
+      <section>
+        <h2>Typography — IBM Plex</h2>
+        <div class="type-row"><span class="tag">display 42/300</span><span class="t-display">Astrolabe</span></div>
+        <div class="type-row"><span class="tag">h1 32/600</span><span class="t-h1">A spec is a snippet</span></div>
+        <div class="type-row"><span class="tag">h2 24/600</span><span class="t-h2">A spec is a snippet</span></div>
+        <div class="type-row"><span class="tag">h3 20/600</span><span class="t-h3">A spec is a snippet</span></div>
+        <div class="type-row"><span class="tag">h4 16/600</span><span class="t-h4">A spec is a snippet</span></div>
+        <div class="type-row"><span class="tag">body 14/400</span><span class="t-body">The quick brown fox edits a Vega-Lite spec and watches it render.</span></div>
+        <div class="type-row"><span class="tag">caption 12</span><span class="t-caption">Last modified · Today</span></div>
+        <div class="type-row"><span class="tag">mono 13</span><span class="t-code">{ "mark": "bar", "encoding": { "x": { "field": "category" } } }</span></div>
+      </section>
+
+      <!-- COLOR -->
+      <section>
+        <h2>Color — neutral ramp (borrowed) · accent &amp; status (free / meaning)</h2>
+        <p class="cap">Neutrals come from the Carbon gray ramp for legibility; the accent and themes are open. Status colors carry meaning only.</p>
+        <h4 style="margin: var(--space-5) 0 var(--space-4)">Surface roles (current theme)</h4>
+        <div class="swatches" id="roleSwatches"></div>
+        <h4 style="margin: var(--space-6) 0 var(--space-4)">Accent &amp; status</h4>
+        <div class="swatches" id="accentSwatches"></div>
+      </section>
+
+      <!-- SPACING -->
+      <section>
+        <h2>Spacing — 8px base unit</h2>
+        <div class="stack" id="spaceScale"></div>
+      </section>
+
+      <!-- ELEVATION -->
+      <section>
+        <h2>Elevation — lightness, not shadow</h2>
+        <div class="elev" style="background: var(--bg)">
+          <span class="cap">--bg</span>
+          <div class="elev inner" style="background: var(--layer-01); margin-top: var(--space-4)">
+            <span class="cap">--layer-01</span>
+            <div class="elev inner" style="background: var(--layer-02); margin-top: var(--space-4)">
+              <span class="cap">--layer-02 (overlays, popovers)</span>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <!-- BUTTONS -->
+      <section>
+        <h2>Buttons — square, 600 weight</h2>
+        <div class="row">
+          <button class="btn btn-primary">Create snippet</button>
+          <button class="btn btn-secondary">Duplicate</button>
+          <button class="btn btn-ghost">Cancel</button>
+          <button class="btn btn-danger">Delete</button>
+          <button class="btn btn-primary" disabled>Disabled</button>
+        </div>
+        <div class="row" style="margin-top: var(--space-5)">
+          <button class="btn btn-primary sm">Compact</button>
+          <button class="btn btn-secondary sm">Compact</button>
+          <button class="btn btn-ghost sm">Compact</button>
+        </div>
+        <p class="cap" style="margin-top: var(--space-4)">Tab through to see the focus ring (2px accent outline).</p>
+      </section>
+
+      <!-- FIELDS -->
+      <section>
+        <h2>Form controls</h2>
+        <div class="row" style="align-items: flex-start; gap: var(--space-7)">
+          <div class="field"><label>Snippet name</label><input class="input" value="Quarterly revenue" /></div>
+          <div class="field"><label>Comment</label><input class="input" placeholder="Add a note…" /></div>
+          <div class="field">
+            <label>Sort by</label>
+            <select class="select"><option>Modified</option><option>Created</option><option>Name</option><option>Size</option></select>
+          </div>
+        </div>
+        <div class="row" style="margin-top: var(--space-5); align-items: flex-start; gap: var(--space-7)">
+          <div class="field" style="max-width: 360px"><label>Spec (JSON)</label><textarea class="textarea">{
+  "mark": "bar",
+  "encoding": { "x": { "field": "category" } }
+}</textarea></div>
+          <div class="stack">
+            <div class="search">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.3-4.3"/></svg>
+              <input class="input" placeholder="Search snippets…" />
+            </div>
+            <label class="check"><input type="checkbox" checked /> Show only drafts</label>
+            <label class="check"><input type="radio" name="r" checked /> Inline data</label>
+            <label class="check"><input type="radio" name="r" /> Dataset reference</label>
+            <div class="check">
+              <span class="toggle"><input type="checkbox" checked /><span class="track"></span><span class="knob"></span></span>
+              <span>Live preview</span>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <!-- TABS + STATUS -->
+      <section>
+        <h2>Tabs · status · tags</h2>
+        <div class="tabs">
+          <button aria-selected="true">Draft</button>
+          <button aria-selected="false">Published</button>
+        </div>
+        <div class="row" style="margin-top: var(--space-6)">
+          <span class="tag-pill"><span class="dot draft"></span> Draft changes</span>
+          <span class="tag-pill"><span class="dot published"></span> Published</span>
+          <span class="tag-pill">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><ellipse cx="12" cy="6" rx="8" ry="3"/><path d="M4 6v12c0 1.7 3.6 3 8 3s8-1.3 8-3V6"/><path d="M4 12c0 1.7 3.6 3 8 3s8-1.3 8-3"/></svg>
+            2 datasets
+          </span>
+          <span class="tag-pill">imported</span>
+        </div>
+        <div class="row" style="margin-top: var(--space-5)">
+          <span class="badge" style="background: var(--support-success)">Saved</span>
+          <span class="badge" style="background: var(--support-error)">Error</span>
+          <span class="badge" style="background: var(--support-warning); color: #161616">82% full</span>
+          <span class="badge" style="background: var(--support-info)">Info</span>
+        </div>
+      </section>
+
+      <!-- LIST + PANEL -->
+      <section>
+        <h2>Snippet library &amp; metadata panel</h2>
+        <div class="row" style="align-items: flex-start; gap: var(--space-7)">
+          <div class="list">
+            <div class="item active">
+              <div class="main">
+                <div class="name">Quarterly revenue</div>
+                <div class="sub"><span class="dot draft"></span> Today · 2 KB</div>
+              </div>
+              <button class="del" title="Delete"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M5 7h14M9 7V5h6v2M7 7l1 12h8l1-12"/></svg></button>
+            </div>
+            <div class="item">
+              <div class="main">
+                <div class="name">Population by region</div>
+                <div class="sub"><span class="dot published"></span> Yesterday</div>
+              </div>
+              <button class="del" title="Delete"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M5 7h14M9 7V5h6v2M7 7l1 12h8l1-12"/></svg></button>
+            </div>
+            <div class="item">
+              <div class="main">
+                <div class="name">Scatter · height vs weight</div>
+                <div class="sub"><span class="dot published"></span> 3d ago</div>
+              </div>
+              <button class="del" title="Delete"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M5 7h14M9 7V5h6v2M7 7l1 12h8l1-12"/></svg></button>
+            </div>
+          </div>
+
+          <div class="panel">
+            <h4>Quarterly revenue</h4>
+            <div class="meta-row"><span class="k">Created</span><span>2026-06-01</span></div>
+            <div class="meta-row"><span class="k">Modified</span><span>Today 14:30</span></div>
+            <div class="meta-row"><span class="k">Status</span><span><span class="dot draft"></span> Draft changes</span></div>
+            <div class="row" style="margin-top: var(--space-5)">
+              <button class="btn btn-primary sm">Publish</button>
+              <button class="btn btn-ghost sm">Revert</button>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <!-- TOASTS -->
+      <section>
+        <h2>Toasts</h2>
+        <div class="stack" style="max-width: 360px">
+          <div class="toast info">Snippet duplicated.</div>
+          <div class="toast success">Published “Quarterly revenue”.</div>
+          <div class="toast warning">Snippet storage is 82% full.</div>
+          <div class="toast error">Could not save — storage is full.</div>
+        </div>
+      </section>
+
+      <!-- CODE -->
+      <section>
+        <h2>Code / editor surface — IBM Plex Mono</h2>
+        <div class="code">{
+  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
+  "data": { "values": [{ "category": "A", "value": 28 }] },
+  "mark": "bar",
+  "encoding": {
+    "x": { "field": "category", "type": "nominal" },
+    "y": { "field": "value", "type": "quantitative" }
+  }
+}</div>
+      </section>
+
+      <!-- MOTION -->
+      <section>
+        <h2>Motion — productive only (150ms, restrained)</h2>
+        <div class="motion-stage" id="motionStage">
+          <div class="motion-box"></div>
+        </div>
+        <div class="row" style="margin-top: var(--space-5)">
+          <button class="btn btn-secondary sm" id="motionBtn">Play transition</button>
+          <span class="cap">Neutralized automatically under <code>prefers-reduced-motion</code>.</span>
+        </div>
+      </section>
+    </main>
+
+    <script>
+      const root = document.documentElement;
+
+      // Theme switch
+      document.getElementById('theme').addEventListener('click', (e) => {
+        const b = e.target.closest('button'); if (!b) return;
+        root.setAttribute('data-theme', b.dataset.themeVal);
+        for (const x of e.currentTarget.children) x.setAttribute('aria-pressed', String(x === b));
+        renderSwatches();
+      });
+
+      // Accent switch
+      document.getElementById('accent').addEventListener('click', (e) => {
+        const b = e.target.closest('button'); if (!b) return;
+        root.setAttribute('data-accent', b.dataset.accentVal);
+        for (const x of e.currentTarget.children) x.setAttribute('aria-pressed', String(x === b));
+        renderSwatches();
+      });
+
+      // Tabs (specimen only)
+      document.querySelectorAll('.tabs').forEach((t) =>
+        t.addEventListener('click', (e) => {
+          const b = e.target.closest('button'); if (!b) return;
+          for (const x of t.children) x.setAttribute('aria-selected', String(x === b));
+        }),
+      );
+
+      // Motion demo
+      document.getElementById('motionBtn').addEventListener('click', () =>
+        document.getElementById('motionStage').classList.toggle('go'),
+      );
+
+      // Live swatches read the resolved token values for the current theme/accent
+      const ROLE_TOKENS = ['--bg', '--layer-01', '--layer-02', '--border', '--border-strong', '--text', '--text-secondary', '--text-placeholder'];
+      const ACCENT_TOKENS = ['--accent', '--accent-hover', '--support-error', '--support-success', '--support-warning', '--support-info'];
+      function swatchHTML(token) {
+        const val = getComputedStyle(root).getPropertyValue(token).trim();
+        return `<div class="swatch"><div class="chip" style="background:${val}"></div><div class="meta"><span class="name">${token}</span><span class="val">${val || '—'}</span></div></div>`;
+      }
+      function renderSwatches() {
+        document.getElementById('roleSwatches').innerHTML = ROLE_TOKENS.map(swatchHTML).join('');
+        document.getElementById('accentSwatches').innerHTML = ACCENT_TOKENS.map(swatchHTML).join('');
+      }
+
+      // Spacing scale
+      (function () {
+        const steps = [['--space-1', '2px'], ['--space-2', '4px'], ['--space-3', '8px'], ['--space-4', '12px'], ['--space-5', '16px'], ['--space-6', '24px'], ['--space-7', '32px'], ['--space-8', '48px'], ['--space-9', '64px']];
+        document.getElementById('spaceScale').innerHTML = steps
+          .map(([t, v]) => `<div class="space-row"><span class="tag">${t}</span><span class="space-bar" style="width:${v}"></span><span class="cap">${v}</span></div>`)
+          .join('');
+      })();
+
+      renderSwatches();
+    </script>
+  </body>
+</html>