figma-token-review

figma-token-review

Before starting: Check whether Figma MCP is connected (see §Prerequisites below). If the connection fails, stop immediately.

Extract which element used which vapor token from the Figma mockup, and verify whether that usage is appropriate. Verification is divided into two kinds with different confidence levels — this separation is the core of this skill.

• Determinism (legality): If the input is the same, the answer is the same. Code (scripts/evaluate.mjs·typography-evaluate.mjs) computes it.
• Semantic judgment (semantic fitness): Fitness in light of context. You (the agent) judge using the vapor schema as a rubric.

4 verification axes

축	Determinism (code)	Semantic judgment (LLM)
1. raw/binding	boundVariables Empty object = raw (unbound) → high	—
2. semantic meaning	do-not-use / missing schema key (typo·unregistered) / role mismatch → high	Fitness of when·avoid in light of context (e.g. misuse of danger↔success)
3. typography hierarchy	Text Style unbound (appliedStatus==='raw') → high	misuse of heading in body text, inverted hierarchy (compared against the 16-level hierarchy)
4. background-foreground pairing	foreground gradeRules: fg-100 on a non-pure-white background → high, ambiguous background → info	Cases where background identification is ambiguous

The WCAG contrast ratio is not computed. The 4 axes only look at the 3-way classification of whether the foreground token's background is pure white (#ffffff)/transparent/other (gradeRules.100/200). oklch→sRGB conversion, rounding, and effective color compositing are out of scope. For limitations, see references/limitations.md .

Prerequisites: Check Figma MCP connection

This skill depends on the Figma Plugin API (use_figma, /figma-use preloaded) and the MCP read tool (get_metadata, get_screenshot). First, get_metadatacall lightly once to check the connection. If it fails, guide with "Figma MCP is not connected. Please try again after connecting." and stop.

Input parsing

• /figma-token-review {Figma URL} form. From the URL, fileKey, nodeId extract.
  • node-id의 -를 :Convert to (e.g. 32842-2107 → 32842:2107).
• Verification mode (optional): If "colors only"/"typography only"/"fonts only" is specified, only that mode. If not specified, 둘 다.
• Intent (optional): The natural language after the URL is the designer's intent (e.g. "I was trying to emphasize the selected tab").
  • Intent present → Judge token fitness based on that intent (more accurate).
  • No intent → Infer the role from the screenshot + nodes. Do not ask back, proceed, but state "No intent provided → role inference (low confidence)" in the report header.

Execution order (4 steps)

Extract color and typography together in a single tree traversal, then evaluate with their respective deterministic scripts.

1. Unified extraction (fixed script) — /figma-useAfter loading scripts/extract.figma.js, Read ROOT_ID·MODE(both/color/typography) only, and pass it as-is to use_figmain read-only mode. Do not rewrite the logic on the fly — rewrite drift is the biggest threat to accuracy (when a defect is found, fix the file itself). The script extracts both color (tracing aliases all the way back) and typography (getStyledTextSegments classification) and returns { colors, typography, schemaMode, viewport, stats }in grouped (nodeIds/count) form.

   • Save the returned object to a file with Write(e.g., /tmp/token-review-extract.json) — the two scripts in step 2 read the same file.
   • Details: references/extraction.md.

2. Deterministic check — pass the extracted file as an argument to each script.

   • Color: node scripts/evaluate.mjs <추출파일> → raw/do-not-use/missing key/role mismatch/fg pair violation. The CLI reads schemaMode(light/dark) and judges with the matching schema.
   • typography: node scripts/typography-evaluate.mjs <추출파일> → appliedStatus==='raw'만 high.

3. Semantic judgment (LLM) — judge based on the rubricof the two script outputs (the $description/when/avoid subset of tokens/Text Styles actually used in the input). Do not Read the entire schema file. The three-part judgment input bundle and output format are in references/evaluation-and-output.md.

4. Terminal output — output color and typography violations in separate sections. For the conformance rate, consolidate the weighted aggregate value of evaluate summary. For each semantic judgment, attach PASS/FAIL + confidence + rationale. Mark low confidence as "needs review".

Screenshot branch: get_screenshothas a large token cost. Call it only (a) in typography mode (hierarchy inference required), or (b) when role reverse-inference is needed because no intent was provided.

Bundle composition

figma-token-review/
├── SKILL.md
├── references/
│   ├── extraction.md             # 1단: alias 끝까지 해석 / 배경 식별 / 추출 출력 형식
│   ├── evaluation-and-output.md  # 2~4단: 결정론 검사 / LLM 판정 3종 입력 / 출력 템플릿
│   └── limitations.md            # 한계(정직성 기록)
├── assets/                       # rubric SSOT. 운영 시 GitHub CDN, 개발/번들은 이 6파일
│   ├── semantic-color.{light,dark}.json   # 의미 검증 본체(when/avoid/role/status/gradeRules)
│   ├── primitive-color.{light,dark}.json  # alias 종착(실제 색). 값 해석 시에만
│   ├── text-style.json                    # typography 16단 위계 + when/avoid
│   └── typography.json                    # text-style이 참조하는 primitive 스케일
└── scripts/
    ├── extract.figma.js          # 1단 통합 추출 고정 스크립트 (use_figma용 — ROOT_ID/MODE만 치환)
    ├── schema-loader.mjs         # 6파일 로딩(mode 선택) + 중첩 트리 평탄화 + gradeRules 상속
    ├── evaluate.mjs              # 색상 결정론 (4축) + rubric 서브셋
    ├── evaluate.test.mjs
    ├── typography-evaluate.mjs   # typography 결정론 (raw=high) + 위계 rubric
    └── typography-evaluate.test.mjs

No version management. Keep only one "current" schema without a version suffix. Synchronization with the design token set is guaranteed by operational discipline, and the code does not compare or block versions. schema-loaderselects the schemaModefor extraction and picks the light/dark file.

Step 1 (unified extraction) is also a bundle-fixed script. The agent substitutes only the two constants ROOT_ID·MODE and passes them to use_figma— no on-the-fly logic rewriting. The invariant principles are in the comments at the top of the script, and if a modification is needed, fix the file while honoring those principles and update the documentation and tests together.

Limitations

Points this skill cannot assert deterministically — such as deterministic limits of background identification, WCAG ratio not being calculated, no CI support, and LLM non-determinism — are honestly recorded in references/limitations.md . To avoid mistaking "not checked" for a pass, verify once before wrapping up the evaluation.