feat: /understand-figma — Figma design knowledge graph (foundation)

[smjeong84]

Why this feature?

Understand Anything already turns code (/understand), wikis (/understand-knowledge), and business domains (/understand-domain) into interactive knowledge graphs. But a huge part of how a product actually works lives in Figma — screens, component libraries, design tokens, and (for many teams) written product/spec notes kept right inside the file. Today that knowledge is invisible to the tool, so the picture of a product stops at the code boundary.

/understand-figma extends the same "analyze anything → navigable graph" idea to Figma so a newcomer can see how a product's screens, design system, and components fit together — the design-side analogue of the architecture graph /understand builds for code.

Why it's needed (use cases):

• Onboarding — a new designer/PM/engineer explores the product's screens + design system as a graph instead of scrolling an unfamiliar Figma file.
• Design-system insight — see components, their variants (component sets), and which design tokens each one uses.
• A foundation for bigger wins (deferred to follow-ups): user-flow graphs from prototype links, design ↔ code mapping, design-system audits (detached instances / inconsistencies), and analysis of product specs written inside Figma.

This PR delivers the foundation only (see Scope below); the higher-value capabilities are designed for but intentionally deferred so this lands as a reviewable, self-contained unit.

What it does

/understand-figma <figma-url-or-key>:

1. fetches the Figma document via the REST API,
2. deterministically parses it into a structural graph (pages → screens → components / component sets / instances) plus a light design-system model (design tokens + uses_token links),
3. runs an LLM design-analyzer agent to add summaries / tags / screen-purpose,
4. assembles the same knowledge-graph.json the rest of the tool uses, tagged kind:"design",
5. auto-opens the existing dashboard, which renders the design graph (per-page + "Design System" layers, design-system-first tour) with a thumbnail preview of the selected screen in the sidebar.

How it's used

Prereqs: Node ≥ 22, pnpm ≥ 10, and a Figma personal access token in the environment.

export FIGMA_TOKEN=<your token>        # create at https://www.figma.com/settings
/understand-figma https://www.figma.com/file/<KEY>/<name>
# bare key:           /understand-figma <KEY>
# scope to one page:  /understand-figma <KEY> --page "Onboarding"
# localized output:   /understand-figma <KEY> --language ko
# force re-analyze:    UNDERSTAND_FIGMA_FORCE=1 /understand-figma <KEY>

Re-running is incremental: if the Figma file version is unchanged it prints UP_TO_DATE and skips.

Design & architecture (how it fits the codebase)

Mirrors the existing "new analysis mode" pattern (/understand-knowledge, /understand-domain): deterministic structural parsing lives in core, the LLM does semantics, and the same schema / persistence / dashboard are reused.

• New, isolated: packages/core/src/figma/ (Node-only) — source/ (FigmaSource adapter seam + FigmaApiSource), parse/ (parse-document, tokens), merge.ts, barrel index.ts; the design-analyzer agent; the /understand-figma skill + figma-scan.mjs / figma-merge.mjs.
• The Figma API client sits behind a FigmaSource interface, so an offline local-JSON source can be added later with no rework — and it is deliberately kept out of the dashboard's browser-safe subpath exports.
• Reused: schema/validation, persistence, the dashboard framework, the subagent + intermediate-file orchestration, and /understand-dashboard auto-launch.

Schema additions (additive, backward-compatible)

• NodeTypes (+6): page, screen, component, componentSet, instance, token.
• EdgeTypes (+3): instance_of, variant_of, uses_token (instance_of promoted from an alias to a first-class edge).
• FigmaMeta (passthrough, alongside domainMeta / knowledgeMeta): fileKey, nodeId, thumbnailUrl, dimensions, tokenKind, plus forward-looking prototypeTargets / componentKey (recorded now so the deferred flow/code-mapping work needs no re-parse).
• kind:"design" added to the graph union. Existing graphs (no kind → codebase) are unaffected.

Verification

• pnpm --filter @understand-anything/core test → 760 passing (incl. new figma suites: api-source, parse-document, tokens, merge, + a schema regression test).
• pnpm --filter @understand-anything/dashboard test → 47 passing (incl. a guard test that fails if a design node type is ever dropped from the dashboard's visible-types set).
• pnpm --filter @understand-anything/core build and pnpm --filter @understand-anything/dashboard build → green.
• pnpm lint (eslint .) → clean.
• Offline safety: figma-scan.mjs fails fast with a friendly error when FIGMA_TOKEN is unset; a test asserts the token never appears in error output.
• Not yet run here: a live end-to-end /understand-figma <url> against a real Figma file (needs a token) — recommended as the reviewer's acceptance check.

Implemented test-first (TDD) and reviewed task-by-task. The review process caught and fixed three real issues, called out for transparency:

• componentSet (the only camelCase node type) was being dropped by the schema's lowercasing sanitizer → added a componentset → componentSet normalization alias + regression test.
• A pre-existing page → article alias would have rewritten design page nodes → removed (knowledge agents emit article directly).
• The dashboard's drill-in canvas filtered out design nodes (they weren't in allVisibleTypes) → fixed and locked with the guard test above.

Security

• FIGMA_TOKEN is read from the environment only; it travels solely in the X-Figma-Token header and is never written to the graph, meta.json, logs, or intermediate files.
• This mode makes an outbound call to api.figma.com — a departure from the otherwise fully-offline pipeline. This is documented in the skill and surfaced to the user.

Scope & roadmap

This PR is the foundation (ingestion + structure + light design-system model). Deferred to their own spec → plan → PR cycles (designed for, not built here):

• B — user flows (prototype links → navigates_to + flow view)
• C — design ↔ code mapping (figmaMeta.componentKey ↔ the code graph)
• D — design-system audit (reuse rate, detached instances, inconsistencies)
• E — analysis of product/spec text written inside Figma (→ claim/entity nodes)

Docs

• Design spec: docs/superpowers/specs/2026-06-24-understand-figma-foundation-design.md (+ Korean …-design.ko.md)
• Implementation plan (15 TDD tasks): docs/superpowers/plans/2026-06-24-understand-figma-foundation.md

Notes for reviewers

• 17 commits, conventional-commit style, each task committed separately for easy review.
• Built/verified locally on Node v20 (repo targets ≥ 22); all builds/tests/lint green regardless, but please run the live e2e on ≥ 22 with a real token.
• A dedicated "design" dashboard view + legend category was intentionally deferred; v1 reuses the structural hierarchical view (design nodes group under the existing "code" filter and render via that view).