| name | design-handoff-patterns |
| description | Use when handing designs to engineering. Covers Figma handoff, design tokens export, spec annotation, the difference between handoff and collaboration, and the rituals that eliminate '?' Slack messages.
|
Design Handoff Patterns
Good handoff is a continuous conversation, not a single Figma link.
Pre-handoff hygiene
Before sharing a design:
- ☑ Components used (not detached layers)
- ☑ Auto-layout applied throughout
- ☑ Tokens used for colors / spacing / type
- ☑ Naming follows convention
- ☑ Mobile + desktop variants present
- ☑ Hover / focus / disabled states shown
- ☑ Empty / loading / error states covered
The 80% rule: if these aren't done, expect 80% more questions.
Annotations to include
Annotate edge cases inline:
- Truncation rules ("name truncates with tooltip after 24 chars")
- Empty states ("if list is empty, show empty-state pattern")
- Loading states ("skeleton matches row height")
- Responsive breakpoints ("stacks vertically below 768px")
- Conditional UI ("admin sees delete button, others don't")
- Animation specs ("button lift 200ms, ease-out")
Spec annotations vs comments
| Inline annotations | Comments |
|---|
| Permanent design specs | Conversational questions |
| Visible to all | Threaded discussion |
| Define behavior | Resolve ambiguity |
Use annotations for what eng needs to know. Comments for ad-hoc discussion.
Handoff rituals
- Design review with eng pair (live walk-through)
- Loom video explaining decisions and intent
- Spec doc for complex interactions
- Token export if non-Figma-aware tools
- Sync after first mockup-to-code pass
What designers should NOT do
- Hand off a flat PNG (kills inspection)
- Use random hex values instead of tokens
- Skip the empty / error states
- Skip mobile
- Disappear after handoff (review is part of the job)
What engineers should NOT do
- Refuse to ask questions ("I'll just figure it out")
- Substitute their own tokens / spacing without flagging
- Ship without designer review
- Add micro-animations without spec
Token export
Use the Figma Tokens plugin (Tokens Studio) to export design tokens to JSON. Pipeline to CSS variables / native platforms via Style Dictionary.
Common mistakes
- Designer ships Figma at "looks done" without empty / error states
- Engineer pixel-pushes from a static PNG without using tokens
- Two-way drift: code has tokens designer didn't see
- "Definition of done" includes screenshots but not interaction
- Handoff = end of designer's involvement
Where this fits in X3 Compass
X3 Compass is currently no-Figma (Joshua + AI direct to code). When team grows, would add Figma + handoff rituals.
