Skip to content

handoff-spec — playbook

Produce a developer handoff document from a finalized design. The output is a single markdown file an engineer can implement against without follow-up questions.

When to use

  • Design is approved and ready to ship; engineering needs a spec.
  • A Figma file has 6+ screens and devs keep DM'ing for clarifications.
  • Cross-team handoff (design → another team's eng).

Inputs (ask if missing)

  1. Designs — Figma link or screenshots of the final state.
  2. Scope — single feature, full screen, multi-screen flow.
  3. Tech stack — for code-side conventions (Tailwind class hints, MUI props, etc.).
  4. Existing design system? — if yes, name it and let the spec reference tokens; if no, inline the values.
  5. Audience — frontend dev, full-stack, design engineer.

Steps

1. Inventory

List every screen and every reusable component on each. If components are repeated, note them once and reference.

2. For each screen, document

  • Purpose — one sentence on what the screen accomplishes.
  • Entry points — how the user reaches it (route, button, deep link).
  • Exit points — what actions navigate away and where.
  • Layout — wireframe diagram + breakpoints behavior.
  • States — empty, loading, error, success, partial data.
  • Edge cases — what happens with very long content, zero items, network failure.

3. For each component, document

If it's an existing system component, just reference it: "Use <Button intent='primary' size='lg'> from our system." Don't re-spec.

If it's new, follow the component-spec-writer skill's playbook to produce a full sub-spec.

4. Document interactions

For every interactive element, document:

Element Trigger Action
Save button click / Enter while focused Persist form, show toast on success, redirect to detail page
Discard link click Open confirmation modal; on confirm, route to list

5. Document data and content

  • Data shape — what does the server return? What's required vs optional?
  • Content rules — character limits, validation rules, empty-string behavior.
  • i18n — keys used, plurals, RTL considerations.
  • Tone — formal/casual; example copy that hits the bar.

6. Document responsive behavior

For each breakpoint (xs/sm/md/lg/xl), describe: - Layout changes (column count, sidebar collapse, nav transformation). - Component swaps (e.g., "tabs become accordion below md"). - Hidden / shown elements.

7. Document a11y requirements

  • Semantic HTML expected (which <h1> / <nav> / <main> lives where).
  • Keyboard interaction map (what Tab reaches, in what order).
  • ARIA roles / properties for complex widgets.
  • Focus management (where focus goes on route change, modal open/close).
  • Announcements (live regions for toast/error).

8. Document analytics events (if applicable)

Event name Trigger Properties
signup_completed After successful signup method, referrer, plan

9. Open questions (be explicit)

Don't leave decisions implicit. List anything ambiguous:

Open: When the user has 0 saved items, do we show the empty state OR auto-redirect to onboarding? Need product to decide before ship.

10. Output

# Handoff: <feature name>

> Designs: <link>
> System: <existing? name?>
> Stack: <stack>
> Owner: <name>
> Status: ready-for-implementation

## Summary
<3 sentences: what this is, who it's for, what done looks like>

## Screens
### <Screen 1 name>
- Purpose:
- Entry/Exit:
- Layout (with sketch):
- States:
- Edge cases:

### <Screen 2 name>
...

## Components
### <Component A>
- (existing system component, no re-spec) | (full sub-spec inline)

## Interactions
<table>

## Data and content
- ...

## Responsive
- xs: ...
- md: ...
- xl: ...

## Accessibility
- ...

## Analytics
<table or skip>

## Open questions
- [ ] <question>

## References
- Designs: <link>
- Component system: <link>
- Token reference: knowledge/design-tokens/...

Source files this skill reads

Verification phase (run before declaring done)

  • Every screen has: purpose, entry/exit, layout, states, edge cases?
  • Every component is either a system reference OR has an inline sub-spec?
  • Are interactions documented as a table (element / trigger / action)?
  • Is responsive behavior named per breakpoint (xs / sm / md / lg / xl)?
  • Are a11y requirements explicit (semantic HTML, ARIA, keyboard, focus management)?
  • Are analytics events listed (or explicitly "none for v1")?
  • Are open questions listed (not implicit)?
  • Could an engineer implement without DM'ing the designer? (If unsure, you've left an open question.)
  • Are design tokens referenced by name, not inlined as hex?

Done when

  • One markdown file, end-to-end.
  • Every screen has purpose, layout, states, edge cases.
  • Every component has a system-reference OR a sub-spec.
  • Interactions table is complete.
  • Responsive behavior is named per breakpoint.
  • A11y requirements are explicit.
  • Open questions are listed (or "none").
  • An engineer would not need to ask design follow-up questions to implement.
  • The verification phase checklist passes.