| name | gdd-figma-extract |
| description | Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context. |
gdd-figma-extract
Pull a whole Figma design system into a compact, queryable local digest - without the raw JSON ever entering Claude context. The heavy lifting runs in tested .cjs tools; the model reads only the digest outputs.
Usage
/gdd:figma-extract <file-key-or-url> # full design-system digest
/gdd:figma-extract <file-key-or-url> --component Button # ~500-token single-component slice
<file-key-or-url> is a Figma file URL (https://www.figma.com/file/<key>/… or /design/<key>/…) or a bare file key.
Behavior
-
Preflight (D-10). Confirm FIGMA_TOKEN is set in the environment:
node -e "process.exit(process.env.FIGMA_TOKEN||process.env.FIGMA_PERSONAL_ACCESS_TOKEN?0:1)"
If unset, tell the user to export FIGMA_TOKEN=figd_… (from https://www.figma.com/developers/api#access-tokens). The token comes from the environment only - never ask the user to paste it into a file or the chat, and never echo it back.
-
Stage 1 - pull. Pull the file's REST endpoints into the gitignored raw cache (D-09):
node scripts/lib/figma-extract/pull.cjs "<file-key-or-url>"
This caches to .figma-extract-cache/raw/<file-key>/ and skips re-pulling when Figma's version is unchanged (D-11). Add --force to bypass the cache, --out <dir> to relocate the cache. The tool prints a JSON summary (endpoints, bytes, cached) on stdout - the raw bodies stay on disk.
-
Stage 2 - plugin sync (OPTIONAL, Path C). Only when the design tokens live in Figma Variables that the REST API cannot return (non-Enterprise plans → the pull summary shows variables skipped) and the user wants token coverage:
node scripts/lib/figma-extract/receiver.cjs --out .figma-extract-cache/raw/<file-key>
This binds 127.0.0.1:5179 (D-06). Tell the user to run the dev-installed "GDD Sync" plugin in Figma and click "Export to GDD" - see figma-plugin/README.md for the one-time dev-install. The receiver writes variables.json into the cache and exits on receipt or timeout. Skip this stage entirely for design systems whose tokens already come through the REST pull.
-
Stage 3 - digest. Transform the cache into the compact digest:
node scripts/lib/figma-extract/digest.cjs --raw .figma-extract-cache/raw/<file-key> --out .figma-extract-cache/digest
This writes DESIGN.md, tokens.json, and components.json. Add --prefer-styles to invert the token priority to styles-first (D-04). Add --component <name> (D-08) to emit a single-component slice instead of the full digest.
-
Read the digest. Open only .figma-extract-cache/digest/DESIGN.md (plus tokens.json / components.json when you need structured data). For a single component, pass --component <name> in Stage 3 and read the ~500-token slice instead of the full ~16K-token spec.
Required Reading
.figma-extract-cache/digest/DESIGN.md - the compact human/LLM-readable spec.figma-extract-cache/digest/tokens.json - resolved design tokens (when structured token data is needed).figma-extract-cache/digest/components.json - components with variants/props/defaults (when structured component data is needed)
Notes
- Two-stage pipeline (D-01): re-run Stage 3 against an existing cache without re-pulling. The digest does zero network calls.
- The spike proved 0 Claude tokens during extraction (898× compression, 223 MB → 254 KB). That property holds only because this skill never surfaces the raw cache.
- Figma MCP remains the right tool for spot questions on a single live component; this skill is the cheaper path for whole-design-system workflows.
Do Not
- Do NOT read or
cat the raw/*.json cache (e.g. .figma-extract-cache/raw/<file-key>/file.json). It is tool-internal and often 100+ MB; loading it into context defeats the off-context guarantee (D-12). Read only the digest outputs above.
- Do not persist, log, echo, or print
FIGMA_TOKEN (D-10). It belongs in the environment only - never write it to a file, a commit, or chat output.
FIGMA-EXTRACT COMPLETE
