OpenParable
Skip to content
← Back to skills

Figma Hello World

Apps & Automation
figma-hello-world

Figma Hello World is an Agent Skill for apps & automation published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Make your first Figma REST API call to fetch a file and inspect its node tree. Use when starting a new Figma integration, testing API connectivity, or learning the Figma document structure. Trigger with phrases like "figma hello world", "figma first call", "figma quick start", "fetch figma file".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/figma-pack/skills/figma-hello-world/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/figma-hello-world, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Figma Hello World

Overview

Make your first Figma REST API call. Fetch a file's metadata and document tree, then inspect the node structure that represents every layer and object in a Figma design.

Prerequisites

  • Completed figma-install-auth setup
  • A Figma file key (from the URL: figma.com/design/<FILE_KEY>/...)
  • FIGMA_PAT environment variable set

Instructions

Step 1: Fetch a File

# Get the full document JSON for a file
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}" | jq '{
    name: .name,
    lastModified: .lastModified,
    version: .version,
    pages: [.document.children[] | .name]
  }'

Expected output:

{
  "name": "My Design File",
  "lastModified": "2025-03-15T10:30:00Z",
  "version": "1234567890",
  "pages": ["Page 1", "Components", "Tokens"]
}

Step 2: Understand the Node Tree

Every Figma file is a tree of typed nodes:

DOCUMENT (root)
├── CANVAS (page)
│   ├── FRAME (container / auto-layout)
│   │   ├── TEXT
│   │   ├── RECTANGLE
│   │   └── INSTANCE (component instance)
│   ├── GROUP
│   │   └── VECTOR
│   ├── COMPONENT (reusable master)
│   └── SECTION

Key node types: DOCUMENT, CANVAS, FRAME, GROUP, RECTANGLE, ELLIPSE, TEXT, VECTOR, COMPONENT, COMPONENT_SET, INSTANCE, LINE, SECTION, BOOLEAN_OPERATION.

Step 3: TypeScript Hello World

// hello-figma.ts
const PAT = process.env.FIGMA_PAT!;
const FILE_KEY = process.env.FIGMA_FILE_KEY!;

interface FigmaNode {
  id: string;
  name: string;
  type: string;
  children?: FigmaNode[];
}

interface FigmaFileResponse {
  name: string;
  lastModified: string;
  version: string;
  document: FigmaNode;
  components: Record<string, { key: string; name: string; description: string }>;
  styles: Record<string, { key: string; name: string; style_type: string }>;
}

async function main() {
  const res = await fetch(
    `https://api.figma.com/v1/files/${FILE_KEY}`,
    { headers: { 'X-Figma-Token': PAT } }
  );

  if (!res.ok) {
    throw new Error(`Figma API error: ${res.status} ${res.statusText}`);
  }

  const file: FigmaFileResponse = await res.json();

  console.log(`File: ${file.name}`);
  console.log(`Last modified: ${file.lastModified}`);
  console.log(`Components: ${Object.keys(file.components).length}`);
  console.log(`Styles: ${Object.keys(file.styles).length}`);

  // Walk the first page and list top-level frames
  const firstPage = file.document.children?.[0];
  if (firstPage) {
    console.log(`\nPage: ${firstPage.name}`);
    for (const child of firstPage.children ?? []) {
      console.log(`  ${child.type}: ${child.name} (${child.id})`);
    }
  }
}

main().catch(console.error);

Step 4: Fetch Specific Nodes

// Fetch only specific nodes by ID (faster for large files)
async function fetchNodes(fileKey: string, nodeIds: string[]) {
  const ids = nodeIds.join(',');
  const res = await fetch(
    `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${ids}`,
    { headers: { 'X-Figma-Token': PAT } }
  );
  const data = await res.json();
  // data.nodes is a map: { "nodeId": { document: {...}, components: {...} } }
  return data.nodes;
}

// Node IDs use the format "pageId:frameId" (e.g., "0:1", "123:456")
const nodes = await fetchNodes(FILE_KEY, ['0:1', '2:3']);

Output

  • File metadata (name, version, last modified)
  • Page names listed from the document tree
  • Top-level frames with node IDs and types
  • Component and style counts

Error Handling

ErrorStatusCauseSolution
Not found404Invalid file keyVerify the key from the Figma URL
Forbidden403No access to fileCheck token scopes and file permissions
Rate limited429Too many requestsHonor Retry-After header
Empty document200File has no pagesCheck if file was recently created

Examples

Quick Node Counter

# Count total nodes in a file
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}" \
  | jq '[.. | .id? // empty] | length'

Get File Thumbnail

curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}" \
  | jq -r '.thumbnailUrl'

Resources

Next Steps

Proceed to figma-local-dev-loop for setting up a development workflow.