design-before-code

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 change                          |
|----------|----------------------------------------|
| Loading  | Response area shows streaming cursor   |
| Error    | Red border, inline error copy          |
| Success  | Full text, feedback buttons appear     |

3 — Copy

Write the actual copy for every text element — not "label here" but the final words.

Placeholder:  "Ask anything about this document…"
Error:        "Something went wrong. Try again."
Empty:        "No messages yet. Start by asking a question."
Loading:      "Thinking…"