Figma Hello World
Apps & Automationfigma-hello-worldFigma 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".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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-authsetup - A Figma file key (from the URL:
figma.com/design/<FILE_KEY>/...) FIGMA_PATenvironment 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
| Error | Status | Cause | Solution |
|---|---|---|---|
Not found | 404 | Invalid file key | Verify the key from the Figma URL |
Forbidden | 403 | No access to file | Check token scopes and file permissions |
Rate limited | 429 | Too many requests | Honor Retry-After header |
Empty document | 200 | File has no pages | Check 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.