/design

name: design
description: 'Use when starting UI work, defining palettes or tokens, fixing AI-generic UI, or persisting a design system to DESIGN.md (modes: implement, persist). Not for live URLs: use web-design-review.'

Design

Contract

| Field | Bound contract | |---|---| | Trigger | Starting UI work, defining palettes or design tokens, correcting AI-generic, vibe-coded, or default-framework design, or persisting an approved design system to DESIGN.md. | | Authority | Reversible local: writes only local UI direction, token, and implementation artifacts; persist mode also writes DESIGN.md, CLAUDE.md pointers, and preview artifacts. Rollback is version control. No remote mutation. | | Side effect | Local writes to the picked mode's artifacts only, bounded to the current project directory. | | Done | Implement mode: one defensible direction is implemented consistently across palette, typography, spacing, density, and motion, and the audit passes clean. Persist mode: an approved design system is persisted in DESIGN.md. |

Inputs

• Mode: `implement` (direction and token implementation) or `persist` (propose, preview, and persist an approved system to DESIGN.md). Required; default `implement` when unstated.
• The surface being designed (landing, dashboard, settings, docs, one-screen tool, TUI, CLI, desktop app). Required.
• The runtime or framework in use (vanilla CSS/HTML, React/Tailwind/shadcn, Bubble Tea/Ratatui/Textual, clap/cobra/cmdliner/typer, Tauri/Slint/egui/Iced, Qt/QML). Required before step 6 in implement mode.
• Primary user and density target. Required for framing; state assumptions if not supplied.
• Existing project context (PRD, brand brief, design tokens, component library, an existing DESIGN.md to extend). Optional; load when present.
• Persist mode only: user approval is the in-loop gate. No design system is persisted until the user approves it.

Procedure

Direction precedes tokens; tokens precede code. The picked direction is the contract. Restraint is the default; reach for decoration only when a named surface goal demands it. Balance, not maximalism, not minimalism.

1. **Frame the surface.** Identify register first: **brand** (marketing, landing, campaign, long-form, portfolio; design IS the product) or **product** (app UI, admin, dashboard, tool; design SERVES the product). Detection rule, first match wins: (a) cue in the task ("landing page" / "campaign hero" → brand; "dashboard" / "settings panel" → product); (b) surface in focus or route segment (`/marketing/*` vs `/app/*`); (c) register field in project context. Then capture surface, primary user, density target, and motion budget in ms. Write one sentence of physical scene (who, where, ambient light, mood) that forces the dark/light decision; category names alone do not force the answer. Mode persist: read any existing DESIGN.md, tokens, and brand guidance first; name missing context rather than inventing it. **Done when:** register is named, the four framing fields are captured, and the dark/light sentence is written.

2. **Diverge: 3-4 directions in parallel with forced contrast.** Dispatch one exploration per direction with a constraint that forces contrast (post-minimalism vs neo-brutalism vs Material 3 vs Fluent, or named taste anchors pulling in opposite directions). Reject converged outputs; re-dispatch with sharpened constraints if two directions read alike. Diversity techniques: verbalized sampling, actor-critic per candidate, persona injection, temperature, most-unlikely reframing, anti-pattern catalog. **Done when:** 3-4 directions are produced and no two read alike under a headline-swap test.

3. **Return a fixed shape per direction.** Each direction states: name (one or two words), 1-2 taste anchors (Linear / Stripe / Things 3 / Rosé Pine / Are.na; name the references), OKLCH palette stub (4-6 swatches, never the default Tailwind ramp), type pair (display + text, named families), spacing scale subset committed (e.g. 4/8/16/24/48), motion budget in ms with one easing curve. Mode persist: the fixed plan also covers component primitives and interaction states. **Done when:** every direction carries all six fields (eight in persist mode) with no defaults borrowed from a framework ramp.

4. **Pick via per-axis single-select.** Each axis (direction, density, motion budget, type pair) is its own single-select question; the recommended option carries `(Recommended)` and is placed first. Ticking `(Recommended)` is accepting the default. Never use multiSelect for axis-with-default override semantics: it collapses N independent decisions into one ambiguous checklist. Reserve multiSelect for additive picks only. **Done when:** one option is selected per axis and the picked direction is named.

5. **Derive tokens from the picked direction.** Color, type, space, radius, shadow, motion: each a token, each referenced, not hardcoded. Pick the color strategy before picking colors: **Restrained** (tinted neutrals plus one accent at ≤10% surface coverage; product default), **Committed** (one saturated color carries 30-60% of the surface; brand default for identity pages), **Full palette** (3-4 named roles, each deliberate; brand campaigns, product data viz), **Drenched** (the surface IS the color; brand heroes, campaign pages). The ≤10% accent cap applies only to Restrained. Express tokens in the runtime's native token system: CSS custom properties for web, theme or design-token objects for React, style structs for TUI and desktop, palette constants for CLI. Tokens precede component code; component code references tokens. **Done when:** the six token families are expressed in the runtime's native system and referenced, not hardcoded.

6. **Apply the picked mode.**

• Mode implement: implement against the runtime. Apply the cross-surface invariants regardless of runtime. Audit the result against the anti-slop charter. **Done when:** implementation references the committed tokens and the audit fla