@design-parity/adapter-figma

The Figma ReferenceAdapter. Figma is the keystone source — the only one with a machine-resolvable design↔code link (Code Connect). This adapter uses the REST API + Code Connect, never the Dev Mode MCP server (that is local/desktop-session oriented and wrong for a hosted bot).

What it does

resolve(componentId, ref, ctx):

1. Resolve the node. If ref is a handle (figma:<fileKey>/<nodeId> or a figma.com URL) it's parsed directly. Otherwise the adapter reads the repo's Code Connect output (figma.code-connect.json, or FIGMA_CODE_CONNECT_FILE) to map the component to a node.
2. Fetch structure — GET /v1/files/:key/nodes (padding, corner radius, fills, text style).
3. Fetch variables — GET /v1/files/:key/variables/local, mapping collection modes (Light/Dark) to themed colors. Degrades gracefully to structure-only tokens when variables aren't entitled.
4. Render the reference image(s) — GET /v1/images, downloaded and written under outDir.
5. Normalize to a DesignReference with linkMethod: "code-connect", including layout — the node tree's absoluteBoundingBoxes flattened to a SemanticTree (root-relative dp, frame on the root) so the structural layout diff can compare element placement. Text nodes are labelled by their visible characters, which is what matches a candidate's semantics label; other nodes fall back to their Figma layer name and so generally go unmatched until layer naming is reconciled. Absent when the node carries no bounding box.

Auth

Reads credentials from AdapterContext.env:

• FIGMA_OAUTH_TOKEN → Authorization: Bearer (preferred), or
• FIGMA_TOKEN / FIGMA_PAT / FIGMA_ACCESS_TOKEN → X-Figma-Token.

Missing credentials, 401/403, 429 (rate limit, with Retry-After), and a missing node each raise a typed FigmaError subclass.

Usage

import { createFigmaAdapter } from "@design-parity/adapter-figma";

const adapter = createFigmaAdapter({
  // optionally render one image per theme from separate frames
  resolveTargets: (ref) => [
    { nodeId: ref.nodeId, theme: "light", size: "compact" },
    { nodeId: "1:43", theme: "dark", size: "compact" },
  ],
});

const reference = await adapter.resolve(
  "ui/Button.kt#PrimaryButton",
  "figma:AbCdEf123456/1:42",
  { repoRoot: process.cwd(), env: process.env },
);

Network is injectable (fetch) and the client is mockable, so unit tests run fully offline (see test/).

Theming note

Figma's image render uses a node's default variable mode; the REST API can't switch modes per render. So themed tokens come from variables (all modes), while themed images come from rendering separate per-theme frames via resolveTargets.