design-system · diff
git:20260716.5b6b136 to git:20260717.ed06ff2
105 added, 108 removed. Audit A to A.
---
name: design-system
- description: "Design tokens: OKLCH palette, typography pair, spacing, motion profile, and the mechanical contrast-check step. Canonical source for the forbidden-fonts list and contrast thresholds — referenced, never restated, elsewhere in this plugin."
- when-to-use: "No design-system.md exists yet at the project root, or an existing one needs auditing/extending."
- keywords: tokens, oklch, typography, contrast, spacing, motion-profile, design-system
+ description: "Token-strategy core — OKLCH color rules, neutral tinting, accent-commitment levels, type scale, 8pt spacing grid, touch targets, and the canonical output format of design-system.md (the file the harness gates on). This is routing step 1 of design-method/SKILL.md — read it before design-web/design-webapp/design-ios/design-android, before picking or auditing a single color/type/spacing value."
+ 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, design-review
+ related: design-method, design-web, design-webapp, contrast-ratios.md, sector-palettes.md, typography-pairs.md, forbidden-fonts.md, design-read-dials.md
---
- ## Design System — Tokens and the Mechanical Contrast Check
+ <!-- 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). -->
- ### When
- Start of a new project (no `design-system.md` at project root), or extending/auditing an
- existing one. Assumes `design-method`'s Step 1 brief and Step 2 signature element are
- already defined.
+ # Design System — Token Core
- ### Steps
+ 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.
- 1. **Design Read + dials** — `references/design-read-dials.md`. Infer the brief (page
- kind, vibe words, audience, quiet constraints) and fix the 3 dials `DESIGN_VARIANCE`,
- `VISUAL_DENSITY`, `MOTION_INTENSITY` (1-10). These are contractual inputs for every
- later step — set once, read everywhere else.
- 2. **Match sector** in `references/sector-palettes.md` — pick the OKLCH palette base.
- 3. **Generate palette** using `references/oklch-system.md` — primary, secondary, accent,
- neutral + semantic colors. All colors `oklch()`. Color must be **committed**: either
- chromatic (chroma ≥ 0.05) or a deliberately near-mono system with one decisive accent —
- the slop is a timid, uncommitted gray, not low chroma itself (Linear/Vercel/Stripe ship
- premium near-mono palettes). Derive the dark-mode set with `references/color-mapping.md`, checking
- `references/edge-cases.md` and `references/image-handling.md` for what breaks on flip.
- 4. **Choose typography pair** from `references/typography-pairs.md` — display + body
- fonts matching the tone from `design-method`. See Forbidden Fonts below.
- 5. **Set spacing density** from `references/spacing-density.md` — dense / standard / editorial.
- 6. **Define motion personality** from `references/motion-personality.md` — corporate /
- modern / playful / luxury. Consumed later by `design-motion`.
- 7. **Check visual techniques** in `references/visual-technique-matrix.md` — what's allowed
- for this personality × density combination.
- 8. **Run the Mechanical Contrast Check and Mechanical Type-Scale Check** (below).
- 9. **Generate `design-system.md`** at project root from `references/templates/` (fintech,
- ecommerce, devtool, creative, or blank).
+ ## Color strategy
- ### Forbidden Fonts (canonical list — defined here only)
+ - **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).
- **Hard-forbidden**: `Inter`, `Roboto`, `Arial`, `Open Sans`, `Lato`, `Poppins`. Any other
- file in this plugin that mentions forbidden fonts must point here instead of restating
- its own list.
+ ## Typography scale
- **Flag-when-undeclared**: `Fraunces`, `Instrument Serif`, `Playfair Display`, `Geist`,
- `Space Grotesk`. These fonts are legitimate *when declared as the deliberate signature
- element* (see `design-method` Step 2) — they are not banned outright. The tell isn't the
- font itself, it's the *reflexive, undeclared* combo: serif-display + italic accent + cream
- background for the first three; the "safe modern-technical" grotesk reached for on
- autopilot, with no stated rationale, for Geist/Space Grotesk. If one of these fonts shows
- up without an explicit signature-element rationale in `design-system.md`, flag it for
- review rather than auto-passing it.
+ - 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`.
- ### Font Self-Hosting (canonical — defined here only)
+ ## Spacing
- A named display/premium font MUST be self-hosted: `@font-face` with a `woff2` source,
- `font-display: swap`, and a `<link rel="preload">` for the file. If that pipeline isn't
- wired up, don't name the font — fall back to a system stack instead. Naming a font in
- `design-system.md` without ever loading it is aspirational typography that never ships;
- the presence of `@font-face` is the check that the intent is real.
+ - **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).
- ### Mechanical Contrast Check (canonical — defined here only)
+ ## Touch targets
- Not a vibe check — a calculation from the OKLCH lightness (`L`) of each token pair,
- per `references/contrast-ratios.md`:
+ iOS 44×44pt · Android 48×48dp · WCAG 2.5.8 minimum 24×24 CSS px regardless of platform.
- | L difference | Approx. ratio | Passes |
- |---|---|---|
- | ≥ 50% | > 7:1 | AAA normal text |
- | ≥ 40% | > 4.5:1 | AA normal text (the floor for body copy) |
- | ≥ 30% | > 3:1 | AA large text / UI components (the floor for borders, icons, focus rings) |
- | < 25% | < 3:1 | Fails everything — do not ship |
+ ## The `design-system.md` output — canonical format
- Run this against every text-on-background and UI-element-on-background pair in both
- light and dark mode before calling the system done. Thresholds: **4.5:1 text, 3:1 UI** —
- this is the only place that number is defined; every other file in this plugin that cites
- a contrast ratio points back here.
+ 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.
- ### Mechanical Type-Scale Check (canonical — defined here only)
+ ```markdown
+ ## Design Reference
+ Inspiration: https://example.com/the-actual-site-browsed-in-generate-step-2
- - **Type-Scale Floor**: ≥ 1.2× between adjacent **title** steps only (display→h1→h2→h3) — mechanical check `step[n].fontSize / step[n-1].fontSize ≥ 1.2`; 1.25× is the preferred target, FAIL is <1.2. Body→caption tier is **exempt** (tighter ratios are legitimate there, see `references/fluid-typography.md`).
- - **Body-Size Floor**: the main paragraph token (`--text-base`/body) ≥ 16px in every breakpoint. Caption/small/label tokens (e.g. `--text-small` 14px) are **exempt**.
+ ### 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)
- Run both alongside the Mechanical Contrast Check above before calling the system done.
+ ### 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)
+ ```
- ### Output
- - `design-system.md` at project root: OKLCH palette (light + dark), typography pair,
- spacing profile, motion personality, visual techniques allowed, the 3 dials recorded
- at the top.
- - Every token pair passes the Mechanical Contrast Check above.
+ **The 4 hard requirements (all must hold):**
- ### Next
- Route back to `design-method`'s table: `design-web`, `design-webapp`, `design-ios`, or
- `design-android`.
+ 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).
- ### References
- | File | Purpose |
- |------|---------|
- | `references/design-read-dials.md` | Design Read (brief inference) + the 3 direction dials with presets |
- | `references/identity-brief.md` | 5-question brand questionnaire (extends `design-method` Step 1) |
- | `references/sector-palettes.md` | Sector-specific OKLCH palettes |
- | `references/oklch-system.md` | OKLCH color generation rules |
- | `references/contrast-ratios.md` | **Canonical WCAG contrast reference — full method + checklist** |
- | `references/color-mapping.md` | Light → dark OKLCH transformation rules |
- | `references/typography-pairs.md` | **Canonical forbidden-fonts list** + approved pairings |
- | `references/spacing-density.md` | Density profiles |
- | `references/motion-personality.md` | Motion personality definitions (consumed by `design-motion`) |
- | `references/visual-technique-matrix.md` | Allowed techniques per personality × density |
- | `references/templates/` | `design-system.md` templates per sector |
+ 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.
- ### Detailed References
- | File | Load when … |
- |------|------|
- | `references/color-system.md` | Building the full semantic color-token layer beyond the base palette. |
- | `references/typography.md` | Defining the type scale beyond the pair itself (weights, line-height). |
- | `references/fluid-typography.md` | Defining the `clamp()`-based fluid type scale. |
- | `references/ui-hierarchy.md` | Establishing visual hierarchy rules across a page. |
- | `references/ui-spacing.md` | Detailing the spacing system beyond the base density profile. |
- | `references/ui-trends-2026.md` | Validating that the visual direction feels current, not dated. |
- | `references/breakpoint-patterns.md` | Defining the responsive breakpoint strategy. |
- | `references/container-queries.md` | A component must respond to its container, not the viewport. |
- | `references/gradients-guide.md` | The identity calls for gradient backgrounds/accents. |
- | `references/theme-presets.md` | Starting from a sector preset instead of building from scratch. |
- | `references/complex-themes.md` | Nested or conditional theming beyond simple light/dark. |
- | `references/multi-brand.md` | Multiple brands or white-label themes share one system. |
- | `references/edge-cases.md` | Dark-mode-specific breakage (shadows, elevation). |
- | `references/image-handling.md` | Dark-mode image treatment strategy. |
- | `references/tailwind-config.md` | Custom Tailwind theme configuration for these tokens. |
- | `references/tailwind-utilities.md` | Mapping tokens to Tailwind utility classes. |
- | `references/tailwind-performance.md` | Optimizing Tailwind output size / purge strategy. |
+ ## Reference index (data lives here, read from source, never restated above)
+
+ | Concern | File |
+ |---|---|
+ | OKLCH mechanics | `references/oklch-system.md` |
+ | Contrast ratios (WCAG) | `references/contrast-ratios.md` |
+ | Sector palettes (concrete OKLCH) | `references/sector-palettes.md` |
+ | Typography pairs | `references/typography-pairs.md` |
+ | Forbidden/flagged fonts (canonical) | `references/forbidden-fonts.md` |
+ | Spacing / density profiles | `references/spacing-density.md` |
+ | Identity brief questionnaire | `references/identity-brief.md` |
+ | Design Read + the 3 dials (VARIANCE/DENSITY/MOTION) | `references/design-read-dials.md` |
+ | Color-token mapping | `references/color-mapping.md` |
+ | Gradients | `references/gradients-guide.md` |
+ | Fluid typography | `references/fluid-typography.md` |
+ | Breakpoints | `references/breakpoint-patterns.md` |
+ | Container queries | `references/container-queries.md` |
+ | Multi-brand theming | `references/multi-brand.md` |
+ | Complex themes (dark mode etc.) | `references/complex-themes.md` |
+ | Motion personality | `references/motion-personality.md` |
+ | UI hierarchy / spacing rhythm | `references/ui-hierarchy.md`, `references/ui-spacing.md` |
+ | UI trends 2026 | `references/ui-trends-2026.md` |
+ | Visual technique matrix | `references/visual-technique-matrix.md` |
+ | Edge cases (empty/error/loading) | `references/edge-cases.md` |
+ | Image handling | `references/image-handling.md` |
+ | Tailwind config / utilities / perf | `references/tailwind-config.md`, `tailwind-utilities.md`, `tailwind-performance.md` |
+ | Per-sector `design-system.md` templates | `references/templates/*.md` |
+
+ ## Next
+
+ This read is `design-method/SKILL.md` routing step 1, not a standalone task — return there
+ for Register resolution, Gate 0, and move dispatch. A pure token question is already
+ answered by the sections above; everything else (page structure, moves, register floors)
+ lives in `design-method` and the target-platform skills.