This guide shows you how to build a complete interaction handoff spec inside Figma for a complex UI component, from state mapping to motion values. You can complete a working spec for one component in under two hours, and use the same system across your entire design library.

What You'll Build

  • A structured annotation layer system that developers can read without a design walk-through
  • A state documentation page that captures every variant, including loading, error, empty, and disabled states
  • A motion spec panel that defines easing curves, durations, and trigger conditions using Figma Variables
  • A reusable handoff template your team can apply to any component going forward

Prerequisites

  • Figma Professional or Organisation plan (required for Variables and Dev Mode, as of 2026)
  • The component you want to spec already built with Auto Layout and Variants
  • Basic familiarity with Figma's Dev Mode panel
  • Optional: the Figma plugin Redlines or Specs (both free on the Figma Community)

Step 1: Audit the Component Before You Annotate

Why does this step come first?

Annotating an incomplete component creates false documentation. Developers build from specs, so any missing state you skip now becomes a bug in production.

Open the component's main page and run through this checklist before you write a single annotation:

  • Default state exists and is named correctly in the Variants panel
  • Hover, focus, active, disabled, loading, error, and success states are each a separate variant
  • Every text layer uses a defined text style from the library
  • Every colour uses a style or a Variable, not a hardcoded hex value
  • Spacing uses Auto Layout gap values tied to a spacing token

If anything on that list is missing, fix it before continuing. A spec that describes broken components is worse than no spec at all.

Step 2: Create a Dedicated Spec Page

Should the spec live on the same page as the design?

No. Mixing spec content with working design frames creates clutter that developers have to navigate around. A dedicated page keeps the handoff clean and scannable.

Add a new page to your Figma file and name it [ComponentName] / Handoff Spec. For example: Dropdown / Handoff Spec.

Set up three frames on this page:

  1. States Overview — a wide frame at 1440px wide where all states sit side by side
  2. Interaction Map — a narrower frame showing trigger-to-state flows as a simple diagram
  3. Motion Spec — a compact frame listing all animation properties in a table layout

Name each frame with a number prefix so they stack in the correct order in the layers panel: 01 – States Overview, 02 – Interaction Map, 03 – Motion Spec.

Step 3: Document Every State in the States Overview Frame

What counts as a state worth documenting?

Any condition that changes the component's appearance or behaviour is a state. That includes conditional visibility, skeleton loaders, and truncated text overflow.

Copy each variant from the main component into the States Overview frame. Do not detach them. Keeping them as instances means the spec updates automatically when the component changes.

Below each instance, add a label using a text style from your library (never freehand type). The label format should follow this pattern:

State: [Variant Name]
Trigger: [What causes this state]
Duration in state: [Transient / Persistent]
Next state on: [What user action or data event transitions out]

For a form input component, one block might read:

State: Error
Trigger: Form submission with invalid value
Duration in state: Persistent
Next state on: User corrects input and field passes validation

This format gives developers the full mental model, not just a picture.

Step 4: Build the Interaction Map

What is the fastest way to draw an interaction map in Figma?

Use Figma's built-in connector lines combined with small state thumbnails. This avoids third-party diagramming plugins and keeps everything in one file.

In the Interaction Map frame, paste small copies of each state instance at roughly 200px wide. Then draw connector arrows between them using Figma's Line tool with an arrowhead endpoint.

Label each arrow with the trigger. Keep the label short: onClick, onBlur (invalid), API error, API success. Developers read these quickly when they are short and consistent.

Group the diagram clearly: entry states on the left, transient states in the middle, terminal or persistent states on the right. This mirrors how developers think about state machines.

If your component has more than eight states, consider splitting the interaction map into two rows: one for happy-path flows, one for error and edge-case flows.

Step 5: Write the Motion Spec

Why do developers need motion values written out explicitly?

CSS and Framer Motion do not read your Figma prototyping settings. If you only specify animation in a prototype flow, the values stay locked inside Figma and never reach the codebase.

In the Motion Spec frame, build a simple table with these columns:

| Transition | Property | Duration | Easing | Delay | Notes |
|---|---|---|---|---|---|
| Default → Hover | background-color | 150ms | ease-out | 0ms | — |
| Default → Error | border-color, icon-opacity | 200ms | ease-in-out | 0ms | Simultaneous |
| Error → Default | border-color, icon-opacity | 150ms | ease-out | 0ms | — |
| Any → Loading | opacity (content) | 100ms | ease-in | 0ms | Fade out before spinner appears |

Use exact millisecond values. Ranges like "fast" or "medium" are subjective and inconsistent across developers. The values above are common starting points for UI components based on material motion research, but adjust to match your own design system.

