Design & UX · master area

Handoff Annotations

The notes the developer reads at PR time — spacing, transitions, the named-state behaviour the wireframe couldn't show. Less than a spec, more than a screenshot.

Owners: Designer Phase it lives in: How We Build (Volume IV) The corpus principle this enacts: The artefacts the chain produces survive the conversation.

Where it lives in the chain

• How We Build · Design Execution · handoff — the canon
• How We Build · The Review — the designer's confirmation reads the annotations alongside the code

How to do this

• Convention — annotations live on the → handoff page of the Figma file, near the frame they describe, not in a separate doc
• Convention — every interactive element has at least one annotation: what the state name is, what triggers the transition, what happens during, what happens after
• Practice — review uses annotations as the spec; if the code doesn't match the annotation, the code changes (or the annotation changes by PR, never silently)

What a good annotation looks like

"Hover: 150ms ease-out, scale 1.02. Focus: 2px outline using --focus-ring token. Click: state moves to submitting, button disables, label changes to Saving…. On success: snap to saved state, label Saved ✓, persists 2s, snaps back to idle. On error: stays in error/validation until field corrected. Network error: stays in submitting for 5s, then shows error/network with retry CTA."

That's an annotation a developer can build to and a QA can test against. "Make it feel snappy" is not.

Related crafts

• Figma Organization — where the annotations live
• Interaction Design — the source of the annotation language
• Code Review — where the annotation is read at PR time