design-system · diff
git:20260717.ed06ff2 to git:20260729.3b91eed
9 added, 1 removed. Audit A to A.
---
name: 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."
+ 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.
```markdown
## 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, 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.