Skip to content
Back to Design Hub

Design Handoff to Developers

Specs, tokens, and review loops that eliminate 'it looks different in code' drift.

Design SystemsIntermediate

Why

The design-to-code handoff is where 80% of visual bugs originate: missing specs, ambiguous spacing, undocumented states (hover, focus, error). A structured handoff with tokens, redline specs, and a review loop cuts implementation rounds from 5 to 2.

According to the 2024 Spark Design Systems survey, 78% of organizations with a design system report faster product delivery. JavaScript is used by 62% of developers per the Stack Overflow 2024 survey and component libraries that align with design tokens cut handoff time by 60%.

When

Formalize handoff when design and engineering are separate people (or teams). Solo dev-designers can skip specs, but any team of 2+ benefits from a defined handoff artifact.

How

1. Use Figma Dev Mode — inspect panel shows CSS, spacing, tokens; no manual redlining 2. Define states — default, hover, focus, active, disabled, error for EVERY interactive component 3. Attach tokens — Figma variables bound to code tokens via Tokens Studio plugin 4. Export assets — SVG for icons (inline), WebP for photos, @2x/@3x for any raster 5. Write spec doc — component name, anatomy, states, props, do/don't, usage examples 6. Review loop — dev implements, designer reviews in PR or staging, comment with screenshots 7. Sign-off — designer approves in Figma comment thread, linked from the PR

Example

# Button spec — handoff document (Markdown) ## Anatomy [Icon?] Label [Badge?] ## States (all must be implemented) | State | Background | Border | Shadow | |----------|--------------------|-----------|-----------------| | default | --color-action-pri | none | --shadow-sm | | hover | --color-action-hov | none | --shadow-md | | focus | --color-action-pri | 2px ring | none | | disabled | --color-surface-3 | none | none, opacity .5| ## Props - variant: "primary" | "secondary" | "ghost" (default: "primary") - size: "sm" | "md" | "lg" (default: "md") - icon: ReactNode (optional, placed before label) - loading: boolean (shows spinner, disables click) ## Do - Use primary for the single most important action per view - Pair icon + label for recognition (e.g. [+] Add) ## Don't - Use ghost for primary actions — it reads as non-interactive - Stack 3+ primary buttons — visual hierarchy collapses ## Figma Frame: "Button v2.3" → https://figma.com/file/abc?node=42

Common Problems

  • ⚠Dev Mode ignored — devs eyeball spacing from screenshots, get 12px vs 16px wrong
  • ⚠Missing states — designer specs default + hover, forgets focus-visible, a11y bug ships
  • ⚠Asset format wrong — PNG for icons (no recolor), JPG for photos (no transparency, larger)
  • ⚠No review loop — designer sees implementation in production, too late to fix cheaply

Best Practices

  • ✓Make Dev Mode the single source — no separate redline docs that drift from Figma
  • ✓Spec all 6 states for interactive components — default/hover/focus/active/disabled/error
  • ✓Link Figma frame URL in the PR description — reviewer can open exact spec in one click
  • ✓Designer reviews on staging, not production — catch before customers see it

FAQ

Figma Dev Mode vs redline docs — which is better?

Dev Mode — it shows live CSS, spacing, and tokens directly from the design, so specs never drift. Redline docs are a separate artifact that goes stale within a week.

What states must I spec for an interactive component?

All six: default, hover, focus, active, disabled, error. Most handoffs spec only default + hover and ship focus-visible and disabled as a11y bugs.

How do I handle the design-to-code review loop?

Designer reviews the implementation on staging (not production), comments with screenshots, and signs off in a Figma comment thread linked from the PR.

SVG or PNG for icons in handoff?

SVG — it's recolorable via currentColor, scales without quality loss, and is smaller. PNG is raster, can't recolor, and needs @2x/@3x variants. Use PNG only for photos.

How do I stop 'it looks different in code' drift?

Bind Figma variables to code tokens via Tokens Studio, and make Dev Mode the single source. No separate spec docs — they drift from Figma within days.