@pi-stef/figma

Pi extension for Figma REST API tools, compact design context, and Jira-linked Figma summaries.

Use this package when implementation work starts from Figma files, frames, FigJam boards, or Jira tickets that contain Figma design links. It keeps the existing figma_context workflow while adding broader figma_* REST tools for search, summaries, assets, comments, variables, styles, and raw debugging escape hatches.

Contents

• Natural Language Usage
• Setup And Auth
• Migration From figma-context
• REST Tool Surface
• Figma Context Workflow
• Atlassian Integration
• Scopes And Permissions
• Rate Limits And Caching
• FigJam Slides And Limitations
• Troubleshooting
• Security Notes

Natural Language Usage

Ask the agent to inspect Figma links in normal task language:

pi "Summarize this Figma flow before implementing the settings page: https://www.figma.com/file/..."
pi "Use figma to inspect the checkout screen, list text content, and extract implementation hints before coding."
pi "Read Jira ABC-123 with Atlassian context and include linked Figma context if auth is configured."

Use exact tool calls when you need deterministic parameters:

figma_context url="https://www.figma.com/file/..." mode="overview"
figma_context url="https://www.figma.com/file/..." mode="screen" maxDepth=8 includeStyles=true
figma_get_implementation_context input="https://www.figma.com/design/..." maxDepth=6

Setup And Auth

figma calls the Figma REST API and needs a personal access token for private or team files. pi never creates token files automatically because they contain secrets.

Create the canonical config file:

mkdir -p ~/.pi/sf/figma
cat > ~/.pi/sf/figma/config.json <<'JSON'
{
  "apiToken": "MY_TOKEN"
}
JSON
chmod 600 ~/.pi/sf/figma/config.json

Install the package:

pi install npm:@pi-stef/figma

Use the default install for global availability, or add -l for project-local install. Use --dry-run first when you want to inspect the Pi install command:

pi install npm:@pi-stef/figma --dry-run

Check token discovery without printing the token:

figma_auth_status
figma_auth_status fileKey="abc123"

Without a fileKey, figma_auth_status only checks local config presence. With a fileKey, it makes the smallest safe Figma request needed to verify API access.

Compatibility fallbacks are supported during the first minor release after figma ships:

• { "apiKey": "..." } in ~/.pi/sf/figma/config.json
• FIGMA_API_TOKEN, FIGMA_TOKEN, or FIGMA_ACCESS_TOKEN
• compatible .mcp.json Figma token entries

New setups should use { "apiToken": "..." } in ~/.pi/sf/figma/config.json.

Migration From figma-context

figma replaces the old figma-context package and keeps the compatibility tool name figma_context.

Before enabling this package, remove the old package from both Pi scopes if it was installed:

pi remove figma-context
pi remove -l figma-context

The helper wrapper performs that cleanup when possible:

scripts/install-figma.sh project
scripts/install-figma.sh global

Do not enable both packages in the same Pi runtime. If another package registered figma_context first, this package skips duplicate registration and logs a migration warning.

REST Tool Surface

Processed tools return compact, bounded output suitable for agent context:

| Tool | Purpose | |---|---| | figma_parse_url | Parse a Figma URL, bare file key, and optional node id. | | figma_auth_status | Check local auth and optional file access without exposing tokens. | | figma_get_design_context | Return page/frame context, hierarchy, and relevant nearby nodes. | | figma_get_node_summary | Summarize layout, dimensions, styles, text, components, and children. | | figma_get_implementation_context | Produce design-to-code layout, color, typography, spacing, asset, and accessibility hints. | | figma_extract_text | Extract visible text nodes with paths and node ids. | | figma_find_nodes_by_name | Search node names with compact path-aware results. | | figma_find_nodes_by_text | Search visible text content. | | figma_render_nodes | Return Figma image render URLs and optional downloaded artifacts. | | figma_extract_assets | Build an asset manifest for renderable nodes and image fills. | | figma_get_styles | List file styles. | | figma_get_variables | List variables and collections when the token has library scopes. | | figma_get_components | List file components. | | figma_get_component_sets | List component sets. | | figma_search_components | Search components by name. | | figma_get_comments | Read file comments when the token has comment scope. | | figma_get_image_fills | Retrieve expiring image-fill URLs. |

