/design-system

name: design-system
description: "Use when starting any design task, before choosing or auditing a color/type/spacing token or writing design-system.md — routing step 1."
when-to-use: "First read of every design task, unconditionally (design-method routing step 1) — before choosing or auditing any token, and before writing design-system.md."
keywords: tokens, oklch, color, typography, spacing, design-system.md, contrast, fonts, density
priority: critical
related: design-method, design-web, design-webapp, contrast-ratios.md, sector-palettes.md, typography-pairs.md, forbidden-fonts.md, design-read-dials.md

<objective> The token-strategy core: OKLCH-only color rules for new tokens, neutral tinting (chroma 0.005-0.015, never pure gray), the accent-commitment levels (restrained/committed/full palette/drenched), the typography scale (ratio, line-height, measure), the 8pt spacing grid, and platform touch-target minimums.

Also defines the canonical output format of `design-system.md` — the file the harness gates on — including its 4 hard requirements (the `## Design Reference` heading, a real inspiration URL, at least one chroma-positive OKLCH token, and the hard-forbidden font exclusions).

This is routing step 1 of `design-method/SKILL.md`: read it before `design-web`, `design-webapp`, `design-ios`, or `design-android`, and before picking or auditing a single color/type/spacing value. </objective>

<!-- Grounding: grounding-corpus.md §B (thresholds), §H (kept anchors); harness-contract.md invariant #2 (design-system.md format) + #3 (this file's read-path triggers harness phase 1). -->

Design System — Token Core

Single source for token **strategy** — not values, values live in `references/*.md` and are read from there, never re-derived here. `design-method/SKILL.md` reads this file **unconditionally as routing step 1**, once per task, before dispatching to any move or target skill — that read is also what advances the harness past phase 0. If a design question is purely about a token (a color, a type pair, a spacing value) this file plus its reference index already answers it; otherwise continue back into `design-method`'s routing.

Color strategy

• **OKLCH only** for new tokens: `oklch(L% C H)`. Never hex/HSL/RGB for anything you're

defining fresh (existing legacy tokens in an inherited codebase are a different problem — don't rewrite what wasn't asked for).

• **Neutrals** — tint every neutral toward the brand hue, chroma **0.005–0.015**. Never a

pure gray (chroma 0), never `#000`/`#fff`.

• **Accent commitment** — pick the strategy BEFORE picking hues:
• **Restrained** — tinted neutrals + one accent ≤10% of surface. Product register default.
• **Committed** — one saturated color carries 30–60% of surface. Brand register default.
• **Full palette** (3–4 named roles) / **Drenched** (surface IS the color) — brand

campaigns, product data-viz. See `design-method/references/register/brand.md` §4 and `register/product.md` §1 for which strategy each register defaults to and when to deviate.

• Reduce chroma as lightness approaches 0 or 100 — high chroma at the extremes reads garish.
• Mechanics: `references/oklch-system.md`. Concrete per-sector values:

`references/sector-palettes.md`. Contrast floors: `references/contrast-ratios.md` — WCAG AA 4.5:1 body text / 3:1 large text + UI components (AAA 7:1 where feasible).

Typography scale

• Ratio **≥1.25** between steps (1.25 major-third is the default, 1.333 for editorial), 6–8

sizes max, **≤3 contrast variations per view**.

• Line-height: body 1.5×, display 1.05–1.15×. Body measure 65–75ch.
• Validated pairs: `references/typography-pairs.md`. Forbidden/flagged fonts — canonical

list, don't restate it anywhere else in this plugin: `references/forbidden-fonts.md`.

Spacing

• **8pt grid**: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96.
• Density profile (Enterprise Dense / Standard / Editorial) chosen per register:

`references/spacing-density.md` — product defaults dense, brand defaults editorial (see `register/brand.md` §4 and `register/product.md` §1).

Touch targets

iOS 44×44pt · Android 48×48dp · WCAG 2.5.8 minimum 24×24 CSS px regardless of platform.

The `design-system.md` output — canonical format

This is the generated file the harness gates on (`gates-pipeline.ts` triggers on any read path ending `design-system.md`; `gates.ts` validates its contents). Every requirement below is a **present/absent check**, not a suggestion — missing one fails the gate silently downstream, with no error surfaced at write time.

## Design Reference
Inspiration: https://example.com/the-actual-site-browsed-in-generate-step-2

### Colors
--color-accent: oklch(0.62 0.19 250);
--color-neutral-900: oklch(0.18 0.01 250);
... (full token set — chroma > 0 required on at least the accent token)

### Typography
--font-display: "Fraunces", ui-serif;
--font-body: "Public Sans", ui-sans-serif;
... (never the four hard-forbidden families below, whichever fonts are actually chosen)

**The 4 hard requirements (all must hold):**

1. Heading `## Design Reference` present verbatim. 2. At least one `https?://` URL — the real inspiration source browsed in `design-web/references/design-inspiration.md` step 2, not a placeholder. 3. At least one `oklch(...)` token with **chroma > 0** — a chroma-0 neutral alone does not satisfy this; the accent (or any committed-strategy token) must carry chroma. 4. Must **not** contain `Inter`, `Roboto`, `Arial`, or `Open Sans` anywhere in the file — this is the harness-checked subset of the full 6-font hard-forbidden tier in `references/forbidden-fonts.md` (which also bans `Lato`/`Poppins`, not harness-checked but still enforced by this skill).

Check this list explicitly before writing `design-system.md` — don't rely on having "used OKLCH generally" earlier in the task; the gate reads the file, not the process.

Reference index (data lives here, read from source