design-spec

# Design specification ## Usage ```text /design-spec <area> <feature> /design-spec handoff <area> <feature> ``` Read the current PRD, decisions, discovery evidence, feasibility analysis, and prototype results from `workspace/<area>/projects/<feature>/`. Do not silently resolve product questions that remain open. Use `context/templates/design_spec_template.md` and save `design-spec.md` beside the project artifacts. ## Required content ### Context and outcomes - target user, task, and entry point; - problem evidence and success criteria; - approved scope, non-goals, and unresolved decisions; - links to source artifacts. ### Flow and screen inventory List each screen, overlay, step, and branch. Include the happy path plus loading, empty, partial, error, offline, permission, validation, destructive-action, success, and recovery states where relevant. ### Per-screen specification For each screen define: - purpose and primary action; - information hierarchy and layout regions; - exact content or content rules; - interaction and keyboard behavior; - state transitions and navigation; - validation, errors, and recovery; - analytics events when required; - responsive and accessibility behavior. ### Components and tokens Map UI elements to components only from a verified target design system. If no design system is known, specify semantic component roles and mark package selection open. Reference verified tokens for color, spacing, type, elevation, motion, and breakpoints; do not invent brand values. ### Data and permissions Document visible fields, source, freshness, formats, limits, role behavior, and privacy constraints. Keep product data requirements separate from speculative implementation details. ## Handoff package When `handoff` is requested, create: ```text design-handoff/ README.md design-spec.md component-map.md content-strings.md flows.md wireframe/ ``` Include only artifacts that add value. A textual flow or low-fidelity wireframe is sufficient when a visual mock is not needed. ## Completion check - Every approved requirement appears in a flow, screen, or state. - Every user-visible state has content and recovery behavior. - Component mappings are verified or explicitly open. - Keyboard, focus, labels, contrast, and responsive behavior are addressed. - Destructive and consequential actions include confirmation and feedback. - Open questions have owners or a decision path when known. - No unsupported product availability, technical feasibility, or delivery claim is introduced.