ProductOct 30, 20266 min read

Design handoff checklist: what to spec before anyone builds

Eight questions every handoff has to answer, where each answer lives in Figma, and what shrinks when both teams build from one library.

When GitHub reviewed its own accessibility audits, it found that 48% of its accessibility issues could have been prevented in the design phase. Design-phase problems are mostly unanswered questions: what the focus order is, what a screen reader announces, what happens when the list is empty.

A design handoff is the point where a design is ready to build, plus the set of decisions that travels with it. A complete handoff answers eight questions before engineering starts, covering states, responsive behavior, tokens, edge cases, accessibility, motion, content, and acceptance criteria.

Key takeaways

A handoff is complete when an engineer can build every state without asking a question.
Specify tokens rather than raw values, so 16px becomes space-4 and survives the next theme change.
Design zero, one, many, and too many for every list, because edge cases cause more rework than visual details.
Accessibility, motion, and content need written annotations, because none of them can be read from a static frame.
When both teams build from one shared component library, the handoff shrinks to what the library doesn't already answer.

The eight-question handoff checklist

Use this as the gate before a file is marked ready for dev.

Question	Deliver	Where it lives	Done when
1. Which states exist?	Every state of new or changed components	Variants	No state exists only in words
2. How does it respond?	Smallest and largest layouts, plus reflow rules	Breakpoint frames	Wrap, stack, and hide rules are written
3. Which tokens apply?	Values bound to variables	Variables in Dev Mode	No raw hex or pixel values
4. What are the edge cases?	Empty, loading, error, long content	An edge-case frame	Zero, one, many, too many are drawn
5. Does it work without a mouse?	Focus order, labels, headings, targets	Accessibility annotations	The keyboard path is written
6. How does it move?	Trigger, duration, easing, fallback	Motion annotations	Reduced motion is defined
7. What does it say?	Final copy, limits, errors	Content annotations	No placeholder text
8. How will we know it's done?	Acceptance criteria	The linked ticket	QA can test unaided

Run it on what changed, not the whole product.

States, responsive behavior, and tokens

States

Draw every state that changes appearance: default, hover, focus, pressed, disabled, loading, selected, and error. Focus is the one most often missing, and the one keyboard users depend on.

Responsive behavior

One frame shows one width. Draw your smallest and largest breakpoints and write the rules between them: which columns collapse and which actions move into a menu. WCAG's Reflow criterion (1.4.10, level AA) expects content to work at a width equivalent to 320 CSS pixels, which makes 320 a sensible narrowest frame.

Tokens instead of raw values

A spec that says #4F46E5 and 16px breaks at the next rebrand. Bind values to variables, and set each variable's code syntax (Figma allows one each for Web, Android, and iOS) so engineers see the name they actually type.

What do edge cases and empty states look like?

Designers draw the screen with nine tidy rows. Production has zero rows, one row, or 4,000. If an edge case isn't drawn, an engineer will design it at 6pm on a Thursday. Design these on purpose:

First-run empty: nothing exists yet. Explain what will appear and offer the first action.
No results: a search or filter returned nothing. Offer to clear it.
Loading: the skeleton, and what appears if loading takes ten seconds.
Error: what failed, whether data was lost, and how to retry.
Long content: the 60-character name, the German translation, the missing avatar.
Permissions: what a read-only user sees instead of the edit button.

If an edge case isn't drawn, an engineer will design it at 6pm on a Thursday.

How do you annotate accessibility, motion, and content?

Figma's annotations come with four preset categories: Development, Interaction, Accessibility, and Content. Categories need a Professional plan or higher, and engineers can filter annotations by category in Dev Mode.

Accessibility. Annotate focus order, heading levels, landmarks, accessible names for icon-only buttons, and what a screen reader announces when something changes. Check pointer targets against WCAG 2.2's Target Size (Minimum) criterion, which asks for at least 24 by 24 CSS pixels, with exceptions. For a ready notation, GitHub open-sourced its Annotation Toolkit, a Figma library for accessibility annotations, in September 2025.

Motion. For every animation, write the trigger, the property that changes, the duration, the easing, and the reduced-motion alternative. Browsers expose that preference through prefers-reduced-motion, widely available since January 2020 according to MDN. Figma Motion, launched at Config in June 2026, lets engineers inspect the timeline in Dev Mode and copy animation code as CSS, JSON, or React.

Content. Deliver final strings, or mark which are placeholders. Note character limits, truncation rules, and every validation message. Copy decided in code review is copy nobody approved.

Acceptance criteria close the loop

Acceptance criteria turn a design into something testable. Write one behavior per line and link the ticket from the frame:

Given an empty project list, the empty state shows a Create project action.
Given a keyboard user, Tab moves through the filters, then the table, then pagination.
Given a name over 40 characters, the name truncates with an ellipsis and the full name appears on hover and focus.
Given reduced motion is on, the panel appears without sliding.

If the build meets them, the handoff worked.

How does the handoff change with a shared component library?

When designers and engineers build from one component library, with the same names, variants, and tokens in Figma and in code, much of this checklist is answered before anyone opens the file. Library components already carry their states, keyboard behavior, and tokens.

What remains is the work only this screen has: composition, content, edge cases, responsive rules, and acceptance criteria. New components still need the full checklist. Two rules keep it tight: annotate only what differs from the library's defaults, and treat any detached instance as a question to resolve before the file is marked ready for dev.

Where Pegasus fits

Pegasus covers the library half of this checklist. Its Figma library and React code share the same component names, variant structure, and tokens, with 470 tokens defined as Figma variables for color, type, spacing, radius, and shadow in light and dark modes. Every component has light and dark variants, so a handoff doesn't need to spec the dark version of a library component.

Each component is documented with its anatomy, properties, and layout and spacing. Pegasus is built to WCAG 2.1 AA, with keyboard paths, focus states, and contrast documented per component, so tokens and much of the accessibility row are settled for anything taken from the library.

The React code ships with Storybook stories and tests, so a designer can check coded components against Figma before signing off.

That leaves handoff time for edge cases, content, motion, and acceptance criteria.

FAQ

What should be included in a design handoff?

A complete design handoff covers interactive states, responsive behavior, tokens instead of raw values, edge cases and empty states, accessibility annotations, motion specs with a reduced-motion fallback, final content, and acceptance criteria. It is complete when an engineer can build every state without asking a question and QA can test from the ticket.

How do you hand off a design to developers in Figma?

Bind values to variables, mark frames ready for dev, and use Figma's annotations with the preset Development, Interaction, Accessibility, and Content categories. Developers inspect variables, properties, and measurements in Dev Mode. Link the ticket with acceptance criteria from the frame so the spec and the test live together.

How do you document accessibility in a design handoff?

Annotate focus order, heading levels, landmarks, accessible names for icon-only controls, and what screen readers announce when content changes. Check target sizes and contrast. GitHub's open-source Annotation Toolkit for Figma provides a ready notation. Do this during design, because GitHub found that 48% of its accessibility issues could have been prevented in that phase.

Who writes acceptance criteria for a design handoff?

The designer drafts them, because they know the intended behavior, and the engineer and QA refine them into testable statements. Write one behavior per line in a given-then format, attach them to the ticket, and link the ticket from the Figma frame. Good criteria cover edge cases and accessibility, not only the happy path.

Sources

design handoff handoff checklist accessibility annotations acceptance criteria figma dev mode

One system. In Figma and in code.

Pegasus ships 1,540 components, 470 tokens, matching React code, Storybook, and a local MCP server. $149, one-time.

Get the full system