Figma Node Fetcher

Fetch data by node from Figma URL and avoid downloading full file trees.

When To Use

Invoke when:

• User provides a Figma link and needs node JSON structure
• User needs node image export (screenshot, rendered PNG/SVG)
• User wants analysis for a specific node, not the whole file
• User says "fetch Figma data", "get Figma node", "export Figma image", or similar

Do NOT invoke when:

• URL has no node-id query — ask user to provide the specific node link
• User asks to fetch an entire Figma file tree — not supported
• Request is outside supported endpoints (e.g., comments, version history, components API)

Prerequisites

• Node.js >= 18
• FIGMA_ACCESS_TOKEN environment variable (or .env.local / .figma.env file with the token)
• If token is missing, run node {skill_dir}/scripts/init_figma_config.cjs to set up

Fixed Workflow

1. Check token config: FIGMA_ACCESS_TOKEN.
2. Validate Figma URL: must include node-id.
3. Route by need:
   • structure data → type=node
   • rendered image → type=image
4. Choose fetch mode:
   • single URL → fetch
   • multiple URLs → fetch-batch
5. Run script and return standardized JSON output.

Config Policy

Read token in this order:

1. environment variable FIGMA_ACCESS_TOKEN
2. {project_root}/.env
3. {project_root}/.env.local
4. {project_root}/.figma.env

Recommended location: {project_root}/.env.local

Scripts

1) Init config

node {skill_dir}/scripts/init_figma_config.cjs --project-root {project_root} --file .env.local

2) Check config

node {skill_dir}/scripts/figma_fetch.cjs check-config --project-root {project_root}

3) Validate URL

node {skill_dir}/scripts/figma_fetch.cjs validate-link --url "https://www.figma.com/file/xxx/xxx?node-id=1%3A2"

4) Fetch node JSON

node {skill_dir}/scripts/figma_fetch.cjs fetch \
  --project-root {project_root} \
  --url "https://www.figma.com/file/xxx/xxx?node-id=1%3A2" \
  --type node \
  --depth 2 \
  --output-dir {project_root}/.figma-output/node

5) Fetch node image

node {skill_dir}/scripts/figma_fetch.cjs fetch \
  --project-root {project_root} \
  --url "https://www.figma.com/file/xxx/xxx?node-id=1%3A2" \
  --type image \
  --format png \
  --scale 2 \
  --output-dir {project_root}/.figma-output/image

6) Batch fetch (multiple URLs)

node {skill_dir}/scripts/figma_fetch.cjs fetch-batch \
  --project-root {project_root} \
  --url "https://www.figma.com/file/xxx/A?node-id=1%3A2" \
  --url "https://www.figma.com/file/xxx/A?node-id=1%3A3" \
  --type node \
  --output-dir {project_root}/.figma-output/batch \
  --clean-output

or:

node {skill_dir}/scripts/figma_fetch.cjs fetch-batch \
  --project-root {project_root} \
  --urls-file {project_root}/figma-urls.txt \
  --type image \
  --format png \
  --output-dir {project_root}/.figma-output/batch-images

Input Contract

Required fields:

• url
• type (node or image)
• output-dir

url must include node-id query.

Batch mode:

• Provide at least one --url or --urls-file
• Each URL must include node-id

Output Contract

Always return JSON with:

• ok
• mode
• type
• single mode: figma.file_key, figma.node_id, output
• batch mode: success_count, failure_count, items, failures, output_dir

Error Handling

• Missing token: return missing_token + setup guidance.
• Missing node-id: fail fast with clear error.
• No image URL from API: fail with explicit error.
• Batch mode partial failure: return non-zero code + failures array.

API Scope Notes

Read and follow:

• {skill_dir}/references/figma-rest-api-notes.md
• {skill_dir}/examples/integration.md

Supported endpoints only:

• /v1/files/{file_key}/nodes
• /v1/images/{file_key}

Do not promise capabilities outside these scripts.

Execution Checklist

Before responding to user, verify:

• FIGMA_ACCESS_TOKEN is available (run check-config if uncertain)
• Figma URL contains node-id query parameter
• Correct type selected (node for JSON structure, image for rendered export)
• output-dir is set to a project-relative path
• Script returned ok: true — if not, relay the error clearly
• Response includes the standardized JSON output or saved file path

Boundary Enforcement

This skill ONLY handles:

• ✅ Validating Figma URLs with node-id
• ✅ Fetching node JSON structure via /v1/files/{file_key}/nodes
• ✅ Fetching node rendered images via /v1/images/{file_key}
• ✅ Batch fetching multiple nodes (JSON or image)
• ✅ Token configuration setup and validation

This skill does NOT handle:

• ❌ Fetching entire Figma file trees (no node-id) → inform user this is unsupported
• ❌ Figma comments, version history, or components API → outside scope
• ❌ Design-to-code generation → delegate to a frontend/product skill, use this skill as data provider
• ❌ Modifying Figma designs (read-only access)

Cross-Skill Orchestration

This skill can be called by other skills.

Recommended orchestration pattern:

1. Product/Frontend skill receives Figma URL from user.
2. Product/Frontend skill calls this skill (or runs {skill_dir}/scripts/figma_fetch.cjs) to fetch node JSON/image.
3. Product/Frontend skill consumes the fetched artifacts to continue implementation.

Practical rule:

• Do not switch to this skill first unless the user request is specifically “fetch Figma data/image”.
• In mixed tasks (e.g., “build page from Figma”), keep the main skill as orchestrator and use this skill as a data provider.