Figma design integration — build UIs that match referenced designs (interactive-once auth)

[tzone85]

Summary

Requirements can now reference figma.com design URLs and vxd builds the UI to match the referenced frames instead of inventing a design.

The auth contract (communicated, not hidden)

Figma needs an operator credential, so the first Figma-referencing run is interactive-once rather than fire-and-forget — and vxd says so everywhere it matters:

• vxd req detects design URLs and fails fast before any LLM spend when no credential exists, with the message naming the exact interactive step.
• vxd figma auth is the one-time session: prints the Figma settings URL (never auto-opens a browser), reads the personal access token, validates it via /v1/me before storing (a typo fails in the session, not mid-pipeline hours later), and persists it at <state_dir>/figma.token mode 0600. FIGMA_TOKEN env is also honored.
• After that single session, Figma runs are fire-and-forget like every other vxd run — vxd figma status shows the authenticated account.

Pipeline flow

1. Pull (figma.BuildDesignContext): referenced nodes fetched at depth 3 + 2x PNG renders into <repo>/.vxd-design/ — a DESIGN_CONTEXT.md frame inventory (dimensions, text styles, solid fills as hex) plus the rendered images. Per-ref failures degrade to a note; all-refs-failed is a loud req-time error, never a hollow success.
2. Plan: the context rides in the decomposition prompt inside <design-reference> data tags, instructing the Tech Lead to derive the design-token foundation from the design.
3. Implement: frontend stories get the context in their goal prompt (after FrontendDesignBrief — the reference overrides generic design guidance) and the PNGs are copied into each frontend worktree so the coding agent can open them.

Safety

• Figma layer names are third-party data: loadDesignContext injection-scans the markdown (a MatchInjectionPattern hit drops the whole context loudly) and neutralises angle brackets so a layer literally named </design-reference> cannot close the data framing. 16 KB cap.
• Render downloads validate the destination host (Figma CDN allowlist) — a tampered API response cannot point a download at an internal address.
• The token never appears in logs or error strings; .vxd-design/ is gitignored and stripped from story branches.

Review

everything-claude-code:go-reviewer: 1 HIGH (error-dropped os.Getwd in the pull path — pull moved after repoPath with proper handling), 2 MEDIUM (tag-close framing escape; untestable direct client construction in runReq), 1 MEDIUM (hollow all-fail success) and 3 LOW (SSRF host validation, hyphenated file keys, unreadable-token diagnostics) — all applied with pinning tests. Reviewer confirmed: token never leaks, injection-scan placement covers every content-to-prompt path, the fail-fast genuinely precedes LLM spend, lookalike domains rejected.

Test plan

• 24 new tests across internal/figma (URL/token/client/context via httptest), engine (load/injection-drop/tag-neutralisation/cap/copy + planner prompt pin), cli (auth validates-then-stores, invalid token not stored, status paths, SSRF refusals)
• make verify (pre-push green gate) passes; golangci-lint 0 issues
• Doc-coverage gates pass (CLAUDE.md section + CLI tables + README bullet)
• NXD: intentionally not ported — Figma is a cloud API; NXD stays offline-first