Handoff Spec

Process

Step 1: Understand the design

• If given a Figma URL, use Figma MCP to get design context and screenshot
• If given a description, clarify any ambiguities before speccing
• If given existing code, document the intended behavior

Step 2: Generate the spec

Output a structured markdown spec with these sections:

Overview

• What this component/page/flow does
• User goal
• Where it appears in the app

Component Breakdown For each component in the design:

### [Component Name]
- Type: [new / existing shadcn / modified]
- Props: [list with types]
- Children: [nested components]

Visual Specifications

• Layout: flex/grid, direction, alignment, gap values
• Spacing: exact values from the 4/8/12/16/24/32 scale
• Typography: which text style for each element
• Colors: semantic color tokens used (not hex values)
• Borders/shadows: which elements have them, exact values
• Responsive: how the layout changes at 320px / 768px / 1024px+

Interaction States For every interactive element:

[Element]:
  Default: [description]
  Hover: [description + timing]
  Focus: [description]
  Active/Pressed: [description]
  Disabled: [description + when this state occurs]
  Loading: [description + when this state occurs]

Animation Specs For every transition/animation:

[What animates]:
  Trigger: [hover / click / page load / state change]
  Property: [opacity, transform, etc.]
  Duration: [ms]
  Easing: [curve]
  Delay: [if staggered]

Data Requirements

• What data does this component need?
• What happens when data is: empty, loading, error, partial, overflowing?
• Character limits or truncation rules
• Sorting/filtering behavior (if applicable)

Edge Cases

• Long text: truncate with ellipsis after N lines / expand on click / wrap
• Empty state: what to show when there's no data
• Error state: what to show when the request fails
• First-time use: any onboarding or empty state guidance
• Permission-based: what changes for different user roles

Accessibility Notes

• Keyboard interaction pattern (tab order, shortcuts)
• ARIA roles and labels needed
• Screen reader announcements for dynamic content
• Focus management for modals/overlays

Step 3: Output

• Write the spec as a clean markdown document
• Use tables for specs with many values (spacing, colors)
• Include a "Questions for engineering" section if anything is ambiguous