Skip to content
Skills Library
Design & UX · Writing

prototype-spec

/prototype-spec

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.

Repository
skills ↗
Licence
MIT
Last repository change
13.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Triggers from the description

write the spec for this screenengineering keeps asking what happens whendocument the interactions before handoffwhat states does this component need
Original author 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.

How it works

  1. Operating procedure
  2. Spec skeleton (copy and fill)
  3. Deliverable
  4. Common handoff failure modes
  5. Quality bar
Original SKILL.md headings · 118 lines, 1,093 words
SKILL.md preview
---
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.
metadata:
  title: "Prototype Spec"
---

# 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:

- **Lo-fi** (concept validation, early usability tests): flows and layout intent only; no redlines, no motion. Speccing pixel details here wastes work that the next iteration deletes.
- **Mid-fi** (scoping, estimation): element inventory, key states, happy-path interactions.
- **Hi-fi / dev-ready** (build handoff): everything below - full states, redlines, motion, breakpoints, edge cases. This is the level the rest of this procedure produces.

### Step 2: Inventory the interactive elements

List every control per screen: buttons, inputs, toggles, draggables, scroll regions, gestures. Anything a user can act on gets a row. This inventory is the spec's table of contents - an element missing here is behavior nobody specs.

### Step 3: Specify states

For each element, define every visual state: default, hover, focus, active/pressed, disabled; loading, success, error where applicable; selected/unselected, expanded/collapsed. Describe what changes between states (color, elevation, label, icon) by token name, not raw hex or px. A button with fewer than five defined states is almost always underspecified.

### Step 4: Specify interactions as trigger → response

Write each as a four-part statement:

- **Trigger** - the exact input: tap, hover 300ms, drag past 40px, Enter key, scroll past threshold.
- **Response** - what changes: state change, navigation, data mutation.
- **Transition** - duration, easing, and what animates, by motion-system token (defer curve/duration definitions to motion-spec).
- **Feedback** - immediate acknowledgment within 100ms: ripple, spinner, optimistic update. If the response can take longer than 400ms, a loading affordance is mandatory.

### Step 5: Specify screen transitions

For navigations and overlays: enter and exit animation (direction, duration token, easing token); whether the previous screen persists, dims, or unmounts; shared-element transitions if any element morphs across screens.

### Step 6: Specify breakpoints and redlines

- Per supported breakpoint: what reflows, what collapses, what disappears, and minimum touch target (44x44px on touch).
- Redlines by token: spacing, sizing, and type references engineering can map to code constants. A raw pixel value in a spec is a future inconsistency.

### Step 7: Specify edge and error behavior

Document every unhappy path: empty, loading, and error states for each data-driven view; slow-network behavior (skeletons, progressive reveal, timeout threshold and what happens at it); validation timing - on blur, on submit, or live, chosen deliberately per field; concurrency - double-tap, rapid navigation, offline. Spell out conditional logic in plain language: "If the cart is empty, the Checkout button is disabled and shows tooltip X." Cover every branch the design implied but did not draw.

### Step 8: Specify accessibility behavior

Focus order and focus trapping for modals; keyboard equivalents for every pointer interaction; live-region announcements for dynamic content; visible focus states already covered in Step 3.

### Step 9: Format as numbered, testable statements

Group by screen, then by element. Each statement must be verifiable by a QA engineer without a follow-up question - "feels snappy" is not a spec; "transition completes in duration-fast with easing-exit" is.

## Spec skeleton (copy and fill)

```
SPEC - [FILL: screen name]            Fidelity: hi-fi / dev-ready
Tokens referenced: [FILL: token set + motion system names]

ELEMENT INVENTORY
  E1 [FILL: element]   E2 [FILL: element]   ...

E1 - [FILL: element name]
  STATES
    default: [FILL: tokens]        hover: [FILL]
    focus: [FILL: visible ring]    active: [FILL]
    disabled: [FILL + why it can be disabled]
    loading / error: [FILL or "n/a because ..."]
  INTERACTIONS
    1. Trigger: [FILL] → Response: [FILL]
       Transition: [FILL: duration + easing tokens] Feedback: [FILL, <100ms]
  BREAKPOINTS
    ≥1024: [FILL]   768-1023: [FILL]   <768: [FILL, touch targets ≥44px]
  EDGE CASES
    Empty: [FILL]  Slow (>400ms): [FILL]  Error: [FILL]
    Double-tap / rapid nav: [FILL]  Offline: [FILL]
  ACCESSIBILITY
    Keyboard: [FILL]  Focus order: [FILL]  Announcements: [FILL]

CONDITIONAL LOGIC
  If [FILL condition], then [FILL behavior].

OPEN QUESTIONS FOR ENGINEERING
  [FILL: every guessed backend behavior, labeled "guess"]
```

## Deliverable

Produce a spec document containing: the element inventory, a state matrix per element, numbered trigger → response interaction statements with motion tokens, screen-transition specs, breakpoint behavior with token-based redlines, edge-case and conditional-logic statements, accessibility behavior, and an open-questions list - ready to hand directly to engineering.

## Common handoff failure modes

- **The happy-path-only spec** - error, empty, and loading states get invented by whoever writes the code, and they will not match the design language.
- **Raw values instead of tokens** - engineers hard-code the pixel value; the next design-system update misses it.
- **Untestable prose** - "should feel responsive" produces a QA argument, not a check.
- **State gaps** - hover and focus omitted because the mockup was drawn for touch; the desktop build ships with dead-feeling controls.
- **Silent assumptions about the backend** - a spec that assumes instant responses breaks the moment latency is real; every timing assumption must be written and flagged.
- **Speccing motion values inline** - durations and curves drift per component; reference the motion system and keep the definitions in motion-spec.

## Quality bar

- Every element in the inventory has all Step 3 states or an explicit "n/a because…".
- Every interaction statement is individually verifiable by QA with no follow-up question.
- Zero raw color/spacing/duration values - tokens only.
- Every data-driven view has empty, loading, error, and slow-network behavior.
- Every guessed value is labeled a guess and listed under open questions.
- After the build, design-qa-checklist can be run directly against the numbered statements.

Versions

The database has no other skills named prototype-spec.

Database snapshot: 13.11.2026 · package version 84c1ed2725c8 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90wire-spec
    Write a developer handoff spec for a component or feature — states, tokens, edge cases. Use when asked to "write a handoff spec", "spec this component for engineering", or "document component states".
  • 100design-handoff
    Generate developer handoff specs from a design. Use when a design is ready for engineering and needs a spec sheet covering layout, design tokens, component props, interaction states, responsive breakpoints, edge cases, and animation details.
  • 90handoff-spec
    Write the implementation handoff — measurements, behaviours, assets, states, and edge cases. Use when engineering picks up the work. For verifying the result afterwards use `design-qa-checklist`; for reusable library components use `component-spec` (design-systems).
  • 86d2s-spec
    Stage 5 (spec) of a discovery-to-spec design exploration. Turns the approved direction into a buildable UX spec covering screens and flow, states (empty, loading, error, no permission), edge cases, testable acceptance criteria, accessibility, copy and the design-system…
  • 100design-handoff
    Generate developer handoff specs from a design. Use when a design is ready for engineering and needs a spec sheet covering layout, design tokens, component props, interaction states, responsive breakpoints, edge cases, and animation details.
  • 90design-handoff
    Use when a design is ready for engineering — produce an implementation-ready spec covering layout, tokens, states, responsive behavior, edge cases, motion, and accessibility.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.