DOL Figma AI Guide - AI Entry

DOL Figma AI - AI Entry

You are an AI agent doing design work in Figma for DOL Education platform (create/modify components, variables, styles, layouts). This is your entry point.

Status note

🟢 Active v1.3 (R19 2026-04-24). Added Organizer Kit layer (canvas meta-components) separate from DS V2 (UI building blocks). Split-architecture: slim index + per-page detail files + CLI lookup tool.

Current coverage:

• DS V2 (UI building blocks): 532 sets + 2,653 standalone across 44 detail files · variable registry (838 tokens) · variable ID map (7 collections) · intent→variable decision tree · 5 workflow runbooks · 5 binding anti-patterns
• Organizer Kit (canvas meta - R19): 67 components across 10 categories · usage-patterns doc with Level 1/2/3 hierarchy + flow arrow rules · 10 detail files

If a task type isn’t in §4 Router, check ../figma-ai/README.md or ../figma-ai/organizer/README.md for extensions.

1. How to use this file

1. Read §2 Hard rules - non-negotiable for every Figma task
2. Read §3 Context defaults - Figma file conventions
3. Match your task in §4 Router → read listed file(s) before acting
4. After task, run §5 Self-check
5. If stuck / task not covered → §6 Sessional fallback

2. Hard rules (always applies)

[!warning] Non-negotiable. Violating any rule below = stop, ask, fix.

Token binding

