The agent generates. You own the system it builds on.

00 · First principles

Six rules everything else descends from

When a question is not covered below, resolve it with these. Each section after this one states a pattern, an example, and where it earns the space a why and a do not. The point is not what any single convention is. The point is that you apply the same one on every project, and you hand that consistency to the agent.

1. Legibility over cleverness. A name tells 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. Exactly one canonical file, branch, or collection owns the truth. Everything else is a working copy, an exploration, or an archive, and it says so in its name.
3. Status is visible, always. State lives in the name as a glyph and a word, never as color alone. Glyph plus label survives colorblindness, search, screenshots, and a model reading the layer tree.
4. Additive, never destructive. New work extends. It does not overwrite. Branches and new sections beat duplicate file sprawl every time.
5. Names map to code. Tokens, components, and styles are named so they translate to CSS variables, Tailwind, and React props with no remapping. color/bg/surface becomes --color-bg-surface.
6. Your system is the agent's brief. The agent generates against whatever you have named and built. A clean, well named system is the difference between output that looks like your product and output that looks like a template. Conventions matter more now, not less.

Casing, fixed once

01 · The agent operating model

Generation is cheap. Your leverage moves to what it cannot own.

The blank canvas stopped being the starting line. You open with the agent in the file, and your work moves from drawing every pixel to directing the work and owning the system it draws on. What stays scarce, and therefore where your leverage concentrates, is the system, the direction, the judgment, and the guarantee.

Two agents, two directions

Know which one you are talking to, because they see different things.

• The native Figma agent works inside out. It lives on the canvas and reads your components, variables, styles, and file structure directly. Use it for canvas work that depends on your system: bulk edits, component swaps, dark mode conversion, filling flows with real content, generating screens that should match your product.
• External coding agents such as Claude Code and Codex work outside in through the Figma MCP server. They read the design and pull variables, measurements, and component code into your stack. Use them for the design to code direction and the round trip back.

Where the agent is strong, and where it is not

• Strong: multi screen mobile flows built on a real, component based system, bulk and repetitive edits across a file, populating layouts with realistic content, and first passes you intend to react to.
• Weak: single desktop screens, novel layouts with no system to lean on, and files with only loose tokens. Given loose variables, it tends to reference them by name and still leave unconnected hex behind. The fix is in the next section.

The four jobs that stay yours

As generation gets cheaper, the cost of shipping something merely average drops to zero, which means the only thing that distinguishes your work is what the agent cannot own.

• The system. The tokens, components, and library the agent builds on. This is the asset that compounds.
• The direction. The prompt, the references, and the taste call on what is actually good.
• The judgment. Accessibility, edge cases, truthfulness, ethics. The agent does not own the outcome. You do.
• The handoff. Naming and structure so the work stays legible to the next reader, whether that reader is a teammate, a coding agent, or production code over MCP.

02 · Context engineering

Build the environment that makes a plain instruction produce on system work

The agent is only as good as the context it stands in. This is the highest leverage skill in the new workflow, and it is mostly upstream of any prompt. You are not writing clever instructions. You are building the environment.

What the agent reads, ranked by how much it shapes the output

1. Your published library. Components and variables it can actually apply. This is the single biggest lever. No library, no system to match.
2. Skills. Reusable instruction files that encode your conventions, called by name. This document, turned into a skill, is your naming and token spec made executable.
3. Attachments. Reference images, briefs, data files, and screens you hand a specific prompt.
4. Connectors. Live context from the tools where the 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 the least when the four inputs above are missing, and the most when they are in place.

The token binding rule

This is the one that separates clean output from a pile of raw hex. The agent binds to tokens reliably when those tokens are attached to real components and you reference the library in the prompt. It binds poorly to loose variables floating in a file. So the order of operations is fixed:

1. Build the component layer first, with tokens bound to it.
2. Publish the library.
3. Reference the library and the components you want by name in the prompt.
4. Then generate.

Make this document a skill

Skills are markdown files you invoke with a slash command, and the design agent takes them alongside attachments and connectors. Encode the rules here, the casing table, the status glyphs, the naming spec, the token tiers, as a skill, and every generation starts on system by default. The same instruction file pattern feeds an external coding agent over MCP, so one source of conventions governs design and code at once.