If your component uses a spring animation (common in React Native or Framer Motion projects), add two extra columns: Stiffness and Damping.

Step 6: Add Annotation Layers Using a Sticky System

What annotation method works best for Dev Mode in Figma?

As of 2026, Figma Dev Mode supports native annotations through the Annotations panel (formerly available only via third-party plugins). Use this instead of freehand sticky notes.

Select a layer in the States Overview frame, open the Annotations panel on the right sidebar, and click the plus button to add a note. These annotations appear automatically when a developer opens the file in Dev Mode.

Annotate the following for each state instance:

  • Any hardcoded pixel value that is not covered by a spacing token
  • Z-index or stacking context changes (for tooltips, dropdowns, modals)
  • Conditional logic that is not visible in the static frame (for example: "Show error icon only when error message exceeds one line")
  • Accessibility attributes: aria-label, aria-live, role values

Keep each annotation under 20 words. If it needs more explanation, the component design probably needs simplification first.

When should you use Variables instead of typed values in the spec?

Always, when the token exists. A spec that shows a hex value instead of a token name creates a maintenance problem every time the design system updates.

In the Motion Spec table, replace raw values with Variable names wherever you have defined them. For example, instead of 150ms, write {motion.duration.fast} if that Variable exists in your library.

If you have not yet set up motion tokens as Variables, this step is a good prompt to do so. Add a Variables group called motion with subgroups duration and easing. Typical duration tokens for a mid-size design system look like this:

motion/duration/instant   = 0ms
motion/duration/fast      = 100ms
motion/duration/base      = 200ms
motion/duration/slow      = 300ms
motion/duration/xslow     = 500ms

This mirrors how teams at companies like Atlassian and Shopify structure motion in their design systems, and it translates directly into CSS custom properties.

Step 8: Publish and Share the Spec

What is the correct way to share the spec with a developer?

Share a direct link to the Spec page, not the top-level file. In Figma, right-click the page tab, select Copy Link, and send that. This drops the developer directly onto the handoff content.

If your developer uses Dev Mode, publish the file as a library first. Dev Mode shows applied styles and variables inline, which reduces the back-and-forth questions by a significant margin. Based on internal process reviews at agencies like Lenka Studio, switching to annotated Dev Mode specs reduced developer clarification requests by roughly 60% on component-heavy projects.

Add a brief written summary at the top of the Spec page as a sticky note or cover frame. Include:

  • Component name and version
  • Designer responsible
  • Date last updated
  • Link to the relevant Jira or Linear ticket
  • Any known open questions or decisions still pending

Step 9: Set Up a Review Gate Before Development Starts

Why add a review gate after the spec is written?

Specs written in isolation miss things that a quick cross-functional review catches. A 30-minute review with a developer before they build saves hours of rework.

Walk through the Interaction Map together. Ask the developer to narrate the state machine back to you. Any point where their narration diverges from your intent reveals a gap in the spec, not a gap in the developer's understanding.

Document any changes from the review directly in the spec before closing the call. Do not rely on Slack messages or verbal agreements. The spec is the source of truth.

Frequently Asked Questions

Does this workflow work for mobile app components, not just web?

Yes. The same page structure, state documentation format, and motion spec table apply to iOS and Android components. For mobile, add a Gesture column to your Interaction Map labels to distinguish swipe, tap, long-press, and pinch triggers.

What if the component has too many states to fit in one frame?

Split the States Overview frame into sections: core states in the first section, edge cases and error states in a second section below. Use a horizontal divider with a label like // Edge Cases to separate them visually.

How is this different from just using a Figma prototype?

A Figma prototype shows the interaction visually, but does not communicate timing values, CSS properties, accessibility attributes, or conditional logic. A prototype is useful for stakeholder sign-off. A handoff spec is what a developer actually builds from.

Do I need to update the spec every time the component changes?

Yes, and the easiest way to enforce this is to add spec updates to your definition of done in your sprint process. If a component change ships without a spec update, the spec becomes misleading faster than it becomes outdated.

Can I use this same approach for design systems with hundreds of components?

Yes, but prioritise. Start with components that have the highest interaction complexity: forms, modals, navigation, data tables. Simple components like badges or avatars rarely need a full interaction spec.

Next Steps

Apply this workflow to one component this week. Pick something that has caused developer questions in the past and use it as your test case. Once the spec is live in Dev Mode, track how many clarification questions come through on that component compared to previous work.

If you want to go further, connect your motion Variables to a design tokens pipeline so the values flow directly into your codebase without manual copying. This closes the last gap between spec and production.

If your team is working through a larger design system build and needs a structured process from component architecture through to developer handoff, the team at Lenka Studio can help you build that foundation. Get in touch to talk through what you are working on.