Turns a static design into a numbered, testable, dev-ready specification covering every state, interaction, breakpoint, motion detail, and edge case the mockup cannot show. Use when someone asks "write the spec for this screen", "engineering keeps asking what happens when", "document the interactions before handoff", "what states does this component need", or a build came back wrong because behavior was never written down. Do NOT use for the motion token details themselves - use motion-spec instead; for verifying a finished build against the spec, use design-qa-checklist.
Click to play with sound.
---
name: Prototype Spec
description: Turns a static design into a numbered, testable, dev-ready specification covering every state, interaction, breakpoint, motion detail, and edge case the mockup cannot show. Use when someone asks "write the spec for this screen", "engineering keeps asking what happens when", "document the interactions before handoff", "what states does this component need", or a build came back wrong because behavior was never written down. Do NOT use for the motion token details themselves - use motion-spec instead; for verifying a finished build against the spec, use design-qa-checklist.
---
# Prototype Spec
A static mockup shows one moment of one state on one screen size; engineering has to invent everything else, and every invention is a coin flip that lands in QA or in production. This skill converts a design into numbered, testable behavior statements so the build matches intent the first time, instead of surfacing as "that's not what I meant" a sprint later.
A spec must answer three questions the mockup cannot: what happens when I touch it, what does it look like in every state, and what happens when something goes wrong.
## Operating procedure
Order matters: the element inventory (Step 2) feeds every later step, and states must exist before interactions can reference them.
### Step 1: Gather inputs
1. The design files and which screens are in scope.
2. Fidelity target - pick from the ladder below; do not spec at higher fidelity than the decision requires.
3. Supported breakpoints and input modes (touch, pointer, keyboard).
4. The design token and motion system names, so the spec references tokens, never raw values.
5. Known backend realities: what can be slow, what can fail, what can be empty. If unknown, mark each as a guess and flag for engineering confirmation.
**Fidelity ladder** - match spec depth to project phase:
… install to load the full skill