20 minintermediate

Prepare Your Figma for AI Handoff

Clean up your Figma file so Claude Code can read it accurately. Proper layer naming, annotations, and token exports reduce ambiguity in handoff.

The situation

You are handing a Figma file to a developer using Claude Code. Your layers are named "Frame 14" and "Group 7." The last handoff produced code that looked nothing like the design, and the back-and-forth took three days.

You'll clean up your file so Claude Code reads it accurately and generates code you can recognise without a second round of corrections.

Follow along using:

What you walk away with

Layer names that describe component intent, not shape, so Claude infers nothing by accident

Annotations for the behaviour pixels cannot show: validation rules, transitions, and error states

A token export and component spec ready to paste directly into a Claude Code session

Rename layers to describe intent, not shape

Claude reads your layer names and annotations as context when you paste them into a session. Generic names like "Frame 3" produce generic code. Rename every interactive element using the pattern: component/state/variant. For example: button/primary/default, input/error/filled, card/product/selected.

text

# Poorly named layers (what Claude has to guess from):
Frame 14
Group 7
Rectangle 3
Vector 2

# Well-named layers (what Claude can use directly):
button/primary/default
form/amount-entry
input/bkash-number
icon/chevron-right

Claudeclaude.ai

Message Claude…

Add annotations for behaviour Claude cannot infer from pixels

Visual design shows states but not transitions, error conditions, or edge cases. Use Figma annotations (or a sticky note layer named "AI-NOTES") to document: what triggers state changes, what validation rules apply, what happens on error, and which fields are optional.

text

# Example AI-NOTES layer content (paste into Figma as a sticky note):

button/primary/default
- Disabled until: amount > 0 AND phone field passes validation
- On tap: disable button, show spinner, call /api/send-money
- Loading state: spinner replaces label for duration of API call

input/amount/default
- Min: 10 BDT, Max: 5000 BDT
- Error state: show "Minimum is 10 BDT" inline below field
- On blur: validate and show error immediately (do not wait for submit)

input/bkash-number/default
- Format: 11 digits, must start with 01
- Error: "Enter a valid 11-digit bKash number"

Claudeclaude.ai

Message Claude…

Export tokens and write a component spec

Before handing off, export your design tokens (colors, spacing, type) and write a one-page component spec. Paste both into Claude and ask it to generate the code. This is faster than describing the design verbally and more accurate than hoping Claude infers correctly from a screenshot.

json

# Export tokens from Figma using the Tokens Studio plugin
# or manually copy them into a JSON file

{
  "colors": {
    "primary": "#E2136E",
    "error": "#D32F2F",
    "surface": "#F5F5F5"
  },
  "spacing": {
    "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px"
  },
  "typography": {
    "body": { "size": "14px", "weight": "400", "lineHeight": "20px" },
    "label": { "size": "12px", "weight": "500", "lineHeight": "16px" }
  }
}

Claudeclaude.ai

Message Claude…

Common mistakes

Four failure modes in Figma-to-Claude handoffs.

Renaming only the top-level frames. Layer naming matters most at the component and element level, not the page or frame level. "Payment Screen" as a frame name helps nothing. "button/primary/disabled" inside that frame is what changes the code.
Skipping the AI-NOTES layer for simple components. Simple components still have non-obvious behaviour: hover states, disabled conditions, error triggers. If you do not annotate them, Claude infers from common patterns, which may not match your product.
Exporting tokens without mapping them to the codebase. A token export that uses Figma variable names your codebase does not recognise adds a translation step for the developer. Check that the token names in the export match what the dev team uses before handing off.
Handing off a file mid-design. Annotations and layer names added to a file that is still changing create confusion. Do the handoff prep pass once, when the design is stable.

What's next?

Build your first flow with Claude Code

New guides, when they ship

One email, roughly weekly. CLAUDE.md templates, workflows I actually use, and the cut-for-length stuff that does not make the public guides. One-click unsubscribe.

Or follow on Substack