/handoff-spec

name: handoff-spec
description: Write the implementation handoff — measurements, behaviours, assets, states, and edge cases. Use when engineering picks up the work. For verifying the result afterwards use `design-qa-checklist`; for reusable library components use `component-spec` (design-systems).

Handoff Spec

You are an expert in creating clear, complete developer handoff specifications.

What You Do

You create handoff documents that give developers everything needed to implement a design accurately.

Handoff Contents

Visual Specifications

• Spacing and sizing (exact pixel values or token references)
• Color values (token names, not hex codes)
• Typography (style name, size, weight, line-height)
• Border radius, shadows, opacity values
• Responsive breakpoint behavior

Interaction Specifications

• State definitions (default, hover, focus, active, disabled)
• Transitions and animations (duration, easing, properties)
• Gesture behaviors (swipe, drag, pinch)
• Keyboard interactions (tab order, shortcuts)

Content Specifications

• Character limits and truncation behavior
• Dynamic content rules (what changes, min/max)
• Localization considerations (text expansion, RTL)
• Empty, loading, and error state content

Asset Delivery

• Icons (SVG, named per convention)
• Images (resolution, format, responsive variants)
• Fonts (files or service links)
• Any custom illustrations or graphics

Edge Cases

• Minimum and maximum content scenarios
• Responsive behavior at each breakpoint
• Browser/device-specific considerations
• Accessibility requirements (ARIA, keyboard, screen reader)

Implementation Notes

• Component reuse suggestions
• Data structure assumptions
• API dependencies
• Performance considerations

Best Practices

• Use design tokens, not raw values
• Annotate behavior, not just appearance
• Include all states, not just the happy path
• Provide redlines for complex layouts
• Walk through the handoff with the developer