• Always bind variables when DS has matching token - never hardcoded hex if DS-Token covers the value.
• 4 categories by target property (see ../figma-ai/naming-convention.md):
  • fill/* → frame/shape background
  • text-color/* → text node fills
  • icon-color/* → icon vectors (NOT text-color, even if same hex)
  • border-color/* → strokes
• Semantic role only - no feature-name tokens (cause-bg, effect-text). Use info/warning/success/danger/brand.
• Intensity modifiers: dim (subtle bg) / soft (hover) / primary (text, icons) / secondary (focus ring).

Style layer precedence

• Variable-first → Effect style (elevation/focus) → Paint style (decorative only when canon).
• Don’t use paint style as fill replacement for semantic role.
• Don’t use effect style to compensate for weak spacing/hierarchy.

Workflow discipline

• Extract boundVariables from reference component trước khi build từ scratch - shortest path to DS alignment.
• Focus ring = global border-color/progress-secondary (not type-specific).
• Hex fallback = documented workaround, not a pattern. Flag missing token to user/DS team instead of normalizing hex usage.

3. Context defaults (assume unless user says otherwise)

• Target file: DOL Design System V2 (variable collection id active trong figma-console-mcp session)
• Mode: GM (General) default; switch to KM (KID) only when user specifies KID context
• Extraction source: when building new component, prefer extracting reference component via figma_get_component_for_development_deep → read boundVariables → build from token binding, not raw hex
• Auto-layout: prefer hug contents for atomic elements, fill container for layout cells - check visual alignment after build
• Naming: follow existing DS file naming conventions (check adjacent components before inventing)

4. Task router - 3-tier access

Pick the cheapest path for your task. Bound context cost: TIER 0 query ≤500 tokens; TIER 1 file ≤500 lines; TIER 2 file ≤300 lines (most), 1000+ for icons/emoji collections only.

TIER 0 - CLI precise lookup (~50-500 tokens output)

For “I need exactly one thing” - no file load needed.

DS V2 (UI building blocks):

python3 ../figma-ai/tools/lookup.py component "Button"           # → top matches w/ key + page slug
python3 ../figma-ai/tools/lookup.py components --page button     # → all components on a page
python3 ../figma-ai/tools/lookup.py variants "Modal footer"      # → full variant property schema
python3 ../figma-ai/tools/lookup.py variable text-color/danger-primary
python3 ../figma-ai/tools/lookup.py variables --family danger --property text
python3 ../figma-ai/tools/lookup.py search alert                 # → fuzzy across components + variables

Organizer Kit (canvas meta - arrange designs, flow arrows, notes):

python3 ../figma-ai/tools/lookup.py organizer "Design area"        # → find canvas-layout component
python3 ../figma-ai/tools/lookup.py organizer-list design-area     # → list category (design-area / arrows / design-notes / etc.)

TIER 1 - Always-on small files (load every Figma session, ~20K tokens total)

Task	File
Match task to variable name	../figma-ai/variable-selection.md (intent → variable decision tree)
Apply 4-category rule	../figma-ai/naming-convention.md §1
Pick intensity (dim/soft/primary/secondary)	../figma-ai/naming-convention.md §3
Run a workflow (bind / extract / mode-audit / DELETED-cleanup / instantiate)	../figma-ai/workflows.md (5 runbooks)
Cross-cutting design philosophy + slop register	../ds-guideline/DIRECTION.md
Anti-pattern check (Figma + universal)	../anti-pattern-registry.md (esp. figma-naming-6-binding)

TIER 2 - Section-grep (load relevant section only)

Task	File + section
Variable hex / TW equivalent	../figma-ai/variable-registry.md (grep ^### §1.1 \text-color/*“ etc.)
Variable Figma ID + collection + mode	../figma-ai/variable-id-map.md (grep ^## General Color System etc.)
Color philosophy (WHY)	../ds-guideline/color.md
Typography philosophy	../ds-guideline/typography.md
Spacing rationale	../ds-guideline/spacing.md
Radius / shadow rationale	../ds-guideline/{radius,shadow}.md

TIER 3 - Component detail files (load on-demand for variant schemas)

DS V2 (UI building):

Task	File
Browse all DS pages + key preview	../figma-ai/component-registry.md (slim index, ~250 lines)
Full variant schema for ONE category	../figma-ai/components/<page-slug>.md (e.g., button.md, input.md, modal.md)
Re-sync after DS changes	../figma-ai/tools/resync-figma.md

Organizer Kit (canvas arrangement - R19):

Task	File
User says “arrange designs” / “add notes to canvas” / “annotate flow”	../figma-ai/organizer/usage-patterns.md (CRITICAL - layout rules, level hierarchy, anti-patterns)
Browse all organizer categories	../figma-ai/organizer/component-registry.md (slim index, ~140 lines)
Full variant schema for a category	../figma-ai/organizer/components/<category>.md (design-area / design-notes / arrows / etc.)
Folder overview	../figma-ai/organizer/README.md

Specialized - sessional

Task	File
Variant property workflow	../../../ai-memory/lessons/figma-variant-component-workflow.md
Figma MCP perf issues	../../../ai-memory/lessons/figma-execute-performance-patterns.md
Async page/node loading	../../../ai-memory/lessons/figma-dynamic-page-async-apis.md
API identifier confusion	../../../ai-memory/lessons/figma-plugin-api-identifier-model.md
Screenshot workflow	../../../ai-memory/lessons/figma-screenshot-hygiene.md
MCP bridge connection broken	../operations/ (human ops, not AI)
Token math (hex, alpha, L*)	../../docs/{color-system-rules,alpha-decomposition-spec}.md
KID tokens	../kid/Design System Guideline/KID_DS_Basic_Guideline.md
Task not covered	../figma-ai/README.md + grep ai-memory/lessons/figma-*.md

Common composite tasks

Scenario	Path (cheapest first)
Build a new Button component (UI)	TIER 1 (selection §4.2 + naming + workflows W5) → TIER 0 lookup.py components --page button → TIER 3 components/button.md only if need variants
Bind a danger color	TIER 0 lookup.py variable text-color/danger-primary → TIER 1 (workflows W1)
Audit slop in existing component	TIER 1 (anti-pattern + DIRECTION §10) → TIER 0 lookup.py variants <name> for inspection
Pick typography for heading	TIER 1 (selection §5) → TIER 2 variable-registry.md §3 Typography
Build card with elevation	TIER 1 (selection §4.5 + §8) → TIER 2 ../ds-guideline/shadow.md for tier rationale
Arrange designs on Figma canvas (R19)	TIER 1 ../figma-ai/organizer/usage-patterns.md (layout rules) → TIER 0 lookup.py organizer "Design area" → TIER 3 ../figma-ai/organizer/components/design-area.md
Connect screens with flow arrows	TIER 1 ../figma-ai/organizer/usage-patterns.md §3 → TIER 0 lookup.py organizer-list arrows for arrow-type choice
Add dev note alongside design	TIER 1 ../figma-ai/organizer/usage-patterns.md §4 (Box Style 1/2 + Color semantic table) → TIER 0 lookup.py organizer "Design note"
Review feature flow stage coverage (sessional)	TIER 1 ../../ai-memory/lessons/figma-feature-flow-analysis-workflow.md (Workflow 7 draft - inventory frames → detect type → coverage check → report missing)

5. Self-check before declaring done

[!important] Run this checklist before saying “done.” Skipping it is the most common cause of regressions.

Token binding

• No hardcoded hex in fills where DS token exists?
• fill/* used for backgrounds (not text-color/*)?
• icon-color/* used for icon vectors (not text-color/*)?
• border-color/* used for strokes?
• All boundVariables resolved to actual DS tokens (no DELETED_*)?

Naming convention

• Semantic role names only (info/warning/success/danger/brand - no feature names)?
• Correct intensity modifier for state (dim default / soft hover / primary emphasis / secondary focus)?
• Focus ring uses global border-color/progress-secondary?

Workflow

• Extracted boundVariables from reference before building (if applicable)?
• Hex fallback documented as intentional workaround (if used)?
• Auto-layout hug vs fill correct for visual hierarchy?
• Component naming follows existing DS file convention?

Mode awareness

• GM mode unless KID task? (Don’t mix tokens across modes)

5.1 Quantified gates (per-component counting - AI must answer with integer)

DEFEND each metric. If any fails → revisit ../figma-ai/naming-convention.md + figma-naming-6-binding anti-pattern rows.

#	Metric	Target	Catches	Source
F1	Hardcoded hex fills per component (DS-Token match exists)	0	figma-naming-6-binding#01 hex fallback drift	DS-Token integrity
F2	text-color/* applied to icon-type nodes	0	figma-naming-6-binding#02 category mismatch	Figma 4-category rule
F3	Feature-named tokens inside component	0	figma-naming-6-binding#03 coupling to feature	Semantic naming rule
F4	Distinct focus-ring border-color tokens across component set	1 (globally)	figma-naming-6-binding#04 per-component drift	A11y consistency
F5	Invented intensity modifiers (not in canonical list)	0	figma-naming-6-binding#05 orphan token	DS-Token governance
F6	Mixed-mode tokens (GM + KM in same component)	0 (pick one context)	Mode leak	§3 context defaults
F7	DELETED_* boundVariables unresolved	0	Stale binding from refactored source	Binding hygiene

5.2 Anti-pattern scope scan (pre-ship)

Before shipping any Figma component work, verify no match against these scopes:

Task	Required scope check
Token binding (any component)	figma-naming-6-binding
Visual design (component composition)	Cross-lane: direction-10-ai-slop-universal (slop-01..slop-10 apply to Figma visual work too) + relevant DIRECTION §10 sub-table
Color role selection	direction-10-color-brand
Component hierarchy / layout	direction-10-layout + direction-10-spacing-depth

Cite specific row when explaining a token decision: e.g., “Rejected per figma-naming-6-binding#03, using text-color/info-primary instead of proposed cause-text”.

Single-file lookup for all 151 anti-pattern rows across 26 scopes: → DOL-DS-token/design-guideline/anti-pattern-registry.md (auto-generated; scan before shipping)

6. Sessional fallback

When task not covered in §4 Router:

1. Grep sessional lessons: ai-memory/lessons/figma-*.md for keyword matching your task
2. Read skill draft: ai-memory/skill-drafts/ (if exists - check for Figma-related draft skill)
3. Ask user: if still unclear, better to ask than guess - Figma changes are expensive to undo

Current sessional lessons (incremental promotion candidates):

• Skill draft: check ai-memory/skill-drafts/ for current DOL Figma skill
• 8 lessons at ai-memory/lessons/figma-*.md + dol-figma-semantic-token-naming.md
• Session-brief: ai-memory/session-brief.md (run-state, open risks, next-best actions)

7. Promotion gate (for AI: what to flag)

If during your task you observe a rule/pattern that:

• Worked consistently across this session + prior
• Not yet in canonical (../figma-ai/*.md)
• Stable enough for cross-session use

→ Flag in friction-log (../../../ai-memory/queue/skill-friction-dol-figma.md) for promotion consideration at next /reflect. Don’t auto-promote; human review gate.

File tree - scope map

✅ IN SCOPE (Figma AI tasks)

File	Purpose
../figma-ai/README.md	Folder index + scope boundary
../figma-ai/naming-convention.md	Canonical 4-category semantic token naming + 5 binding anti-patterns
../figma-ai/variable-registry.md	Auto-gen registry - all 838 AI-facing DS variables (semantic + component + typography + spacing + radius + shadow) with resolved values, TW equivalent, dark variants
../figma-ai/variable-id-map.md (R17)	Auto-gen ID map - variable name ↔ Figma ID + collection ID + mode IDs (for direct binding without runtime name lookup)
../figma-ai/component-registry.md + ../figma-ai/components/*.md (R17+R18)	Auto-gen component catalog - 532 component sets + 2,653 standalone split into 44 per-page detail files (with slim INDEX at top), extracted from live DS file
../figma-ai/variable-selection.md	Intent → variable decision tree - 10 common design tasks → direct variable names
../figma-ai/workflows.md	5 operational runbooks - bind / extract / mode-audit / DELETED-cleanup / instantiate
../figma-ai/tools/resync-figma.md	Re-extraction runbook (how to refresh id-map + component-registry when DS changes)
../anti-pattern-registry.md	figma-naming-6-binding scope (5 rules) + all other DOL anti-patterns (cross-lane)
../../docs/tailwind-color-guideline.md	Deep token reference (code-side mapping)
../../docs/color-system-rules.md	Token math rules (when derivation needed)
../../docs/alpha-decomposition-spec.md	Alpha math (when deriving new tokens)
../../../ai-memory/lessons/figma-*.md	Sessional operational knowledge (specialized workflows)
../../../ai-memory/lessons/dol-figma-semantic-token-naming.md	Source record (promoted to naming-convention.md)
../../../ai-memory/queue/skill-friction-dol-figma.md	Active capture point for in-session Figma observations (promotion gate input)

❌ OUT OF SCOPE (don’t read for Figma AI)

File	Why
../ui-style-guide/*	Code-facing Tailwind recipes, not Figma
../operations/	Human ops runbook, not AI doing design
../../design-system-report/*	Historical reports
../ai-entry/CODE-UI.md	Code UI task entry (wrong domain)

Related entries

• README.md - folder index
• CODE-UI.md - parallel entry for code UI tasks (different domain)