design

Design

Contract

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.