Figma AI Guideline - Canonical

active v1.3Updated3 tuần trước

Figma AI Guideline

Canonical layer cho AI agents (Claude Code, Codex, Cursor) làm design work trong Figma - tạo components, variables, styles; refactor tokens; publish libraries.

Status

🟢 Active v1.2 (R18 2026-04-24). Split-architecture: slim index + per-page detail files + CLI lookup tool. Optimized for AI context efficiency (3-tier access: ≤500 tokens for precise queries, ≤500 lines for index, ≤300 lines for detail files).

Current canonical content:

File	Purpose	Tier
`naming-convention.md`	4-category semantic naming + intensity modifiers + 5 binding anti-patterns	TIER 1 always-on
`variable-selection.md`	Intent → variable decision tree (10 common design tasks → direct variable names)	TIER 1 always-on
`workflows.md`	5 operational runbooks (bind / extract / mode-audit / DELETED-cleanup / instantiate)	TIER 1 always-on
`variable-registry.md`	All 838 AI-facing DS variables - sectioned by category, grep-by-section	TIER 2 grep
`variable-id-map.md`	Variable name → Figma ID + collection ID + mode IDs (extracted from live DS file)	TIER 2 grep
`component-registry.md`	Slim INDEX (~250 lines): all 44 detail files + 3-key preview per page	TIER 3 entry
`components/<page-slug>.md`	44 detail files with full variant property schemas per DS page	TIER 3 on-demand
`components/_index.json`	Machine-readable catalog consumed by `tools/lookup.py`	(not for direct read)
`tools/lookup.py`	CLI for precise queries (component / variants / variable / variables / search)	TIER 0 ≤500 tokens
`tools/extract-figma-metadata.py`	Generator: reads cache JSONs → emits index + 44 detail files + machine JSON; `--check` CI gate	meta
`tools/extract-variable-registry.py`	Generator: reads `dist/tokens-data.json` → variable-registry.md; `--check` CI gate	meta
`tools/resync-figma.md`	Re-extraction runbook for metadata + VALUES (Step 1.5 = value pull → diff → apply → propagate). Run when DS team publishes changes or token values shift.	meta

Planned extensions (future, on signal):

🟡 publish-workflow.md - Library publish patterns when publish-cycle signal emerges
🟡 recipe mode in lookup.py - emit pre-baked variable bundle for common builds (button-primary, alert-danger, etc.)
🟡 Pre-commit hook wiring all 3 generators with --check

Scope

✅ IN SCOPE for this folder

Semantic naming conventions (stable rules)
Operational patterns (AI workflow phases)
KEY/ID references (cheat sheets)
Prompting patterns for Figma tasks
Anti-patterns observed during AI Figma work

❌ OUT OF SCOPE (belong elsewhere)

Content	Belongs to	Why
MCP bridge troubleshooting	`../operations/`	Audience = humans fixing ops, not AI doing work
Figma design rationale (why this token exists)	`../ds-guideline/`	Design intent layer, not operational
Token values (hex, scale)	`../../docs/tailwind-color-guideline.md`	Token infrastructure
Session observations (experimental)	`ai-memory/lessons/`	Sessional, not yet stable for canonical
Skill draft (procedural)	`ai-memory/skill-drafts/` or `.claude/skills/`	Workspace skill system

Relationship with sessional layer

Rules here get promoted from ai-memory/lessons/figma-*.md only after 2-3 stable sessions without evolution. Pre-promotion state = rule lives in sessional lesson only.

Current source lessons (sessional, not canonical):

ai-memory/lessons/dol-figma-semantic-token-naming.md → promoted to naming-convention.md (2026-04-23)
ai-memory/lessons/figma-variable-extraction-from-reference.md → canonical-ized into workflows.md Workflow 2 (R16 2026-04-24)
ai-memory/lessons/figma-dynamic-page-async-apis.md - sessional (MCP pattern - may merge into workflows later)
ai-memory/lessons/figma-execute-performance-patterns.md - sessional (perf - orthogonal to design guideline)
ai-memory/lessons/figma-mcp-bridge-port-recovery.md - sessional (ops - not AI-facing)
ai-memory/lessons/figma-plugin-api-identifier-model.md - sessional (API identifier semantics)
ai-memory/lessons/figma-screenshot-hygiene.md - sessional (screenshot workflow)
ai-memory/lessons/figma-variant-component-workflow.md - sessional (variant handling)

How AI agents use this folder

Start at: ../ai-entry/FIGMA-AI.md (router + hard rules + self-check).

Follow pointers from router to specific files here when needed.

Don’t read this README directly during task execution - it’s for humans understanding the folder structure.

MCP setup (multi-instance + multi-file parallel, v1.10.0+)

DOL Edu workflow thường multi-file (DS V2 source + consumer files). Setup canonical:

Mode: NPX (94+ tools, write + real-time). Cloud (43) / Remote SSE (22) chỉ dùng read-only exploration.
Required env: FIGMA_ACCESS_TOKEN=figd_... + ENABLE_MCP_APPS=true (unlock token browser, DS dashboard, design-code parity audit).
Multi-instance: re-import Desktop Bridge plugin manifest sau v1.10.0 → plugin scan all 10 ports (9223-9232), broadcast events to all servers.
Per-session file routing: each Claude session calls figma_navigate(url) to claim active file independently.
Disciplined 1-session-per-file to avoid race conditions; up to 10 parallel sessions.

Full setup steps + workflow recipes + power features + anti-patterns: ai-memory/lessons/figma-mcp-multi-instance-parallel-setup.md.

Governance

Promotion criteria: 2-3 stable sessions without friction → promote từ sessional sang canonical
Demotion: khi canonical rule conflict với reality → flag, update, or mark superseded
Review cadence: sau mỗi 3-5 Figma sessions, review ai-memory/lessons/figma-*.md for promotion candidates
Change log: track promotions in CHANGELOG.md (future) when content volume justifies

AI entry (router): ../ai-entry/FIGMA-AI.md
Ops runbook (human-facing): ../operations/
Design intent: ../ds-guideline/DIRECTION.md
Decision record: ai-memory/lessons/ai-entry-pattern-vs-split-decision.md

Figma AI Guideline - Canonical