Design-to-Dev Handoff (Dev Mode, Code Connect)

The full lesson

The gap between a finished design file and a shipped product is where most interface quality is lost. Spacing drifts. Colors get hardcoded. Interactive states go unimplemented because nobody wrote them down. For most of the industry’s history, teams bridged this gap with redline PDFs, Zeplin exports, and hope. In 2026, the combination of Figma Dev Mode, Code Connect, and token-driven handoff has turned that gap from a constant source of rework into a solvable problem — but only for teams who understand how the pieces fit together.

Why Handoff Breaks Down

The root cause of poor handoff is not bad tools — it is an information gap. Designers make decisions that carry invisible context: “this uses the surface/elevated token because it needs to sit above the page background”; “this spacing is space/400, not arbitrary 16px”; “this button is disabled but still focusable because form validation hasn’t run yet.” None of that reasoning survives a static screenshot or a flat color hex.

The classic handoff stack — Zeplin, InVision Inspect, even the older Figma Inspect panel — could answer “what does this look like?” It could not answer “what component is this?”, “what token drives this value?”, or “what happens in the error state?” Developers filled those gaps with their best judgment, and judgment varies.

Figma Dev Mode: What Changed

Dev Mode shipped as generally available in late 2023 and has been extended significantly through 2024–2025. It is a separate view of a Figma file, optimized for developers. It is not just a “read-only mode” — it is a different lens on the same file, tuned to answer development questions.

Key capabilities in Dev Mode as of 2026:

• Measurement and spacing inspection — click any element to see CSS-ready spacing values, auto-layout rules, and frame dimensions. Values appear in whatever unit system the project uses (px or rem).
• Component identification — Dev Mode shows which library component a frame or element corresponds to, with a direct link to the component source. No more guessing whether something is a custom one-off or the shared Button component.
• Token display (with Code Connect) — when Code Connect is configured, token names replace raw values. Instead of #F5F5F5 you see color/surface/secondary. Instead of 16 you see space/400.
• Annotations — designers can attach structured notes to designs: interaction details, accessibility requirements, edge cases. These live in the file alongside the design, not in a separate Notion doc that goes stale.
• Ready-for-dev status — sections of a file can be marked “Ready for dev.” This signals to developers which screens are stable and which are still changing.

One important limit: Dev Mode does not generate production-ready code, and it knows nothing about your actual codebase. That is what Code Connect handles.

Code Connect: Linking Design to Production Components

Code Connect is Figma’s bridge between a design-file component and the real code component in your repository. Once it is set up, a developer inspecting a component in Dev Mode sees a usage example drawn from your actual codebase — real imports, real prop names, and all.

Setting up Code Connect requires a one-time mapping step. You create a configuration file (typically figma.config.json and a *.figma.tsx or *.figma.ts file per component family) that tells Figma which design component maps to which code component, and how design properties map to code props.

Here is a simplified Code Connect file for a Button component in TypeScript:

import figma from "@figma/code-connect";
import { Button } from "./Button";

figma.connect(Button, "https://figma.com/file/...?node-id=...", {
  props: {
    label: figma.string("Label"),
    variant: figma.enum("Variant", {
      primary: "primary",
      secondary: "secondary",
      destructive: "destructive",
    }),
    disabled: figma.boolean("Disabled"),
  },
  example: ({ label, variant, disabled }) => (
    `<Button variant={variant} disabled={disabled}>{label}</Button>`
  ),
});

Once you publish this to Figma, every developer inspecting that component in Dev Mode sees the real import and usage — with the actual prop names and values from the live codebase. This is a big improvement over tool-generated snippets that use made-up component APIs.

Token-Driven Handoff: The Foundation Layer

Dev Mode and Code Connect become far more powerful when your design system uses design tokens. Without tokens, Dev Mode shows hardcoded values. With tokens and Code Connect configured, it shows semantic references that map directly to variables in the codebase.

Modern token architecture uses three tiers, aligned with the W3C Design Token Community Group (DTCG) stable format (DTCG is the industry standard for defining and sharing design tokens across tools):

Tier	Example name	Example value	Purpose
Primitive	blue-500	oklch(55% 0.18 250)	Raw color, no semantic meaning
Semantic	color/action/primary	references blue-500	Communicates intent
Component	button/background/default	references color/action/primary	Scoped to a specific component

This three-tier structure means that when a designer changes the brand’s primary action color, every component referencing color/action/primary updates — in the design file and, when tokens are synced, in the codebase. The DTCG format uses $value and $type keys, making it tool-neutral and compatible with Style Dictionary, Theo, or any modern token pipeline.

