What should I include in the handoff to avoid guesswork?

Visual specs, interaction details, content behavior, edge cases, accessibility information, and token references.

Why use design tokens instead of fixed pixel values?

Tokens ensure consistency across components and design systems, making updates scalable.

How do I handle missing data or slow connections in the handoff?

Document fallback states, loading behavior, and what the UI should show under those conditions.

design-handoff

Scanned

npx machina-cli add skill anthropics/knowledge-work-plugins/design-handoff --openclaw

Files (1)

SKILL.md

1.5 KB

Design Handoff

Create clear, complete handoff documentation so developers can implement designs accurately.

What to Include

Visual Specifications

Exact measurements (padding, margins, widths)
Design token references (colors, typography, spacing)
Responsive breakpoints and behavior
Component variants and states

Interaction Specifications

Click/tap behavior
Hover states
Transitions and animations (duration, easing)
Gesture support (swipe, pinch, long-press)

Content Specifications

Character limits
Truncation behavior
Empty states
Loading states
Error states

Edge Cases

Minimum/maximum content
International text (longer strings)
Slow connections
Missing data

Accessibility

Focus order
ARIA labels and roles
Keyboard interactions
Screen reader announcements

Principles

Don't assume — If it's not specified, the developer will guess. Specify everything.
Use tokens, not values — Reference spacing-md not 16px.
Show all states — Default, hover, active, disabled, loading, error, empty.
Describe the why — "This collapses on mobile because users primarily use one-handed" helps developers make good judgment calls.

Source

git clone https://github.com/anthropics/knowledge-work-plugins/blob/main/design/skills/design-handoff/SKILL.mdView on GitHub

Overview

Design Handoff creates clear, complete developer documentation from design files. It codifies visual, interaction, content, edge-case, and accessibility specs so engineers implement exactly as intended.

How This Skill Works

The process gathers design details into structured sections: Visual Specifications, Interaction Specifications, Content Specifications, Edge Cases, and Accessibility. It emphasizes tokens (e.g., spacing-md) over hard values, requires showing all states, and explains the rationale to guide implementation.

When to Use It

When a design is ready for engineering and you need precise, code-ready specs.
When translating design files into implementation guidance for frontend or mobile teams.
When tokens (colors, typography, spacing) should drive the handoff rather than hard pixel values.
When a component requires explicit states: default, hover, active, disabled, loading, error, empty.
When you must address edge cases, accessibility, internationalization, or performance considerations before development.

Quick Start

Step 1: Trigger the handoff (e.g., say "handoff to engineering" or "design specs for developers").
Step 2: Fill in Visual, Interaction, Content, Edge Cases, and Accessibility sections with exact measurements, tokens, and state coverage.
Step 3: Review for token usage, all states, rationale, and accessibility notes before sharing.

Best Practices

Don't assume—document every behavior and constraint.
Use design tokens (spacing-md, color-primary) instead of raw values.
Show all states (default, hover, active, disabled, loading, error, empty) in every spec.
Explain the rationale behind decisions to guide developers (the why).
Organize specs by Visual, Interaction, Content, Edge Cases, and Accessibility with clear cross-references.

Example Use Cases

Handoff for a responsive Card component with padding, typography, and states
Modal dialog with focus order, ARIA roles, keyboard interactions, and animations
Loading skeletons and empty-state messaging for a data table
Navigation bar with breakpoints and touch gestures
Internationalized form with character limits and truncation behavior

Frequently Asked Questions

Add this skill to your agents