--- name: design description: "Turn a design seed \u2014 a brand, a feeling, a reference, a colour \u2014 into a concrete design system with tokens, component specs, states and accessibility rules that implementation can build against. Use after personas and before architecture. Produces .delivery/initiatives/initiative/design-system.md." --- # Design system Design seed from the originator: **the user's request** DEFINE stage, optional depth. Inputs: `.delivery/initiatives//brief.md`, `.delivery/personas/`, plus any existing tokens in the codebase. Output: `.delivery/initiatives//design-system.md`. ## Conventions Read [host capability guidance](../../references/runtime.md) and [delivery conventions](../../references/conventions.md) before running this phase. ## Gate check Read any `.delivery/product-map.json` owner lens and what must survive before proposing a visual direction. Follow the [product contract](../../references/product.md): preserve stated intent, label inference, check critical gates before polish and use a bounded refinement/reframe with baseline and rollback. Do not turn an owner's preference into measured customer benefit or a universal aesthetic score. Read the brief and the personas. - **Brief missing** — stop, run `$delivery:brief`. - **Personas missing** — warn. Look and feel is a claim about who the product is for; without personas you are designing for an imagined average user and no choice can be justified. Offer to run `$delivery:personas` first. - **Existing design system in the codebase** — find it before proposing anything. Look for token files, theme configuration, a component library, established conventions. Read them and cite real paths. Extending an existing system beats introducing a second, parallel one, even when the existing one is imperfect. If `.delivery/initiatives//design-system.md` already exists, read it and ask whether to **revise**, **replace**, or **start new version**. See `../../templates/version-history.md` for what each means, the same-problem test that chooses between revise and start new version, and the Version-history table and Corrections log it writes. Never silently overwrite. If `the user's request` is empty and no seed is on record, ask the originator for one before proceeding: what should this feel like, who should feel welcomed by it, is there a reference they admire, and are there fixed brand constraints such as a logo, a colour or a typeface. A design system invented with no seed will be arbitrary, and arbitrary decisions are the hardest to defend later. **Open blocking findings.** Apply the conventions' *Open blocking findings* check to every artifact this phase consumes before going further. ## Run **1. Extract rules from the seed.** Use the `design-lead` lens. A seed is a direction, not a design — the job is to make the rules it implies explicit. Be scrupulous about the boundary between **seeded** and **inferred**. If the originator gave one accent colour, the rest of the palette is your extrapolation and must be labelled as such, with what it was optimised for. They may care deeply about something you treated as free, and they can only tell you if they can see which is which. **2. Tie identity to personas.** Every significant choice names the persona it serves and what it signals to them. Where a choice serves one persona and alienates another, surface it as a decision rather than resolving it silently. **3. Define the tokens.** Colour, type scale, spacing scale, radii, elevation, motion. Named with stated intent, not raw values. Map onto the project's real token file names where one exists. Cover the cases implementers will actually hit — a missing token is the reason hardcoded values appear. **4. Specify component states.** Default, hover, focus, active, disabled, loading, **error and empty**. The last two are where design most often supplies nothing and users most need direction. **5. Compute accessibility, do not assert it.** State actual contrast ratios for every text/background pairing, specify focus indicators, touch target sizes, reduced-motion behavior, and the text-scaling policy. If a seeded brand colour fails contrast, say so plainly and give the accessible variant — this is exactly the finding the originator needs early, since it is nearly impossible to retrofit. **6. Say what is deliberately unstyled**, so nobody fills the gap with an invention. **7. Challenge it.** Run `$delivery:challenge .delivery/initiatives//design-system.md`, which puts `design-lead`, `user-researcher`, `qa-strategist` and `feature-critic` on it, plus the skeptic persona. Fold blocking findings in. ## Write Write to `.delivery/initiatives//design-system.md` using `../../templates/design-system.md`. ## Exit criteria - Within the template's budget, or the overrun declared in the document with its reason — measure prose when computation is available; otherwise report word count unverified - Seeded versus inferred is marked on every significant decision - Tokens are named with intent and mapped to real project token names where they exist - Every component spec covers error and empty states - Contrast ratios are computed and stated, not asserted - Each identity decision names the persona it serves - Existing codebase design conventions are cited and either extended or explicitly superseded ## Writing, then revising **Budget: 600 words target, 1000 hard cap** (excludes code, YAML and data tables). Compose, measure and revise as *Writing, then revising* in the conventions says. ## Hand off Report the system, and lead with anything the seed forced that you would push back on — a brand colour failing contrast, an identity that conflicts with a persona the product needs. Those are the originator's decisions to make, and now is when they are cheap. Stories will reference these tokens by name, so implementation builds against the system rather than approximating it. Next step: `$delivery:architecture`.