Design Ops · Reference

Figma Operating System

A working standard for running Figma with an agent in the file. The agent generates. You own the system it builds on, the direction it follows, and the guarantee at the end. Written for people who already know the tool and want the operating model, not the tour.

How to read this: each section states a pattern (the rule), an example, and where it earns its place a why and a don't. It assumes fluency in Figma. 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.

00First principles

Six rules everything else descends from. When a question isn't covered below, resolve it with these.

1. Legibility over cleverness. A name tells a teammate, future you, or an agent what the thing is and what state it's 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

01The agent operating model

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. Generation is cheap now. What stays scarce, and therefore where your leverage concentrates, is the system, the direction, the judgment, and the guarantee.

The loop

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 in the left rail, and it 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 (Claude Code, Codex, and others) 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.

The native agent is in beta as of mid 2026, rolling out in waves to Full seats on Professional, Organization, and Enterprise plans, with View, Collab, and Dev seats limited to Draft files. Starter, Education, and Government are not in the beta. It is free during the beta and does not draw AI credits; standard credit usage starts at general availability. Treat all of that as a moving target and check the current state before you quote it to anyone.

Where the agent is strong, and where it is not

Direct it to its strengths instead of fighting its weaknesses.

• Strong: multi screen mobile flows built on a real, component based system; bulk and repetitive edits across a file; populating layouts with realistic content; 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 and styles, 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.

02Context engineering

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 that makes a plain instruction produce on system work.

What the agent reads

Five inputs, ranked by how much they shape 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 actually 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.

Read the output for binding, not just for looks. A screen can look right and still be full of detached hex values that will never theme. After every generation, inspect a sample of fills and text for live token bindings. Unbound values are the most common failure, and the easiest to miss.

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. Your naming spec and your automation spec become one artifact. The same instruction file pattern feeds an external coding agent over MCP, so one source of conventions governs design and code at once.

03The hierarchy at a glance

Figma nests like this. Each level gets its own convention, with the full spec in §06.

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, Prototype flows.

04The status system

One glyph set, used the same way on files, pages, and sections. Glyph plus word, always.

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

05The 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, foundations, components, and the library you publish and point the agent at
   • 🗺️ Flows, maps, IA, prototypes
   • One file per surface or feature as needed (🟡 Evidence View)
   • 🧪 Sandbox, throwaway and agent explorations; never publish from here
3. Set the file thumbnail (§6.4) so the project board reads at a glance.
4. In the design system file, create your variable collections and page scaffold (§07, Appendix).
5. Publish the library, enable it in the surface files, and add your conventions as an agent skill.

06Naming conventions, the complete spec

6.1 Teams

Pattern: Domain, the product line or area of life. Examples: Conformly · Reply First · Aspen Valley News · Job Search.
Why: teams are the coarsest filter. Keep them few and stable. Do not spin one up per feature.

6.2 Projects

Pattern: Product, one project per product. Examples: Conformly · howmuchwouldihaveif.com · Criterion.
Don't: put dates or versions in a project name. That is what files and version history are for.

6.3 Files

A file is one surface, one system, or one workstream. Not one screen, not the whole product.

Pattern: [status] Surface — [Descriptor]

⭐️ Design System
🗺️ Flows & IA
🟡 Evidence View
🟡 Accessibility Statement
🔵 Onboarding — Redesign
🧪 Sandbox
📦 Evidence View v1

• Lead with the status glyph.
• The design system file is always ⭐️ Design System, and the only file you publish components and variables from.
• A 🧪 Sandbox per project absorbs throwaway and agent generated work so real files stay clean.
• When a file is superseded, append its old version label and set it 📦 rather than deleting it.

6.4 File thumbnail

The thumbnail is what you see on the project board. Do not leave it to chance. Set any frame as the thumbnail (right click the frame, then Set as thumbnail).

Pattern: a dedicated --- COVER --- frame at 16:10 holding product mark, file title, status glyph and label, owner, and last updated date.
Why: a board of deliberate covers is instantly navigable. A board of random first screens is noise.

6.5 Pages

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: name them ──────────────── or ── WORK ── / ── REFERENCE ──. They hold no work. They are separators in the page list.

