Design To Code Handoff

Design-to-Code Handoff

The handoff is where designs go to die. Every missing spec forces an engineer to guess; every guess is a coin flip between "matches the design" and "doesn't." This skill eliminates guessing by producing a complete, implementation-ready spec that maps every visual decision to code.

Process

1. Collect all design artifacts

Gather upstream outputs from the product design pipeline:

• Design tokens (from design-tokens) — color, spacing, radius, shadow, breakpoint definitions
• Typography scale (from typography-system) — font pairing, sizes, weights, line-heights
• Component specs (from design-system-builder) — atoms, molecules, organisms with props and states
• State matrices (from component-style-guide) — every variant × state combination
• Layout spec (from dashboard-layout-patterns) — shell pattern, grid, responsive behavior
• Motion spec (from micro-interaction-motion-design) — transitions, feedback animations, motion tokens
• User flows (from user-flow-mapping) — entry points, decision paths, error flows

If any artifact is missing, flag it — do not proceed with gaps. Every gap becomes a guess downstream.

2. Generate the component implementation checklist

For each component in the design:

• Which existing component in the codebase matches? (exact match / partial / none)
• If none, what new component is needed? Name it, describe its responsibility.
• Props/variants needed for this usage — cross-reference with component-style-guide.
• Token references for all visual properties: background, text color, padding, margin, border-radius, shadow, font-size, font-weight. No raw values allowed.
• Responsive behavior at each breakpoint — how does this component change across breakpoint-sm → breakpoint-xl?

3. Map layout to code structure

Translate the layout spec into a file/component tree:

• Which component owns which section of the layout?
• Where do data fetches live? (page level / component level / shared)
• How does routing work? Map routes from information-architecture.
• What shared state is needed? (user session, module data, UI state)

Produce a tree diagram showing the component hierarchy with file paths.

4. Spec interactions and states

For each interactive element: trigger → action → visual feedback → state change.

• Reference the component-style-guide state matrix for visual changes.
• Reference the motion spec for transition timing and easing.
• Don't leave any interaction as "obvious" — spell it out. "Button click saves form" is incomplete. "Button click → button enters loading state (spinner, disabled) → POST /api/form → on success: toast success, reset form, button returns to default → on error: toast error with message, button returns to default" is a spec.

5. Produce the implementation file list

Ordered list of files to create/modify. For each file:

• File path (following project conventions)
• Purpose (one sentence)
• Components involved (imported / exported)
• Tokens used (list token names)
• Dependencies (other files that must exist first)
• Estimated complexity: S / M / L

Order by dependency: files with no dependencies first, files that depend on others after.

6. Verify token coverage

Cross-reference every color, spacing, radius, shadow, and font-size in the spec against design-tokens. Flag any value that isn't a token — raw values are spec bugs that will diverge across components.

7. Verify flow coverage

Walk through every user flow from user-flow-mapping against the component tree:

• Can every flow be completed using the specced components?
• Are error states, loading states, and empty states covered?
• Does every CTA connect to a real route? (cross-reference with route-integrity-checker)

Completion criteria

Done when:

• Every visual element maps to a component
• Every component maps to tokens (zero raw values)
• The file list is ordered, dependency-resolved, and actionable
• Every user flow is walkable through the component tree
• Every interactive element has a trigger → action → feedback → state chain

Not done if any element says "use appropriate styling" — that's a guess, not a spec.

Output format

Implementation checklist artifact (Markdown):

1. Design artifact inventory (collected / missing)
2. Component implementation checklist (component → props → tokens → responsive)
3. Component hierarchy tree (with file paths)
4. Interaction specs (trigger → action → feedback → state)
5. Implementation file list (ordered by dependency)
6. Token coverage report (pass / violations)
7. Flow coverage report (complete / gaps)

Anti-patterns

• Handing off a screenshot instead of a spec.
• Token references that say "see design system" without specifying which token.
• Specs that describe appearance but not behavior.
• File lists without dependency ordering — leads to blocked work and circular imports.
• Skipping the flow coverage check — leads to components that render but don't connect into a usable product.