03 · The hierarchy at a glance

Figma nests like this, and each level gets its own convention

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

Cross cutting systems run alongside the tree, not inside it: Components, Variables in Collections with Modes, Styles, Published Libraries, Branches, and Prototype flows.

04 · The status system

One glyph set, used the same way on files, pages, and sections

Glyph plus word, always. Most of your state signaling rides on this one set.

Rule: one status glyph, at the front of the name. When status changes, swap the glyph. The rest of the name holds, so links and muscle memory survive.

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

05 · The workflow

The lifecycle, run with the agent in the file

At each stage the agent does a first pass and you direct, curate, and own the result. Solo or team, the spine is identical. Solo just collapses the review gates into self review.

Project setup checklist, do once, every time

1. Create the Project, named for the product.
2. Create the spine of files: ⭐ Design System as the library you publish and point the agent at, 🟡 Flows for maps and IA, one file per surface or feature as needed, and a 🧪 Sandbox for throwaway and agent explorations that you never publish from.
3. Set the file thumbnail so the project board reads at a glance.
4. In the design system file, create your variable collections and page scaffold.
5. Publish the library, enable it in the surface files, and add your conventions as an agent skill.

06 · Naming, the complete spec

Each level, its pattern, and where it earns it, a do not

6.1Teams

Pattern: Domain, the product line or area of life. Teams are the coarsest filter. Keep them few and stable, and do not spin one up per feature.

6.2Projects

Pattern: Product, one project per product. Do not put dates or versions in a project name. That is what files and version history are for.

6.3Files

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

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

The design system file is always ⭐ Design System, and the only file you publish components and variables from. When a file is superseded, append its old version label and set it 📦 rather than deleting it.

6.4File thumbnail

The thumbnail is what you see on the project board. Set any frame as the thumbnail rather than leaving it to chance. Pattern: a dedicated cover frame at 16:10 holding product mark, file title, status glyph and label, owner, and last updated date. A board of deliberate covers is instantly navigable. A board of random first screens is noise.

6.5Pages

Pages divide a file into phases or workstreams. Use a small, repeatable set, with divider pages to group them.

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

Divider pages hold no work. Name them as a rule of dashes or as —— REFERENCE ——, and let them act as separators in the page list.

6.6Sections

Sections are real canvas objects, not frames. Use them to group and status regions of a page. They carry status, collapse, can be marked Ready for Dev, and keep a busy page scannable.

✅ 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 index so screens sort in flow order. The state is the variant: Default, Empty, Loading, Error, Success.

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

Every interactive screen names its states as sibling frames. Empty, loading, error, and success are first class, not afterthoughts. Never ship Frame 427. Rename or delete auto named frames before handoff.

6.8Groups and layers

Pattern: name the role, not the shape. Rename anything you would reference, prototype to, or hand off. Prefer auto layout frames over groups for structure, since they survive content changes, and name containers by function: row, stack, card, field.

6.9Components

The backbone. Use slash nesting. Figma turns slashes into a folder tree in Assets, and it maps to how you would organize code.

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

First segment is the category, kept short and fixed. Do not put states in the name, that is what variants are for: Button/Primary with a State property, not Button/Primary/Hover. One component, one job. Use slots for controlled flexibility instead of letting designers 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 surface verbatim in Dev Mode and in generated props. Sloppy variant names become sloppy props, and the agent will repeat them.

6.11Variables and tokens

Pattern: group/subgroup/name, lower kebab, slash grouped. Group by role, not raw value. Numeric scales step in hundreds so you can insert between later without renumbering. Full architecture in section 07.

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

6.12Styles

A light, dark, or multi brand value is a variable. A bundle of properties reused as a unit is a style, built on variables.

6.13Prototype flows

Name every flow starting point for what it demonstrates. One flow is one story a stakeholder can click through unaided. Motion specs live in the timeline and are inspectable in Dev Mode, so do not redescribe easing in text.

6.14Annotations

