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

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.
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.
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.
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.

Using pi-figma

Cost-ordered tool map

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.

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.

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.

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.