House glyph set (pick once, reuse everywhere): 📋 readme · 🗺️ flows · 🎨 designs · 🧩 components · 🎟️ prototype · 📐 foundations · 🧪 explorations · 📦 archive · 🔧 handoff.

6.6 Sections

Sections are real canvas objects, not frames. Use them to group and status regions of a page. Most of your status signaling lives here.

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

Why sections, not frames, for grouping: they carry status, collapse, can be marked Ready for Dev, and keep a busy page scannable.

6.7 Frames / screens

Pattern: ## · Surface — State. ## is a two digit index so screens sort in flow order. 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.
• For responsive sets, suffix the breakpoint: 01 · Dashboard — Default · sm, … · lg.

6.8 Groups & layers

Pattern: name the role, not the shape.

✅  header
    nav
    cta-row
    status-badge
✗  Rectangle 12
✗  Group 5

• Rename anything you would reference, prototype to, or hand off. Decorative one offs can stay default.
• Prefer auto layout frames over groups for structure, since they survive content changes. Reserve raw groups for static clusters.
• Name auto layout containers by function: row, stack, card, field.

6.9 Components

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 (Button, Form, Navigation, Feedback, Data, Layout, Overlay). Keep the category list 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. If you are tempted to call it CardOrBanner, split it.
• Use slots for controlled flexibility instead of letting designers detach instances. A slot keeps the instance live while allowing the content inside it to change.

6.10 Component sets & variant properties

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

Property names (Title Case, fixed vocabulary): Type · Size · State · Variant · Icon · Disabled (boolean).

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

Why: these names surface verbatim in Dev Mode and in generated props. Sloppy variant names become sloppy props, and the agent will repeat them.

6.11 Variables & tokens

Pattern: group/subgroup/name, lower kebab, slash grouped. Full architecture in §07.

color/bg/surface
color/bg/surface-raised
color/text/default
color/text/muted
color/border/default
color/accent/primary
space/100   space/200   space/400
radius/sm   radius/md
font/size/body   font/size/h1

• Group by role, not raw value: color/text/muted, never color/gray-600 at the semantic layer.
• Numeric scales step in hundreds (100/200/400/800) so you can insert between later without renumbering.
• Maps one to one to CSS: color/bg/surface becomes --color-bg-surface, which becomes Tailwind bg-surface.

6.12 Styles (color / text / effect / grid)

Rule of thumb: variables hold raw, themeable values (a single color, a number). Styles hold composites (a full type style, a shadow stack). Styles can consume variables. Variables cannot consume styles.

Text:    text/heading/h1   text/body/default   text/label/sm
Effect:  shadow/100   shadow/200   focus-ring
Grid:    grid/desktop-12   grid/mobile-4

Decision shortcut: 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.13 Prototype flows & starting points

Pattern: name every flow starting point for what it demonstrates.

Flow: Generate & Publish Statement
Flow: Empty → First Run
Flow: Error Recovery

One flow is one story a stakeholder can click through unaided. Motion specs live in the timeline (§9.4) and are inspectable in Dev Mode. Do not redescribe easing in text.

6.14 Annotations

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.15 Exports / assets

Pattern: name-descriptor@scale.ext, lower kebab.

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

Rule: set export settings on the component or frame, named to the final filename, so re exports are one click and stay consistent.

07Token & variable architecture

A three tier system. It is what makes theming, multi brand, and clean handoff possible, and it is what gives the agent a coherent palette to build on.

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

Tier 1, Primitives (collection: Primitives)

The raw palette and scales. Never applied to designs directly.

color/blue/500   color/gray/900   color/white
space/4  space/8  space/16  space/24
radius/4  radius/8

Tier 2, Semantic (collection: Semantic / Theme)

Roles that alias primitives. 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
radius/control          → radius/8

Tier 3, Component (optional)

Only when a component needs its own knobs (button/padding-x → space/gutter).

Collections & modes

