# Figma > Query Figma files via REST API. Use when the user pastes a figma.com URL or mentions Figma files, frames, nodes, components, variables, or design-system tokens (colors, spacing, typography). - Skill: `rahlir/figma` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add rahlir/figma` - Raw SKILL.md: https://api.skillmd.com/api/skills/rahlir/figma/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: Rahlir (https://skillmd.com/u/rahlir) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/rahlir/figma --- # Figma Use this skill to pull design context from Figma into implementation work. The common case is grounding code in the design: comparing implementation against a wireframe, applying the correct brand colors and spacing, or checking how a component should look. Less commonly, the user asks for a specific data lookup like "what value is the variable X". Either way, the user supplies a figma.com URL; fetch what's needed via `./figma.mjs` and apply it. All operations are read-only. ## Required setup **Run this check first:** ```bash test -n "$FIGMA_TOKEN" && ./figma.mjs me ``` - If both succeed, the token is valid and the helper works. - If `FIGMA_TOKEN` is unset, stop and tell the user to add it to `~/.profile` or `~/.zprofile`. Personal access token from https://www.figma.com/settings → Security. Scopes: `files:read`, plus `file_variables:read` for Enterprise design tokens. - Do not export the token or edit shell profiles yourself. ## Before any operation 1. **Find or ask for a reference.** Look for a `figma.com/file/...` or `figma.com/design/...` URL in the user's message or the conversation. - URL present → parse and use directly. The helper extracts the file key and, if present, the `node-id` (URL form `12-345` becomes API form `12:345`). - No URL → ask the user for a file URL. Do not guess keys or ids; there is no API for finding files by name. 2. **Identify the intent.** Match to a task pattern below before running anything. If ambiguous, run `info` first to orient, or ask the user. 3. **Avoid redundant fetches.** If you already have the JSON from a previous call in the same turn, answer from it instead of refetching. ## Task patterns ### 1. Orient in a file **Triggers:** "what's in this file", "show me the pages", "give me an overview", URL with no `node-id=` **Command:** ```bash ./figma.mjs info ``` Returns file metadata and the page list with child counts. Use as the entry point when you have the file key but do not yet know which page or frame to drill into. ### 2. Inspect a specific frame, layer, or component **Triggers:** URL containing `node-id=`, "this frame", "this layer", "what's inside " **Commands:** ```bash ./figma.mjs node [--depth N] ./figma.mjs node [--depth N] ``` Default depth is 2 (node + children + grandchildren). Raise `--depth` rather than chaining calls when going deeper. ### 3. Read design tokens **Triggers:** "design tokens", "system colors", "spacing scale", "typography tokens", "what variables are defined" **Command:** ```bash ./figma.mjs vars [--collection NAME] ``` Returns variables grouped by collection and mode. If the response is empty (the file has no variables defined), fall back to `styles` (see task 4) for the legacy pre-variables system. A `403` is a different case: token or plan is missing `file_variables:read`; see Errors below. ### 4. List components or styles **Triggers:** "what components exist", "component list", "what styles are defined", "design-system inventory" **Commands:** ```bash ./figma.mjs components # named components + component sets ./figma.mjs styles # color, text, effect, grid styles ``` For internals of a specific component, follow up with `node `. ### 5. Render a frame visually **Triggers:** "show me", "what does it look like", "render this", "preview" **Steps:** 1. Render and download: ```bash ./figma.mjs image [--format png|svg|pdf] [--scale 1|2|3] ``` 2. The script prints the saved path under `/tmp/pi-figma-skill/`. 3. Use the `read` tool on that path to view the image. Default is PNG at scale 1. Use SVG for vector assets you intend to reuse, PNG `--scale 2` for high-detail visual review. ### 6. Drill from file to page to frame When the user asks about a region you have not seen yet: 1. `info ` to list pages. 2. `node ` to list the page's top-level frames. 3. `node --depth 3` to inspect the frame. Reuse the parsed `` across steps; do not re-extract it from the URL each time. ## Disambiguation - **"Design system colors / spacing / typography"** → `vars` first (modern), `styles` second (legacy). - **"Component X"** → metadata: `components`. Internal structure: `node `. Picture: `image`. - **"Show me X"** → visual frame: `image`. Data (tokens, components, structure): the matching data command. - **URL with no clear intent** → `info`, then ask the user what they want from it. ## Output handling - Markdown output is hard-capped at ~200 lines. For full payloads (`jq`, programmatic use), add `--json`. - Hidden variables (`hiddenFromPublishing`) are returned and tagged `(hidden)` so you can mention or filter them as needed. - Summarize before dumping. Do not paste 200 lines of variable tables when the user asked for one color value. ## Errors that mean "stop" - `403` on `vars` → token lacks `file_variables:read` (Enterprise feature). Tell the user; do not retry the same call. - `404` on `node` → wrong id or wrong file key. Recheck the URL parse; do not guess at id variants. - `401` → token is invalid or expired. Tell the user to regenerate; do not retry. - `FIGMA_TOKEN env var not set` → setup incomplete. Point at the Setup section; do not export it yourself. ## NEVER - **NEVER write to Figma.** This skill is read-only by design. Do not compose REST calls outside `figma.mjs`. - **NEVER guess a file key or node id.** Parse from URLs or ask the user. - **NEVER export `FIGMA_TOKEN` or edit the user's shell profile** without explicit permission. - **NEVER refetch data already in scope** for the current turn. - **NEVER use this skill for codegen** (frame → React/Tailwind/etc). Tell the user to use Figma Dev Mode's built-in "copy as code". ## Out of scope Codegen, canvas writes, cross-file search, file discovery by name (no such API exists), comments, Code Connect mappings. Use Figma desktop or Dev Mode for those.