Raw escape hatches are explicit and capped:

| Tool | Purpose | |---|---| | figma_get_file_raw | Fetch raw file JSON for debugging. | | figma_get_nodes_raw | Fetch raw node JSON for debugging. |

Prefer processed tools first. Use raw tools only when debugging a shape the compact transformers do not expose yet.

Figma Context Workflow

figma_context keeps the original overview/screen concepts:

• mode="overview" is for pages, canvases, worksheets, and multi-screen flows.
• mode="screen" is for a focused frame or screen.

Recommended flow:

1. Start with mode="overview" for broad Jira or story links.
2. Pick relevant screen node IDs from the overview.
3. Re-run with mode="screen" for implementation details.

Useful options:

| Option | Notes | |---|---| | format | markdown for agent-readable text, or structured JSON when exact fields matter. | | includeRaw | Adds raw tree data; use sparingly because output can grow quickly. | | includeHidden | Includes hidden nodes. Defaults to visible-only summaries. | | includeStyles | Includes style details where available. | | maxDepth | Bounds tree traversal. | | maxScreens | Bounds overview screen candidates. | | maxTextPerScreen | Bounds extracted text per screen. |

Atlassian Integration

packages/atlassian uses this package when Jira or Confluence context contains Figma links. story_context, jira_issue includeContext=true, and jira_get_issue includeContext=true keep the Figma URL inventory and, when auth is configured, add a Linked Figma Context section.

The integration is bounded for Jira latency:

• Figma enrichment defaults to auto: enabled only when Figma auth is configured.
• includeFigmaContext: false keeps only URL inventory.
• includeFigmaContext: true records missing-auth or API failures in inaccessibleLinks instead of failing Jira context.
• maxFigmaLinks defaults to 2.
• Figma links are fetched with concurrency 2.
• Individual Figma failures do not prevent Jira or Confluence context from returning.

Scopes And Permissions

Figma REST tokens need scopes that match the tool you call:

| Capability | Typical scope | |---|---| | Files, nodes, text, design context | file_content:read | | Comments | file_comments:read | | Components, styles, libraries | library_assets:read and library_content:read |

Some files also require membership or file-level access in Figma. A valid token without access to the target file returns 403/404-style guidance.

Rate Limits And Caching

The REST client retries 429 responses using Figma's Retry-After header, up to a bounded retry cap. If rate limits continue, narrow requests with ids, nodeId, and depth, or wait before retrying.

Cacheable responses are stored under:

$XDG_CACHE_HOME/pi/figma

or, when XDG_CACHE_HOME is unset:

~/.cache/pi/figma

Clear cached responses with:

rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/pi/figma"

Image render URLs and image-fill URLs are not cached because Figma treats them as expiring links.

FigJam Slides And Limitations

URL parsing accepts Figma /file, /design, /proto, /board, and /slides links when a file key is present. REST detail varies by file type and token scope:

• FigJam and Slides documents may expose less design-to-code structure than design files.
• Prototype behavior, live selection, desktop MCP state, OAuth app publishing, webhooks, and mutating Figma APIs are out of scope.
• Large files should be queried by node id and bounded depth instead of raw full-file reads.

Troubleshooting

| Symptom | Action | |---|---| | Figma API token not found | Create ~/.pi/sf/figma/config.json with { "apiToken": "MY_TOKEN" } or set a documented env fallback. | | 401 or 403 | Check token validity, scopes, and file access. | | 404 | Confirm the file key and node id, and verify the token can access the file. | | 429 | Wait or narrow the request with node IDs and lower depth. | | Request too large | Use figma_get_nodes_raw, figma_get_design_context, or figma_context with a node id and bounded depth. | | Duplicate figma_context warning | Remove the legacy figma-context package from Pi global and project scopes. |

Security Notes

• Tokens are read from local config or environment and are never printed by tools.
• pi does not scaffold secret-bearing Figma config files.
• Keep ~/.pi/sf/figma/config.json at chmod 600 when possible.
• Asset downloads only write when outputDir is explicit and resolved safely under the allowed working directory.
• Raw tools can return large file data; prefer compact tools for normal agent work.