How I run Figma with an agent in the file.

00 · Six rules

Six rules behind everything on this page

When something isn't covered on this page, these rules decide it. Each section below gives a pattern and an example, plus a reason or a warning where it helps. The exact conventions matter less than using the same ones on every project, so the agent gets that consistency too.

1. Clear beats clever. A name should tell a teammate, future you, or an agent what the thing is and what state it is in, without opening it.
2. One source of truth per system. One file, branch, or collection is the official version. Everything else is a working copy, an exploration, or an archive, and its name says so.
3. Status is always visible. Status goes in the name as a glyph and a word, never as color alone. That way it works for colorblind readers, in search, in screenshots, and for an agent reading the layer tree.
4. Add, don't overwrite. New work extends what is already there. Use branches and new sections instead of piling up duplicate files.
5. Names map to code. Name tokens, components, and styles so they translate straight to CSS variables, Tailwind, and React props. color/bg/surface becomes --color-bg-surface.
6. Your system is the agent's brief. The agent builds from whatever you have named and built. A clean system gets you output that looks like your product. A messy one gets you something that looks like a template. Naming and structure matter more now that an agent reads the file too.

Casing for each type of object

01 · Working with the agent

How the job changes when an agent works in the file

You no longer start from a blank canvas. The agent does more of the drawing, and your job shifts to directing it and owning the system it builds on. The parts only you can provide are the system, the direction, the judgment, and the final sign-off.

The two kinds of agent, and what each can see

They see different things, so know which one you are working with.

• The native Figma agent works from inside the file. It reads your components, variables, styles, and file structure directly. Use it for canvas work that depends on your system: bulk edits, swapping components, converting to dark mode, filling flows with real content, and generating screens that should match your product.
• External coding agents like Claude Code and Codex work from outside, through the Figma MCP server (a connection that lets outside tools read Figma files). They read the design and pull variables, measurements, and component code into your codebase. Use them to go from design to code and back.

What the agent is good and bad at

• Strong: multi screen mobile flows built on a real, component based system, bulk and repetitive edits across a file, filling layouts with realistic content, and first drafts you plan to react to.
• Weak: single desktop screens, new layouts with no system behind them, and files with only loose tokens (variables not attached to any component). With loose variables, it often names them but still leaves raw hex values behind. The next section explains the fix.

The four jobs that stay with you

As generating screens gets cheaper, average work costs almost nothing to make. What sets your work apart is the part the agent can't own.

• The system. The tokens, components, and library the agent builds on. This keeps paying off over time.
• The direction. The prompt, the references, and the call on what is actually good.
• The judgment. Accessibility, edge cases, accuracy, and ethics. You are responsible for the outcome, not the agent.
• The handoff. Naming and structure that keep the work clear to whoever reads it next: a teammate, a coding agent, or production code over MCP.

02 · What the agent needs

Giving the agent the context it needs to match your system

The agent can only work with what you give it. Setting up that context matters more than how you word any prompt.

What the agent reads, from most to least influence

1. Your published library. The components and variables it can actually use. This matters most. Without a library, there is no system for it to match.
2. Skills. Reusable instruction files that describe your conventions, which you call by name. Turn this page into a skill and the agent follows your naming and token rules directly.
3. Attachments. Reference images, briefs, data files, and screens you add to a specific prompt.
4. Connectors. Live links to the tools where your work lives, so a brief in Notion or a ticket in your tracker reaches the agent without copy and paste.
5. The prompt. Direction and constraints. It does little without the four inputs above, and a lot with them.

The token binding rule

This rule decides whether you get clean output or a pile of raw hex values. The agent reliably uses your tokens when they are attached to real components and you name the library in your prompt. It does poorly with loose variables sitting in a file. So always work in this order:

1. Build the components first, with tokens attached.
2. Publish the library.
3. In the prompt, name the library and the components you want.
4. Then generate.

Turn this page into a skill

Skills are markdown files you run with a slash command. The agent uses them along with attachments and connectors. Put the rules from this page into a skill (the casing table, the status glyphs, the naming spec, the token tiers), and every generation starts on your system. A coding agent can use the same kind of file over MCP, so one set of rules covers both design and code.

03 · How Figma nests

How Figma is structured, and how I name each level

Organization / Workspace
└─ Team                  → a product line or domain
   └─ Project            → one product / initiative
      └─ File            → one surface, system, or workstream
         └─ Page         → a phase or workstream within the file
            └─ Section   → a named region of canvas (a real object)
               └─ Frame  → a screen / artboard
                  └─ Group / Layer