Use Dev Mode annotations, not floating text, so they are structured and inspectable. Lead 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, lower kebab. Set export settings on the component or frame, named to the final filename, so re exports are one click and stay consistent.

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

07 · Token and variable architecture

A three tier system, so theming, multi brand, and clean handoff are possible

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

Tier 1, Primitives

The raw palette and scales, in a Primitives collection. Never applied to designs directly. color/blue/500, space/8, radius/4.

Tier 2, Semantic

Roles that alias primitives, in a Semantic or Theme collection. This is what you actually apply to layers, and what the agent should bind to.

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 knobs, such as button/padding-x aliasing space/gutter.

Collections and modes

• A collection is a set of variables plus its modes. Keep semantic theming in one collection so a single mode switch reskins everything.
• Modes are contexts. Typically Theme as Light or Dark, and Breakpoint as Mobile or Desktop with number variables for spacing. Mode count per collection is plan gated and rises with your tier, so design your strategy around the plan you are on.
• Extended collections let you extend a parent semantic collection per brand, inheriting every variable and mode and overriding only what differs. This is the real single source of truth for multi brand. It is an Enterprise capability, so on lower tiers you model multi brand with modes instead.

08 · Versioning

Four mechanisms, each for a different job, instead of duplicating files

8.1Named version history checkpoints

Figma autosaves continuously. You name the moments that matter. Pattern: vMAJOR.MINOR — Milestone. Stamp at every approval, every handoff, before any risky restructure, and at archive. These named points are your real saves, available on every plan.

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

8.2Branching

Branching and merging is an Organization and Enterprise feature. Where you have it, branch any change to a shared or published file, especially the design system, instead of editing main directly. Figma diffs and flags conflicts, and main always stays shippable.

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

8.3Semantic versioning for the design system

Treat ⭐ Design System like a package. Major is breaking, a token removed or renamed or a component API changed, and you announce it. Minor is additive, a new component or token, safe to adopt. Patch is fixes. Record the version on the file thumbnail and in each library publish note.

8.4Source of truth policy

Exactly one ⭐ file per system, the only thing you publish from. No duplicate file versioning. A name like Design System copy 3 is banned. New direction goes to a branch or a spike section. Superseded work goes to 📦, never deleted, because archiving keeps the audit trail.

09 · Presenting and handoff

Make the work legible to the next reader, human or agent

9.1Presentation regions

Keep a clean, scaffold free region for showing work: a presentation section with only stakeholder ready frames. No spikes, no scratch, no open comments. Order frames left to right in narrative order.

9.2Prototypes

One named flow per story. Set a sensible starting point and hide dev scaffolding. Use the prototype for behavior, and Slides for narrative.

9.3Figma Slides

9.4Dev Mode handoff

• Mark finished regions Ready for Dev so devs get a focused, stable surface.
• Add annotations for spacing, behavior, accessibility, and token bindings. Inspectable, not floating text.
• Variables appear in Dev Mode with code syntax for CSS, iOS, and Android. Your color/bg/surface shows as the actual custom property. That is the payoff of principle five.
• Figma Motion timelines are inspectable in Dev Mode. Every easing curve copies out as CSS, JSON, or React, and passes to a coding agent over MCP. Spec motion on the canvas, not in prose.
• The Figma MCP server lets a coding agent, Claude Code included, read the design directly and pull variables, measurements, and component code. Name things well and your handoff is half built already.

9.5Comment etiquette

Comments are for decisions and questions, not durable specs. Those are annotations. Resolve when addressed. A frame with open comments is not ✅. Prefix when useful: Q: question, NIT: minor, BLOCKER: must fix.

10 · FigJam

The thinking space, before and around the pixels

Board naming: [emoji] Product — Activity (date). One board per activity. End every workshop board with an ✅ Decisions cluster, the few outcomes that flow into the brief. The board can sprawl. The decisions stay crisp, and they are what you hand the agent at the brief stage.

11 · The Figma AI toolkit

The agent is the through line. Everything else is a material or a surface.

The list below reflects what shipped through Config 2026, when motion and shaders joined the canvas as first class materials and the agent picked up tools you can build yourself.

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 scaffold

Build this once. Reuse 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)