/design-handoff
If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.
Generate comprehensive developer handoff documentation from a design.
Usage
/design-handoff $ARGUMENTS
Generate handoff specs for: @$1
If a Figma URL is provided, pull the design from Figma. Otherwise, work from the provided description or screenshot.
What to Include
Visual Specifications
-
Exact measurements (padding, margins, widths)
-
Design token references (colors, typography, spacing)
-
Responsive breakpoints and behavior
-
Component variants and states
Interaction Specifications
-
Click/tap behavior
-
Hover states
-
Transitions and animations (duration, easing)
-
Gesture support (swipe, pinch, long-press)
Content Specifications
-
Character limits
-
Truncation behavior
-
Empty states
-
Loading states
-
Error states
Edge Cases
-
Minimum/maximum content
-
International text (longer strings)
-
Slow connections
-
Missing data
Accessibility
-
Focus order
-
ARIA labels and roles
-
Keyboard interactions
-
Screen reader announcements
Principles
-
Don't assume — If it's not specified, the developer will guess. Specify everything.
-
Use tokens, not values — Reference spacing-md not 16px .
-
Show all states — Default, hover, active, disabled, loading, error, empty.
-
Describe the why — "This collapses on mobile because users primarily use one-handed" helps developers make good judgment calls.
Output
Handoff Spec: [Feature/Screen Name]
Overview
[What this screen/feature does, user context]
Layout
[Grid system, breakpoints, responsive behavior]
Design Tokens Used
| Token | Value | Usage |
|---|---|---|
color-primary | #[hex] | CTA buttons, links |
spacing-md | [X]px | Between sections |
font-heading-lg | [size/weight/family] | Page title |
Components
| Component | Variant | Props | Notes |
|---|---|---|---|
| [Component] | [Variant] | [Props] | [Special behavior] |
States and Interactions
| Element | State | Behavior |
|---|---|---|
| [CTA Button] | Hover | [Background darken 10%] |
| [CTA Button] | Loading | [Spinner, disabled] |
| [Form] | Error | [Red border, error message below] |
Responsive Behavior
| Breakpoint | Changes |
|---|---|
| Desktop (>1024px) | [Default layout] |
| Tablet (768-1024px) | [What changes] |
| Mobile (<768px) | [What changes] |
Edge Cases
- Empty state: [What to show when no data]
- Long text: [Truncation rules]
- Loading: [Skeleton or spinner]
- Error: [Error state appearance]
Animation / Motion
| Element | Trigger | Animation | Duration | Easing |
|---|---|---|---|---|
| [Element] | [Trigger] | [Description] | [ms] | [easing] |
Accessibility Notes
- [Focus order]
- [ARIA labels needed]
- [Keyboard interactions]
If Connectors Available
If ~~design tool is connected:
-
Pull exact measurements, tokens, and component specs from Figma
-
Export assets and generate a complete spec sheet
If ~~project tracker is connected:
-
Link the handoff to the implementation ticket
-
Create sub-tasks for each section of the spec
Tips
-
Share the Figma link — I can pull exact measurements, tokens, and component info.
-
Mention edge cases — "What happens with 100 items?" helps me spec boundary conditions.
-
Specify the tech stack — "We use React + Tailwind" helps me give relevant implementation notes.