Some things sit outside this tree and apply across it: components, variables (grouped in collections with modes), styles, published libraries, branches, and prototype flows.

04 · Status glyphs

One set of status glyphs for files, pages, and sections

Always use a glyph and a word together. This one set covers most of the status you need to show.

Rule: one status glyph, at the front of the name. When the status changes, swap the glyph and leave the rest of the name alone, so links and habits still work.

⭐ Design System
✅ Sign-In Flow
🟡 Evidence Export
🧪 Statement — Layout Spikes
📦 Evidence View v1

05 · Workflow

The project workflow, stage by stage, with the agent

At each stage the agent does a first pass. You direct it, pick what to keep, and own the result. It works the same solo or on a team. Solo, you just review your own work at the review steps.

Setup checklist for every new project

1. Create the Project, named for the product.
2. Create the core files: ⭐ Design System, the library you publish and point the agent at. 🟡 Flows for maps and information architecture. One file per surface or feature, as needed. And a 🧪 Sandbox for throwaway work and agent experiments, which you never publish from.
3. Set the file thumbnail so you can tell files apart on the project board.
4. In the design system file, create your variable collections and page scaffold.
5. Publish the library, turn it on in the surface files, and add your conventions as an agent skill.

06 · Naming

How to name things at every level

6.1Teams

Pattern: Domain, meaning the product line or area of life. Teams are the broadest grouping. Keep them few and stable, and don't make one per feature.

6.2Projects

Pattern: Product, one project per product. Don't put dates or versions in a project name. Files and version history handle that.

6.3Files

A file holds one surface, one system, or one workstream. Not a single screen, and not the whole product. Pattern: [status] Surface.

⭐ Design System
🟡 Evidence View
🔵 Onboarding — Redesign
🧪 Sandbox
📦 Evidence View v1

The design system file is always named ⭐ Design System, and it is the only file you publish components and variables from. When a file is replaced, add its old version label to the name and mark it 📦 instead of deleting it.

6.4File thumbnail

The thumbnail is what shows on the project board. Don't leave it to chance: you can set any frame as the thumbnail. Pattern: a cover frame at 16:10 with the product mark, file title, status glyph and label, owner, and last updated date. A board of covers is easy to scan. A board of random first screens is not.

6.5Pages

Pages split a file into phases or workstreams. Use a small set you repeat in every file, with divider pages to group them.

📋  Cover & Readme
────────
🟡  Flows
🎨  Designs
🧩  Components
🎟  Prototype
────────
🧪  Explorations
📦  Archive

Divider pages hold no work. Name them with a row of dashes or like —— REFERENCE ——, so they act as separators in the page list.

6.6Sections

Sections are real canvas objects, not frames. Use them to group parts of a page and show their status. They can carry a status, collapse, and be marked Ready for Dev, and they keep a busy page easy to scan.

✅ Statement — v2 (Approved)
🟡 Statement — Export Panel
🧪 Statement — Layout Spikes
🔴 Statement — Legacy (do not use)

6.7Frames and screens

Pattern: ## · Surface — State. The ## is a two digit number so screens sort in flow order. The state is the variant: Default, Empty, Loading, Error, or Success.

01 · Statement — Default
02 · Statement — Generating
03 · Statement — Published
04 · Statement — Error

Every interactive screen gets a frame for each state, side by side. Empty, loading, error, and success states matter as much as the default. Never hand off a frame called Frame 427. Rename or delete auto-named frames first.

6.8Groups and layers

Pattern: name what a layer does, not its shape. Rename anything you will reference, link a prototype to, or hand off. Use auto layout frames instead of groups for structure, because they adapt when content changes. Name containers by what they do: row, stack, card, field.

6.9Components

Components are the backbone of the file. Name them with slashes: Figma turns each slash into a folder in the Assets panel, which matches how you would organize code.

Button/Primary
Button/Secondary
Form/Input
Form/Input/Search
Navigation/Tab
Data/Table/Row
Feedback/Toast

The first part is the category, kept short and fixed. Don't put states in the name. That is what variants are for: Button/Primary with a State property, not Button/Primary/Hover. Give each component one job. Use slots when people need some flexibility, so they don't detach instances.

6.10Component sets and variant properties

Name properties and their values like an API, because that is what they become in code.

