v3 Website — Design Token System + Full Migration — Design

Date: 2026-05-14 Project: Sub-project B of a two-part effort. (Sub-project A — responsive pass on all v3 pages — is complete.) Worktree: /Users/maximilianbrandstaetter/Orcha/.claude/worktrees/website-v3-mobile-responsive, branch website-v3-mobile-responsive.

Goal

The v3 website uses far too many distinct values — 39 font sizes, ~38 spacing values, ~15 border-radii, raw hex colors that duplicate existing tokens, and ~5 icon sizes. Define a constrained design-token system covering type, color, icons, spacing, and radius; codify it as CSS custom properties; and migrate the entire v3 site (shared CSS + every page's inline styles) to use it — so the site has a small, defined set of values instead of organic sprawl, with no meaningful visual change.

Audit findings (current state)

• Font size: 39 distinct values. Mass concentrated in 9–16px; a long tail of half-pixels (10.5, 9.5, 13.5, 12.5, 11.5, 14.5, 15.5, 8.5, 7.5) and one-offs (96, 80, 60, 44, 36, 30, 28, 26, 23, 21, 20, 17). Display headings already use clamp().
• Font weight: essentially clean — 400 / 500 / 600 (500 dominates ×339); one stray 700.
• Font family: clean — --sans and --mono already defined (--serif is an unused alias of --sans).
• Color: a solid :root token set already exists — but it is defined twice (in v3.css and product.css) and inconsistently used. Raw hexes leak in: many duplicate existing tokens (#006EC7=--accent ×12, #f5f3ee=--bg-2, #5a5a56=--ink-3, #dcd7cb=--line, …); a 5-color categorical pastel palette (#D49B70 #BC7B95 #A185BB #7A9BC0 #6DAF9F) has no tokens; a handful of genuinely-new colors (#fafaf6, #eceae3, #1a1a1a, …) have no tokens; #8627 (×9) is a malformed hex.
• Icon: SVG widths 12 / 13 / 14 / 16 / 18; stroke-widths sprawl (1.8 ×254, 1.6 ×144, 1.4 ×54, 1.5 ×22, + others).
• Spacing: ~38 distinct padding/gap/margin px values; mass in 2–40px, long tail to 140px.
• Border-radius: ~15 distinct values; --radius: 10px token exists but is rarely used; 999px pill is common.

Approach

Data-driven snap. Each token scale is derived by keeping the well-used values from the existing distribution and dropping the half-pixels and one-offs. Migration replaces every raw value with its nearest token. Because the kept values are the dominant ones, the overwhelming majority of usages do not move at all; outliers shift by 1–4px at most. The site looks essentially unchanged — it just has a small defined set of values.

Rejected: a fresh modular scale (textbook-cleaner, but full migration would visibly redesign a site that was just made responsive); tokens-without-migration (the user explicitly chose full migration).

Design

1. Token architecture

• New file www/v3/css/tokens.css — one canonical :root holding every token scale. Linked first on all 30 pages (before v3.css), so it is the base layer.
• The duplicated :root blocks in v3.css and product.css are removed — tokens.css is the single source of truth. (Existing token names — --bg, --ink, --accent, --sans, etc. — are preserved so nothing downstream breaks; new scales are added alongside.)
• Tokens are plain CSS custom properties (no preprocessor, no utility-class framework — consistent with the current static-CSS codebase). Utility classes are out of scope; values are referenced as var(--token).

2. The token scales

Values below are the proposed scales — derived from the audit distribution, optimized for minimal drift. They are the primary thing to scrutinize in the spec review.

• Type — --text-* (11 discrete steps + display): 9, 10, 11, 12, 13, 14, 15, 16, 19, 24, 32 px. These are the well-used integer sizes (each ≥10 uses, together ~90% of all usage) — kept as-is so they don't move. Display headings keep clamp()-based tokens (--text-display-s/m/l). Snap rule for the rest: each dropped value → nearest kept step (half-pixels collapse: 10.5→11, 9.5→10, 13.5→14, …; one-offs: 17→16, 18→19, 20→19, 22→24, 26→24, 28→32, 30→32, 36→32; 44/48/60/80/88/96 → the display tokens). Open for review: whether to merge the dense 12/13/14/15/16 cluster further (tighter, but moves hundreds of usages).
• Weight — --weight-{regular,medium,semibold}: 400 / 500 / 600. The stray 700 → 600.
• Family: keep --sans, --mono. Drop the unused --serif alias.
• Color: consolidate to one :root. Keep all existing semantic tokens. Add --cat-1…5 for the categorical pastel palette. Genuinely-new colors get named tokens only if used ≥2× with intent, otherwise snap to the nearest existing token. Every raw hex in CSS + pages is replaced with var(--token). Fix #8627. Open for review: the names/values for the categorical palette and any new neutrals.
• Icon — --icon-{sm,md,lg}: 14 / 16 / 18 px (covers the real cluster; 12→14, 13→14). Stroke-width consolidated to --icon-stroke (1.6) and --icon-stroke-bold (1.8); the 1.4/1.5 etc. snap. Open for review: whether 12px deserves its own step.
• Spacing — --space-* (~14 steps): 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 64, 80, 120 px. Keeps the heavily-used fine-grained low end; drops 14/18/22/28/36/56/72/etc. → nearest. Open for review: this is the hardest scale — spacing usage is the most spread out; a tighter scale is possible but drifts more padding/gap values.
• Radius — --radius-* (6 steps): 2, 4, 8, 12, 16, 999 (pill). The existing --radius: 10px → --radius-md (12) or kept at 10; 14→12 or 16; etc. Open for review: whether to keep 10px given its frequency.

3. Migration

Snap-to-nearest, applied site-wide, staged (mirroring sub-project A's structure):

• Stage 1 — Tokens + shared CSS: create tokens.css; link it first on all 30 pages; remove the duplicate :root blocks; migrate v3.css, product.css, responsive.css, trial.css to var(--token).
• Stage 2 — Page inline styles, tiered: migrate the inline style= attributes and in-body <style> blocks across all 30 pages — homepage (de+en) → product pages (de+en) → section pages (de+en). de/en mirrors take the same edits.

One spec; writing-plans produces the staged plans.

4. Verification — visual-regression harness

Extend www/v3/dev/screenshot.mjs into a visual-regression tool:

• A baseline mode captures the current rendering of all 30 pages × 5 widths before migration begins (the "ground truth" — the site as it looks today).
• A diff mode, run after each stage, re-renders and pixel-compares against the baseline, reporting any page/width whose rendering changed beyond a small tolerance.
• The migration's success criterion is a near-zero diff — data-driven snapping should produce no meaningful visual change. Any region that diffs significantly is either an outlier that snapped too far (revisit the scale) or a real bug (fix it).

This replaces the old harness's overflow-only check with a true before/after comparison, which is what a token migration needs.

Acceptance criteria

• www/v3/css/tokens.css exists, is linked first on all 30 pages, and is the single :root source (no :root left in v3.css/product.css).
• Every font-size, color, icon size, spacing, and radius value in the v3 CSS files and the 30 pages' inline styles is either a var(--token) reference or one of the defined scale values — no raw hexes, no half-pixel font sizes, no off-scale values.
• The visual-regression harness reports near-zero diff vs. the pre-migration baseline across all 30 pages × 5 widths — the site looks the same, with far fewer distinct values.
• The responsive harness still passes (no horizontal overflow regressions).

Out of scope

• Utility-class / framework adoption — plain custom properties only.
• A separate markdown design-guide doc or visual HTML reference page (the user chose codified CSS tokens as the deliverable form; tokens.css with clear comments is the guide).
• Redesigning anything — values change only by snapping, never by intent.
• The drafts and archive pages (same exclusion as sub-project A).

Risks / known tricky areas

• Spacing scale — the hardest; usage is genuinely spread out, so any real reduction drifts some values. The visual-regression harness is the safety net.
• clamp() headings — display headings use clamp(min, vw, max); these get --text-display-* tokens but the clamp() expressions themselves must be preserved, not flattened.
• color-mix() usage — much of the CSS uses color-mix(in oklab, var(--token), …); migration must keep these intact, only replacing raw-hex inputs.
• de/en mirror drift — pages are mirrors today; the harness checks both, and edits are applied per-file.
• Scale bikeshedding — the exact scale values are subjective; the spec review is the place to settle them, and the data-driven derivation + the open-for-review notes above bound the discussion.