The handoff implication is direct: a developer inspecting a button in Dev Mode should see button/background/default, not #0F62FE. That single change eliminates a whole class of hardcoded values that otherwise pile up into maintenance debt over time.

Living Handoff with Storybook

For teams with a mature design system, the most reliable handoff surface is not the Figma file — it is Storybook. A Storybook that reflects the live component library, with all states documented, is the highest-fidelity specification a developer can work from. It is not a picture of a component; it is the component itself.

The living handoff model works like this:

1. Designers work in Figma, using components that correspond one-to-one with Storybook stories.
2. Token files are the source of truth, synced from Figma Variables (or a token management tool like Tokens Studio) to the codebase via a CI pipeline.
3. Developers implement against the Storybook story, not against a Figma screenshot.
4. Code Connect surfaces the Storybook-aligned usage example in Dev Mode, closing the loop.

The contrast with the old model is stark. Spec PDFs drifted from the codebase the moment they were exported. A living Storybook drifts only when a developer intentionally changes the implementation — and that change is version-controlled, reviewable, and visible.

Annotations and State Documentation

The most common handoff gap is undocumented states. A component exists in far more states than the default, filled-in version:

• Loading — skeleton, spinner, or progressive reveal
• Empty — no data yet; an onboarding opportunity or blank slate
• Error — inline validation (triggered on blur, not on submit), field-level error message linked with aria-describedby
• Disabled — is it still focusable? Why is it disabled? Will it become enabled?
• Partial/intermediate — checkbox indeterminate, upload in progress, partially saved draft

In Figma, component variants handle most of these states. A Button component with variants for State: default / hover / active / focus / disabled / loading is both a design-system artifact and a handoff specification. When Code Connect is set up correctly, each variant maps to a prop combination in the real component, and the developer sees the accurate usage example for each state.

Dev Mode annotations are the complementary layer. They are free-text notes attached to specific frames that document behavior a variant cannot encode. For example: “On hover, this tooltip appears after a 200ms delay. Dismiss on Escape or pointer-leave. WCAG 2.2: tooltip must not obscure the trigger target.”

The Handoff Review Checklist

Before marking a section ready for development, check these categories:

Structure and tokens

• All colors reference semantic tokens, not hardcoded values
• All spacing values correspond to the spacing scale (no arbitrary pixel values)
• Typography uses text styles with token bindings, not manually set font properties
• Elevation and shadow use the token system, not ad-hoc values

States and edge cases

• Every interactive component has all states documented (default, hover, focus, active, disabled, loading, error)
• Empty states are designed for every list, table, or data container
• Error states use specific messages (not “Something went wrong”) linked via aria-describedby
• Long-text overflow behavior is specified

Accessibility

• Focus order is annotated for all interactive flows
• ARIA roles and labels are specified for non-standard interactive elements
• Color is not the sole carrier of information
• Target sizes meet the WCAG 2.2 minimum (24x24px) and ideally 44x44px for touch

Responsive behavior

• Breakpoint behavior is documented or linked to a responsive prototype
• Container-query behavior is noted where applicable

Motion

• Transitions reference motion tokens (duration, easing/spring curve)
• prefers-reduced-motion fallback is specified

Outdated Habits to Retire

The handoff space has accumulated a lot of legacy practices. These are worth explicitly retiring:

Redline PDFs and Zeplin exports. These served a purpose in the pre-token era, but they are static artifacts that drift from the live design file the moment they are exported. They cannot express token relationships, component variants, or interactive behavior. Teams still using redline exports in 2026 are doing manual work that token pipelines and Dev Mode have made obsolete.

“Final” design files separate from the dev reference. When designers maintain a “presentation” Figma file and a separate “dev handoff” file, divergence is guaranteed. There should be one file, with sections marked by status. Dev Mode is the lens; the file is the source of truth.

Hardcoded one-off values. Implementing a spacing value as 14px because it “looks right” — instead of checking whether space/350 exists in the token scale — creates a micro-inconsistency that multiplies across every component. Enforce the token scale at code review as rigorously as you enforce it in design critique.

Separate tone-of-voice and content standards documents. Error message copy, empty-state copy, and microcopy guidelines are part of the handoff. If they live in a document developers never read, production error messages will be whatever the developer typed first. Co-locating content standards with component documentation in Storybook gives them a real chance of being referenced.