Set: Button
  Properties:
    Type     = Primary | Secondary | Ghost
    Size     = Sm | Md | Lg
    State    = Default | Hover | Focus | Disabled
    Has Icon = true | false

These names show up exactly as written in Dev Mode and in generated code props. Messy variant names become messy props, and the agent will copy them.

6.11Variables and tokens

Pattern: group/subgroup/name, lowercase with hyphens, grouped by slashes. Group by role, not by raw value. Number scales go up in hundreds so you can add steps in between later without renumbering. Section 07 covers the full setup.

color/bg/surface
color/text/muted
color/border/default
color/accent/primary
space/100   space/200   space/400
radius/sm   radius/md

6.12Styles

If a value changes for light, dark, or different brands, make it a variable. If a set of properties is reused together, make it a style built on variables.

6.13Prototype flows

Name every flow starting point for what it shows. One flow is one story a stakeholder can click through without help. Motion specs live in the timeline and can be inspected in Dev Mode, so don't describe easing in text.

6.14Annotations

Use Dev Mode annotations, not loose text boxes, so notes are structured and easy to inspect. Start each one with a category tag.

[Spacing]  16 between rows (space/400)
[Behavior] Disabled until form valid
[A11y]     aria-live=polite on toast region
[Token]    color/text/muted

6.15Exports and assets

Pattern: name-descriptor@scale.ext, lowercase with hyphens. Set export settings on the component or frame, named with the final filename, so re-exporting takes one click and stays consistent.

og-card-home@2x.png
icon-shield-16.svg
hero-statement@2x.webp

07 · Tokens and variables

Three tiers of tokens, so theming, multiple brands, and handoff all work

PRIMITIVE  →  SEMANTIC  →  COMPONENT
(raw values)   (roles)       (optional, component-specific)

Tier 1, Primitives

The raw colors and scales, kept in a Primitives collection. Never apply them to designs directly. For example: color/blue/500, space/8, radius/4.

Tier 2, Semantic

Named roles that point to primitives, kept in a Semantic or Theme collection. These are what you apply to layers, and what the agent should use.

color/bg/surface     → color/white   (Light)  / color/gray/950 (Dark)
color/text/default   → color/gray/900 (Light)  / color/gray/50  (Dark)
color/accent/primary → color/blue/500
space/gutter         → space/16

Tier 3, Component, optional

Only when a component needs its own settings, like button/padding-x pointing to space/gutter.

Collections and modes

• A collection is a set of variables and its modes. Keep semantic theme tokens in one collection so switching one mode restyles everything.
• Modes are contexts. Usually Theme (Light or Dark) and Breakpoint (Mobile or Desktop, using number variables for spacing). How many modes you get per collection depends on your plan, and higher plans get more, so plan around the one you are on.
• Extended collections let each brand extend a parent semantic collection. It inherits every variable and mode and overrides only what is different. This is the proper way to keep one source of truth across brands. It is Enterprise only, so on other plans use modes for multiple brands instead.

08 · Versioning

Four ways to version, each for a different job

8.1Named versions in version history

Figma saves automatically. You name the moments that matter. Pattern: vMAJOR.MINOR — Milestone. Name a version at every approval, every handoff, before any risky restructure, and when you archive. These named versions are your real save points, and every plan has them.

v1.0 — Approved for build
v1.1 — Post-critique fixes
v2.0 — Statement redesign

8.2Branching

Branching and merging is only on Organization and Enterprise plans. If you have it, make changes to shared or published files on a branch, especially the design system, instead of editing main directly. Figma shows the differences and flags conflicts, so main is always ready to ship.

feature/evidence-export
fix/input-focus-ring
explore/statement-layout
chore/token-rename

8.3Version numbers for the design system (semantic versioning)

Treat ⭐ Design System like a code package. Major means a breaking change, like removing or renaming a token or changing a component's properties, and you announce it. Minor means something added, like a new component or token, and is safe to adopt. Patch means fixes. Put the version on the file thumbnail and in each library publish note.

8.4One official file per system

Each system has exactly one ⭐ file, and it is the only one you publish from. Don't version by duplicating files. A name like Design System copy 3 is not allowed. New ideas go on a branch or in an exploration section. Replaced work is marked 📦, never deleted, so you keep a record of what changed.

09 · Presenting and handoff

Making the work easy to follow for whoever picks it up next

9.1Presentation areas

