design-before-codelisted

# Design Before Code ## The Law ``` CODE WRITTEN WITHOUT A SPEC IS ALWAYS A PROTOTYPE. "I'll design it as I build it" produces UI shaped by what was easy to code — not by what users need. A written layout, state definitions, final copy, and interaction map IS a spec. ``` ## When to Use Trigger before: - Implementing any new AI feature UI component - Refactoring a component that changes its interaction model - Adding a new page or major section to an AI product - Implementing the output of an agent or multi-step AI workflow ## When NOT to Use - Hotfixes to existing, already-designed components (wording changes, colour tweaks) - Backend-only changes with no UI surface - Prototypes explicitly scoped as throwaway (label them as such) ## The Spec Format A spec does not need to be a Figma file. It needs to answer four questions: ### 1 — Layout What is the visual structure? Describe it in words or ASCII: ``` ┌─────────────────────────────────┐ │ [Avatar] User message │ │ │ │ AI response [Avatar] │ │ ─ ─ streaming ─ ─ │ │ │ │ [Prompt input ___________] [▶] │ └─────────────────────────────────┘ ``` Note: column widths, alignment, responsive behaviour (stacks on mobile? collapses?), max-width constraints. ### 2 — States Which states does this component have? (See `ai-states-required` for the full list.) For each state, note the visual difference. ``` | State | Visual ch