figma-canon v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/f5e43ec3e672f357.

---
name: figma-canon
description: >-
  Read-only knowledge base of Figma canon for AI agents: a routing table of on-demand references
  (Plugin API core, data and anomalies, write atomicity, auto layout, inspection, handoff format,
  naming, state coverage, quality rubric, AI slop signatures, security, rate limits) plus hard
  rules learned in production (the canvas mutates under you, null-guard before operating, hex
  versus token). Use on any mention of Figma, a node id, a design system, a token, a component or
  auto layout, and before any figma_execute call. It informs writes and never performs one.
license: MIT
metadata:
  author: Thiago Xikota
  version: "1.0.0"
---

# figma-canon

Universal canon. The references live in `references/`. Load only what is relevant: token-efficient by design.

## Operating principle

You are an AI coding agent operating on a Figma file. Before any write (`figma_execute`), inspect the file. Before any inspection, load the relevant reference. Before any handoff, run the gate (skill `figma-handoff-gate`). Treat the canvas as a production artifact, not a playground.

## When to load each ref

A leading `+` means: in addition to what the task already loaded.

| Context | Load these references |
| --- | --- |
| About to write via `figma_execute` | `references/plugin-api-core.md` + `references/figma-execute-atomicity.md` + `references/auto-layout-canon.md` |
| Write touches tokens, variables, annotations or images | + `references/plugin-api-data.md` |
| Write hits edge cases (sections, connectors, masters, image-fill bug, rate limits) | + `references/plugin-api-anomalies.md` |
| New screen creation | + `references/state-coverage.md` + `references/ai-slop-signatures.md` + `references/naming-canon.md` |
| Handoff prep, pre-ship | + `references/handoff-format.md` + `references/ai-slop-signatures.md` |
| Inspect or orient on a new file | `references/inspect-protocol.md` |
| Validating JavaScript that the optional precheck hook flagged | `references/plugin-api-core.md` + `references/plugin-api-data.md` + `references/ai-slop-signatures.md` |
| Tooling failure (REST 429) | `references/rate-limit-recovery.md` + `references/plugin-api-anomalies.md` |
| Tooling failure (Bridge disconnect) | skill `figma-bridge-doctor` (self-contained) |
| A write behaves strangely | `references/plugin-api-anomalies.md` + `references/field-notes.md` (recent field notes not yet folded into the other files) |
| Post-write self-evaluation | `references/quality-rubric.md` |
| Code Connect mapping (component to React) | `references/code-connect-setup.md` |
| Security review, new MCP server | `references/security-canon.md` |
| Ad hoc prototype via `figma_execute` | `references/plugin-api-core.md` + `references/figma-execute-atomicity.md` + `references/auto-layout-canon.md` + `references/naming-canon.md` + `references/state-coverage.md` (+ `references/plugin-api-data.md` if binding variables, + `references/quality-rubric.md` in the final phase) |

## Hard rules (always-on, summary)

1. Inspect before editing (dump the structure of the target in this session, through the Bridge). The target node id is precise, never ambiguous.
2. Prefer existing components and tokens. Never recreate a component and never hardcode hex, spacing or typography. No style from outside the design system.
3. Auto layout on every multi-child container. Layers get semantic names (never `Frame N`). Variants use Title Case (`State=Hover`).
4. Cover every required state (not only the happy path). Document the big decisions (description + annotation).
5. Write path, the same two paths as Check 0 of `figma-preflight`. Path A: `figma_execute` (figma-console MCP server) through the Desktop Bridge, the path this repo validates. Path B, only for a setup where the official Figma MCP server is the only connection (figma-console is not installed). When a figma-console Bridge drops in the middle of a task, recover it with `figma-bridge-doctor` instead of switching servers: `use_figma` (official Figma MCP server), whose block is applied atomically. Path B is not validated by this repo: keep writes small, read back every change. `figma_execute` is NOT atomic: a script that fails midway CAN leave partial nodes. After a failure, sweep the parent for orphans BEFORE retrying (details in `references/figma-execute-atomicity.md`). Never run an API pattern that has no recovery (sync `figma.currentPage = x`, `createConnector` in a Design file, an async call without `await`). The optional precheck hook (`hooks/figma-canon-precheck.py`, opt-in) flags those patterns. Syntax rules live in `references/plugin-api-core.md`.
6. Return the ids of every write. Score against `references/quality-rubric.md` (below 8/10 = fix before declaring done).
7. WCAG AA contrast minimum (4.5:1 text, 3:1 UI). In an AUDIT, compose the `opacity` chain of the NODE and of its groups, not only `paint.opacity`: a group with `opacity: 0.35` flattens a pill and its glyph together and drops a high-contrast pair below AA without changing a single hex, and a pass that reads only the face value of the fill returns "clean" (field note, 2026-08: the defect was invisible to a full-page scan). Cheap detector: scan the tree for `opacity < 1` and separate legitimate chrome (status bar, home indicator, glass) from opacity used as STATE, which is forbidden as a hierarchy signal.
8. The canvas mutates under you in the middle of a session: the designer may be editing the file live (filling an image, deleting a node, dragging an asset in). Re-dump the state immediately before a batch write, null-guard every `findOne` and `getNodeByIdAsync`, and re-verify sensitive content before declaring done (field note, 2026-06: a video dragged in live reintroduced a content violation on a slide that was already marked done).
9. Null-guard BEFORE operating: `const n = page.findOne(...); if (!n) { re-dump, bail or recreate }`. Operating on null aborts the entire batch. A screen that came back blank: recover by cloning the fills of a known-good sibling (clone-mutate-reassign), never by hardcoding hex. Screenshot-verify before declaring done.
10. When the BACKGROUND CONTEXT of a cloned screen changes (for example white to a gray block `#EFEFEF`): audit in one pass ALL the fills that depended on the old background (dot rings, tracks, chips, hairlines, secondary text `#757575`). Detector: light fill on a light background. A 2nd patch on the same component = stop and redesign the whole row that contains it. A recolor sweep BY HEX with no role filter recolors the wrong node, in series (field note, 2026-07). Dump the structure of 1 exemplar BEFORE the sweep. Proof: a crop at >=1.2x of the critical components. A 0.3x overview is not proof.
11. A bulk hex-to-token migration COLLAPSES tinted chips and badges (bg token == text token = invisible text). After a bulk bind, scan the small frames (height <= ~46px with a TEXT child) where the variable of the bg == the variable of the text. Fix by tinting the bg (`paint.opacity ~= 0.16`) or by recoloring the TEXT to a contrasting token. The detector is built into the migration, not a hand-fix. Recurred 4 times on one project (field note, 2026-06).

## Defers to project canon

Project-specific canon overrides the universal rules where they conflict. Convention: the Figma map of each project lives in a `figma-map.md` file kept in the project (default `docs/figma-map.md`), or in the agent's own memory system if it has one. The `figma-orient` skill writes and consolidates it. If the map does not exist yet for the file in question, run `figma-orient` before any write. Any further project canon lives in the project's own repo (for example its design docs).

## Security canon (always-on, abbreviated)

- Allowed servers: the official Figma MCP servers, plus `figma-console` (figma-console-mcp by Southleft) as the local write path. Anything else: evaluate first. NEVER use `figma-developer-mcp` below 0.6.3 (CVE-2025-53967, RCE).
- Writes to production files require a Full seat (the seat table, drafts included, is in `references/security-canon.md`). Draft-first policy unless the user explicitly says otherwise.
- See `references/security-canon.md` for the full threat model.