Keep one clean area for showing work: a presentation section with only frames that are ready for stakeholders. No experiments, no scratch work, no open comments. Arrange frames left to right in the order you tell the story.

9.2Prototypes

One named flow per story. Set a sensible starting point and hide any dev scaffolding. Use prototypes to show behavior, and Slides to tell the story.

9.3Figma Slides

9.4Dev Mode handoff

• Mark finished areas Ready for Dev so developers get a focused, stable view.
• Add annotations for spacing, behavior, accessibility, and token bindings, as inspectable notes rather than loose text.
• Variables show in Dev Mode with code syntax for CSS, iOS, and Android. Your color/bg/surface appears as the real CSS custom property. This is why rule five says names should map to code.
• Figma Motion timelines can be inspected in Dev Mode. Every easing curve copies out as CSS, JSON, or React, and can go to a coding agent over MCP. Define motion on the canvas, not in writing.
• The Figma MCP server lets a coding agent, including Claude Code, read the design directly and pull variables, measurements, and component code. If things are named well, much of the handoff is already done.

9.5How to use comments

Comments are for decisions and questions. Specs that need to last go in annotations. Resolve comments once they are handled. A frame with open comments is not ✅ approved. Prefixes help: Q: for a question, NIT: for something minor, BLOCKER: for something that must be fixed.

10 · FigJam

When to use FigJam, Figma Design, and Slides

Board naming: [emoji] Product — Activity (date). One board per activity. End every workshop board with a ✅ Decisions group: the few outcomes that go into the brief. The rest of the board can be messy. The decisions should be clear, because they are what you give the agent at the brief stage.

11 · Figma AI tools

Figma's AI tools and what each one is for

This list reflects what shipped through Config 2026. That release added motion and shaders to the canvas, and let you build your own tools for the agent.

12 · Cheat sheet

The whole system on one screen

TEAM        Conformly
PROJECT     Conformly
FILE        ⭐ Design System  |  🟡 Evidence View  |  🧪 Sandbox
THUMBNAIL   cover frame, right-click, Set as thumbnail (16:10)
PAGE        🎨 Designs   🧩 Components   🟡 Flows   ——   📦 Archive
SECTION     ✅ Statement — v2     🧪 Statement — Spikes
FRAME       01 · Statement — Default   02 · ... — Error
LAYER       header / nav / cta-row   (role, not "Rectangle 12")
COMPONENT   Button/Primary   Form/Input/Search   (slots, not detach)
VARIANT     Type=Primary  Size=Md  State=Hover  Has Icon=true
VARIABLE    color/bg/surface   space/200   radius/md
STYLE       text/heading/h1   shadow/200   (composites only)
TOKENS      Primitives → Semantic → Component  (semantics alias, never hardcode)
MODES       Theme: Light/Dark   Breakpoint: Mobile/Desktop  (count is plan-gated)

AI LOOP     Generate → Curate → Refine → Guarantee
CONTEXT     library > skills > attachments > connectors > prompt
BINDING     tokens on real components + reference the library, then read for live bindings
AGENTS      native = inside-out (canvas)   MCP = outside-in (Claude Code, Codex)

STATUS      ⭐ source  ✅ approved  🚀 shipped  🔵 review
            🟡 wip  🧪 explore  ⚫ backlog  🔴 blocked  📦 archived

VERSION     v1.0 — Approved for build   (named checkpoints, every plan)
BRANCH      feature/...  fix/...  explore/...  (Organization / Enterprise)
SoT         one ⭐ file; branch, do not duplicate; archive, do not delete

A · Appendix

Starter design system file

Build this once. Use it as your template file, and point the agent at it.

File: ⭐ Design System  (v1.0)

📋  Readme
    cover frame   (title, version, owner, changelog)
    how to use / publish rules / link to the agent skill

📐  Foundations
    Color (primitive swatches → semantic roles)
    Type scale
    Spacing & radius scales
    Elevation / shadows
    Grids

🧩  Components
    Button   (set)
    Form/    (Input, Select, Checkbox, Radio)
    Navigation/
    Feedback/  (Toast, Banner, Empty State)
    Data/    (Table, Tag, Badge)
    Overlay/ (Modal, Popover, Tooltip)

🎟  Patterns
    Composed examples (a real form, a real table view)

──────
🧪  Explorations
📦  Archive

Variable collections:
    Primitives   (raw palette + scales)
    Semantic     (roles; modes: Light / Dark)
    Breakpoint   (number vars; modes: Mobile / Desktop)