• Collection equals a set of variables plus its modes. Keep semantic theming in one collection so a single mode switch reskins everything.
• Modes equal contexts. Typical: Theme as Light / Dark (/ High Contrast); Breakpoint as Mobile / Desktop with number variables for spacing. The mode count per collection is plan gated and rises with your tier, so design your mode strategy around the plan you are actually on.
• Extended collections let you extend a parent Semantic collection per brand, inheriting every variable and mode and overriding only the values that differ. This is the real single source of truth for multi brand. Note that extended collections are an Enterprise capability, so on lower tiers you model multi brand with modes instead.
• Apply modes at the frame or page level so one design previews across contexts without duplicate screens.

Naming guardrails

• Primitives may reference raw values (blue/500). Semantics must never hardcode a hex. They always alias a primitive.
• Up to 5,000 variables per collection. Clarity is the constraint, not the cap.
• Every semantic variable answers "where does this go" (bg, text, border, accent), not "what color is it".

08Versioning

Four mechanisms, each for a different job. Use them deliberately instead of duplicating files.

8.1 Named version history checkpoints (every plan)

Figma autosaves continuously. You name the moments that matter. Pattern: vMAJOR.MINOR — Milestone.

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

When to stamp: every approval, every handoff, before any risky restructure, and at archive. These named points are your real saves. Roll back or branch from any of them.

8.2 Branching (Organization & Enterprise)

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.

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

Flow: branch, work, request review, resolve, merge. Figma diffs and flags conflicts, and main always stays shippable.

On Professional or solo, with no branching: use named checkpoints (§8.1) as your rollback points, do risky work in a 🧪 section or the 🧪 Sandbox file, and duplicate a file only as a deliberate, dated snapshot (📦 … v1). Never as ongoing version control.

8.3 Semantic versioning for the design system

Treat ⭐️ Design System like a package. MAJOR is breaking: a token removed or renamed, 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.4 Source of truth policy

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

09Presenting & handoff

9.1 Presentation pages / sections

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.2 Prototypes (clickthroughs)

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

9.3 Figma Slides (stakeholders & narrative)

Use Figma Slides when the audience needs a story, not a canvas: kickoffs, design reviews, GTM, exec updates. It sits next to your design files and pulls in live frames. Keep a reusable Deck Template so every deck starts on brand.

Rule of thumb: FigJam to think, Figma to design, Slides to tell.

9.4 Dev Mode handoff

• Mark finished regions Ready for Dev (section status). Devs get a focused, stable surface.
• Add annotations (§6.14) for spacing, behavior, a11y, 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 5.
• Figma Motion timelines are inspectable in Dev Mode. Every easing curve and keyframe 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 for the agent already.

9.5 Comment 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.

10FigJam

The thinking space, before and around the pixels.

Board naming: [emoji] Product — Activity (date)

🧠 Conformly — Discovery (Jun)
🗺️ Conformly — Journey Map
🧩 Reply First — IA Workshop
🔁 Aspen Valley — Sprint Retro

• One board per activity. Do not let a board become a junk drawer.
• End every workshop board with a ✅ 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.
• Keep reusable templates (journey map, 2×2, affinity, retro) so sessions start fast.

11The Figma AI toolkit

The agent is the through line. Everything else is a material it works in or a surface it acts on. 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.

Design engineer note: the agent's skills are reusable instruction files, the same pattern as this document. Lift the naming and token rules here into a Figma skill, and every generation already speaks your system. Pair it with the MCP server and a coding agent reads the result straight into your Next.js and Tailwind stack. Your design spec, your automation spec, and your handoff spec become one chain.

12Cheat sheet

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 for flex, not detach)
VARIANT     Type=Primary  Size=Md  State=Hover  Has Icon=true
VARIABLE    color/bg/surface   space/200   radius/md   text/body/default
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)
FLOW        Flow: Generate & Publish Statement
ANNOTATION  [Spacing] [Behavior] [A11y] [Token]
EXPORT      og-card-home@2x.png

AI LOOP     Generate → Curate → Refine → Guarantee
            system + conventions = the agent's brief; encode them as a skill
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 (code: 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)
SOLO        no branches → checkpoints + 🧪 section + dated 📦 snapshots
SoT         one ⭐️ file; branch don't duplicate; archive don't delete

AAppendix, 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 ---            (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)