---
name: figma
description: Read and analyze Figma files via the pi-figma extension. Use when the user references a Figma URL, asks about designs, frames, components, design tokens, or UX copy. Teaches the cost-aware tool ordering needed to stay under context budget.
---

# Using pi-figma

You have access to four Figma tools via the `pi-figma` extension. Their names match Figma's own vocabulary (Map, Inspect, Copy, Tokens). They are **ordered by cost** — always prefer the cheapest one that can answer the question.

## Cost-ordered tool map

1. **`figma_copy(file, nodeId?)`** — flat list of UX text (written copy). Cheapest. Use for copy audits, i18n extraction, proofreading, "what does this screen say". Not related to clipboard copy.

2. **`figma_tokens(file)`** — registered design-system Styles (color/text/effect/grid). Use for DS audits, "is this token named correctly", naming-convention checks. Returns names only in v1 — not resolved hex values.
   - **Known limitation:** modern files often use Figma **Variables** instead of Styles; v1 does not read Variables yet. If `figma_tokens` returns zero counts, the file likely uses Variables — fall back to `figma_inspect` on a consuming node and read its `fill`/`textStyle`.

3. **`figma_map(file, depth=3)`** — page/frame structure (id + name + type). The **entry point** whenever you don't already know node ids. Never skip to `figma_inspect` without mapping first unless the user handed you a node id directly.

4. **`figma_inspect(file, nodeIds, depth=3)`** — Dev Mode-style compact dump of one or more frames: layout, fills, text, component references. Use after `figma_map` has revealed the id you want. Start with `depth=3`; increase only if output shows `truncatedChildren`.

## Accepted inputs

- **File**: a raw key (`abc123XYZ`) OR any Figma URL (`figma.com/file/...`, `figma.com/design/...`).
- **Node IDs**: `1:234` (API form), `1-234` (URL form), or a full URL with `?node-id=` — all parsed automatically.

## Discipline rules

- **Never dump the full file.** There is no tool for that on purpose. For depth, use `figma_inspect` on the smallest node that contains what you need.
- **Read `truncatedChildren`.** If an inspect result shows `truncatedChildren: 47`, that's 47 descendants you didn't see. Either drill in with a child's `nodeId` or raise `depth` — don't guess.
- **Cache is version-aware.** Repeat calls in one turn are nearly free. Don't hesitate to call `figma_map` before every `figma_inspect` session.
- **Color values live on nodes, not tokens.** `figma_tokens` gives style *names* only. To resolve a hex, `figma_inspect` a node using that style and read `fill`.

## Typical workflows

- **"Convert this frame to SFRA ISML"**
  → `figma_map` → identify frame id → `figma_inspect(file, [id], depth=5)` → generate ISML from the compact tree.

- **"Audit copy for typos"**
  → `figma_copy(file)` → scan the flat list.

- **"What design tokens exist?"**
  → `figma_tokens(file)`.

- **"Does this component match the DS?"**
  → `figma_tokens(file)` for DS context → `figma_inspect(file, [instanceId])` to read the actual fills → compare.

## Auth setup

Extension reads `FIGMA_PAT` env var, or `~/.pi-figma/config.json` with `{"pat":"figd_..."}`. If no token is configured, the tool call fails with an actionable message.