Figma Authoring Constraints

/figma-authoring-constraints

Figma-side rules that make a design clean and code-able before it reaches an agent. These are the design half of the pipeline: the figma-design-fetch skill fetches + implements + verifies; this is what makes the fetch worth anything. If a design breaks these, get_design_context degrades to a rigid pixel snapshot and get_variable_defs comes back empty — no amount of agent effort fixes a design authored as a flat mockup.

Authoritative source: Figma's Structure your Figma file for better code. Each rule is one executable sentence + a reference. Give this to designers; the figma-design-fetch pre-fetch lint enforces a subset (unbound colors · default names · raster nodes · absolute positioning) as a hard gate.

Master TOC

• [Variables / tokens (1–5)](#variables--tokens-15)
• [Auto layout (6–9)](#auto-layout-69)
• [Components / variants (10–12)](#components--variants-1012)
• [Naming (13–15)](#naming-1315)
• [Dev Mode / Code Connect readiness (16–18)](#dev-mode--code-connect-readiness-1618)
• [Don't use raster placeholders (19–20)](#dont-use-raster-placeholders-1920)
• [How these map to the MCP gotchas](#how-these-map-to-the-mcp-gotchas)
• [Companion](#companion)
• [Provenance](#provenance)

Variables / tokens (1–5)

1. Bind every color, spacing, radius, and font size to a Figma variable — never a bare literal. This is

exactly what get_variable_defs returns; unbound values force the agent to eyeball hex. (Figma, variables guide)

1. Build two token tiers: primitive → semantic. Primitives hold raw values (color ramps / spacing steps);

semantics alias them by UI role (page background / primary action / danger text). (zeroheight)

1. **Name semantic tokens by intent, not appearance** — text/subdued (survives dark mode), not text/gray

(breaks the moment a mode is added).

1. Prefer variables over styles for anything tokenizable (variables carry modes/themes, scoping, and

code-syntax handoff); reserve styles for what variables can't express — gradients / compound fills / shadows. (Figma)

1. Set a "code syntax" on variables so handoff / MCP emits the real code-side token name, not the Figma label.

Auto layout (6–9)

1. Every container uses auto layout — no absolute positioning. Auto layout is what tells the agent the

responsive intent, and it maps cleanly to flexbox. (Figma, auto layout guide)

1. Set padding / gap / direction / alignment in the auto-layout panel, don't hand-nudge — they map directly

to padding / gap / flex-direction / alignment.

1. Use hug vs fill deliberately (buttons/cards hug = content-sized; sections fill = flex-grow:1); don't mix

fill children under a hug parent.

1. Nest auto-layout frames to express the real DOM hierarchy (header + content each with its own padding/gap).

Components / variants (10–12)

1. Componentize anything reused (button / card / input / nav item).
2. States of one thing = variants; genuinely different things = different components; organize by named

properties (Size / State). (variants)

1. Make every interactive state a variant (default / hover / active / focus / disabled) so the agent has an

implementable state to build.

Naming (13–15)

1. Replace default names with intent names: Frame1268 / Group5 → CardContainer / ProductImage /

CTA_Button.

1. Match component names to what developers call them in code, encoding hierarchy with /

(Button/Primary/Default); write the convention down before the first component. (LogRocket)

1. Give pages / sections / frames clear, navigable names — think about how a developer or agent finds this

frame. (Dev Mode guide)

Dev Mode / Code Connect readiness (16–18)

1. Use Code Connect to link Figma components to real code — Figma calls it the first path to consistent

code-side reuse; without it the model can only guess. (Needs Org/Enterprise; without it, use the markdown Need→Token contract from #2/#13.)

1. Use annotations + dev resources to convey intent visuals can't (behavior / alignment / responsiveness;

link to the real component / doc).

1. Select small frames (one Card, one Header), not big heavy frames — small selections keep the MCP context

controllable and the output predictable. (custom rules)

Don't use raster placeholders (19–20)

1. Never hand the agent a flattened / rasterized mockup or a pure-image frame — an image has no semantics,

so the model only produces a pixel snapshot that drifts from the design system. Build with real layers + variables + components. (LogRocket)

1. Avoid unnamed / deeply-nested layers mixed with tokens (the inverse of #13/#2).

How these map to the MCP gotchas

• Empty get_variable_defs = the design bound no variables (not an MCP bug). #1–#5 are the fix; the

figma-design-fetch pre-fetch lint makes "variables bound" a gate before code-gen.

• get_design_context quality tracks structure — auto layout / componentization / semantic names / Code

Connect are exactly what make it emit componentized code instead of a div-soup.

• Low-fidelity mockup → pixel snapshot = breaking #19; the fix is entirely on the design side.
• Code Connect paywall (needs Dev/Full seat + Org/Enterprise): when you lack it, #2/#13's markdown

Need→Token table + component barrel is the substitute mapping contract.

Companion

• figma-design-fetch — the agent-side pipeline that consumes a design authored to these rules; its pre-fetch

lint enforces #1 / #6 / #13 / #19 as a gate.

Provenance

The Figma-side (Part B) half of the Figma→code pipeline, distilled from Figma's official "structure your file" guidance + the aliafsahnoudeh reference project. Kept as a standalone designer-facing spec so the design and the agent-side pipeline evolve together.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jajupmochi
• Source: jajupmochi/agent-harness
• License: MIT

Install and usage instructions live in the source repository linked above.