Designing for Handoff

The gap between Figma and code is where projects lose momentum. This page covers what designers can do inside Figma to close it — for both human engineers and AI agents. They need the same things: named layers, token values, autolayout, and every important state shown.

Why handoffs break

Each of these is preventable by working inside Figma with the code translation in mind from the start.

Figma file structure

Figma file structure

Name pages after routes. This gives agents an immediate map from design to codebase.

Figma page name          → App Router path
─────────────────────────────────────────────
Dashboard                → app/dashboard/
  Dashboard/Home          → app/dashboard/page.tsx
  Dashboard/Projects      → app/dashboard/projects/page.tsx
Auth                     → app/auth/
  Auth/Login              → app/auth/login/page.tsx
  Auth/SignUp             → app/auth/signup/page.tsx
Settings                 → app/settings/page.tsx

Within a page, group frames into named sections that correspond to layout slots:

Dashboard page
├── Sidebar              → layout sidebar slot
├── Header               → layout header slot
├── Main/ProjectTable    → page content
└── Main/QuickActions    → page content

Layer naming conventions

Every layer name should answer: what component is this in the codebase?

Component names

Use PascalCase matching your component naming convention:

Grouping with slashes

Forward slashes create collapsible groups in Figma's layer panel and encode the hierarchy:

Page/Dashboard
├── Sidebar/Nav/Logo
├── Sidebar/Nav/Link.Home
├── Sidebar/Nav/Link.Projects
├── Header/SearchInput
├── Header/UserMenu
├── Main/Toolbar
├── Main/Table.Header
└── Main/Table.Row

Autolayout rules

Auto Layout in Figma translates almost 1:1 to CSS flexbox. Every frame should use Auto Layout unless there is a specific reason not to.

What to avoid

• Absolute positioning — has no clean CSS flexbox equivalent. Use Auto Layout frames instead.
• Overlapping elements with manual x/y coordinates — translate to relative positioning or z-index with intent.
• Mixed-direction layouts without wrapping — if content needs to break into rows, use Wrap.
• Nested Auto Layout frames used as centering hacks — these produce unnecessary nesting in generated code. Use alignment properties instead.

Token-aware design

Design tokens are the single source of truth for colours, spacing, typography, and radii. When designers use tokens instead of raw values, the generated code references the same variable as the codebase. When they use raw values, agents inline hex codes and magic numbers.

Figma variables → CSS custom properties

Create Figma variables that match your CSS custom properties exactly:

Figma variable          CSS custom property
─────────────────────────────────────────────
color/primary/500       --color-primary
color/neutral/100       --color-neutral-100
spacing/4               --spacing-4  (1rem)
spacing/8               --spacing-8  (2rem)
radius/md               --radius-md
font/sans               --font-sans

Rules for token usage

• Bind every colour fill to a Figma variable, never a raw hex
• Bind every spacing value (gap, padding, margin) to a spacing variable
• Use text variables for font family, size, weight, and line height
• If a value does not exist as a token, add the token — do not use a raw value

Component variants → code props

Figma component variants should map directly to React component props. The cleaner the mapping, the less the agent has to guess.

States as variants

Model every interaction state as a component variant, not as a separate component:

Sizes as a separate axis

Keep size variants on their own property axis so they compose with states:

Property 1: Size  →  sm | md | lg
Property 2: State →  default | hover | focus | active | disabled | loading

This maps to:

<Button size="sm" state="default">Save</Button>
<Button size="lg" disabled>Save</Button>

Agents that see this variant structure generate a single component with props. Agents that see six disconnected button frames generate six separate components.

What agents and developers need

Before handing off a design file, verify that every screen includes:

States

Every screen must show more than the happy path. Include at minimum:

• Loading — skeleton or spinner for every data-dependent region
• Empty — what the user sees before data exists
• Error — API failure, validation error, or permission denied
• Success — confirmation after completing an action
• Edge cases — long names, zero results, expired sessions

Real copy

Use the actual text that will appear in the product. Lorem ipsum hides layout problems: names that are 3 lines long, button labels that overflow, headings that wrap at awkward breakpoints.

Breakpoint annotations

Note where the layout changes in frame names or descriptions:

Frame name: "Dashboard/Home [desktop: 1440]"
Frame name: "Dashboard/Home [tablet: 768]"
Frame name: "Dashboard/Home [mobile: 375]"

Dev Mode annotations

Use Figma Dev Mode to annotate:

• Spacing values between elements
• Component names matching the codebase
• Token references for colours and typography
• Notes about responsive behaviour or interaction details

Design-to-code tools

Several tools now translate Figma designs directly into code. They are not replacements for design engineering — they are accelerators that handle the mechanical translation so you can focus on the decisions that matter.

Tool comparison

When to use which approach

Handoff checklist

Before handing off a Figma file to a developer or agent, confirm:

• Every layer is named meaningfully — no Rectangle 47, Frame 12, or Component 1
• Pages are named after routes or route groups
• All colours come from Figma variables matching CSS tokens
• All spacing (gap, padding) comes from spacing variables
• Every frame uses Auto Layout
• Interaction states (hover, focus, disabled, loading) exist as component variants
• Loading, empty, error, and edge-case states are shown for every screen
• Real copy is used in place of lorem ipsum
• Breakpoint-specific frames are annotated
• Interactive prototype is linked for complex flows

Related pages

• Product Designer First — Product thinking before interface work
• Design System — Token architecture and system structure
• AI-Ready Design Systems — Token schema for agent consumption
• Prototyping & Validation — Fidelity levels and testing
• Agent Collaboration — Prompt patterns for working with agents