Figma Skill — 设计协作平台

/tmp/wp_post_content.html

figma-skill

  

A high-performance TypeScript SDK for extracting Figma design data. Optimized for AI workflows with token-efficient TOON format (30-60% smaller), automatic pagination for large files, and parallel image processing.

Why figma-skill?

• AI-Optimized: TOON format reduces token usage by 30-60% compared to JSON, perfect for LLM consumption
• Handles Any File Size: Automatic fallback to paginated fetching - no configuration needed
• Streaming API: Memory-efficient chunk-based processing for files with 10K+ nodes
• Built-in Image Processing: Parallel download with crop, resize, and format conversion
• Smart Caching: LRU cache with 80%+ hit rate reduces API calls
• Type-Safe: Full TypeScript with @figma/rest-api-spec types
• Resilient: Auto-retry with exponential backoff, rate limiting, timeout handling

Features

• TOON Format: 30-60% smaller than JSON, optimized for AI consumption
• Automatic Fallback: Handles files of any size without configuration
• Streaming API: Memory-efficient chunk-based processing for 10K+ nodes
• Smart Caching: LRU cache with 80%+ hit rate
• Image Processing: Parallel download with crop, resize, and format conversion
• Pluggable Extractors: Modular extraction pipeline for custom data needs
• Type-Safe: Full TypeScript with @figma/rest-api-spec types
• Resilient: Auto-retry with exponential backoff, rate limiting
• Utility Functions: requireEnv, logging, deduplication helpers

Installation

npm install figma-skill

yarn add figma-skill

pnpm add figma-skill

bun add figma-skill

Quick Start

import { FigmaExtractor } from "figma-skill";

const client = new FigmaExtractor({
  token: process.env.FIGMA_ACCESS_TOKEN,
});

// Extract in TOON format (token-efficient)
const design = await client.getFile("abc123DEF", { format: "toon" });

// design is a string in TOON format
await Bun.write("design.toon", design);

Table of Contents

• [Usage](#usage)
• [TOON Format](#toon-format)
• [API Reference](#api-reference)
• [Advanced Usage](#advanced-usage)
• [Examples](#examples)
• [Performance](#performance)
• [Contributing](#contributing)
• [License](#license)

Usage

Basic File Extraction

import { FigmaExtractor } from "figma-skill";

const client = new FigmaExtractor({ token: process.env.FIGMA_TOKEN });

const design = await client.getFile("fileKey", { format: "json" });

// Access extracted data
design.nodes.forEach((node) => {
  console.log(`${node.name}: ${node.type}`);
});

Extract with TOON Format (Recommended)

import { FigmaExtractor } from "figma-skill";

const client = new FigmaExtractor({ token: process.env.FIGMA_TOKEN });

// TOON format is 30-60% smaller than JSON
const toonDesign = await client.getFile("fileKey", { format: "toon" });
await Bun.write("design.toon", toonDesign);

// For programmatic access, use JSON format
const jsonDesign = await client.getFile("fileKey", { format: "json" });
console.log(jsonDesign.nodes.length);

Get Specific Nodes

import { FigmaExtractor } from "figma-skill";

const client = new FigmaExtractor({ token: process.env.FIGMA_TOKEN });

const design = await client.getNodes("fileKey", {
  ids: ["1:2", "1:3", "1:4"],
});

Download Images

import { FigmaExtractor } from "figma-skill";
// Deduplicated download (removes duplicates)
import { downloadImagesDeduplicated } from "figma-skill/images";

const client = new FigmaExtractor({ token: process.env.FIGMA_TOKEN });

// Basic download
const downloaded = await client.downloadImages("fileKey", {
  ids: ["1:2", "1:3"],
  outputDir: "./output/images",
  format: "svg",
  parallel: 5,
});

const deduped = await downloadImagesDeduplicated(
  [
    { id: "1:2", url: "https://..." },
    { id: "1:3", url: "https://..." },
    { id: "1:2", url: "https://..." }, // duplicate removed
  ],
  { outputDir: "./output/images" }
);

Stream Large Files

import { FigmaExtractor } from "figma-skill";

const client = new FigmaExtractor({ token: process.env.FIGMA_TOKEN });

// For progress tracking on very large files (10K+ nodes)
const stream = await client.streamFile("fileKey", {
  chunkSize: 100,
});

stream.progress.on("progress", (p) => {
  console.log(`${p.percent}% - ${p.processed}/${p.total} nodes`);
});

for await (const chunk of stream) {
  // Process chunk.nodes
}

// Note: getFile() also handles large files automatically via pagination

TOON Format

TOON is a token-efficient format for design data that reduces file size by 30-60% compared to JSON. It's optimized for AI consumption and processing.

Benefits

• Smaller: 30-60% reduction in tokens
• AI-Friendly: Optimized structure for LLM processing
• Preserves Structure: Maintains design hierarchy and relationships
• Convert Back: Can convert back to full JSON when needed

Usage

import { FigmaExtractor, toToon, fromToon } from "figma-skill";

const client = new FigmaExtractor({ token: process.env.FIGMA_TOKEN });

// Extract directly to TOON
const toonString = await client.getFile("fileKey", { format: "toon" });

// Or convert existing design
const design = await client.getFile("fileKey", { format: "json" });
const toonString = toToon(design);

// Convert back from TOON
const restored = fromToon(toonString);

When to Use TOON vs JSON

| Use Case | Format | Reason |

| ----------------------- | ------ | ---------------------- |

| AI processing | toon | Token efficiency |

| File storage | toon | Smaller file size |

| Node filtering/counting | json | Need structured access |

| Debugging | json | Human-readable |

| Final output | toon | Always use TOON |

API Reference

FigmaExtractor

Main client class for Figma API interactions.

Constructor

new FigmaExtractor(config: FigmaExtractorConfig)

Options:

• token (string, required): Figma access token
• baseUrl (string, optional): API base URL (default: https://api.figma.com/v1)
• timeout (number, optional): Request timeout in ms (default: 30000)
• maxRetries (number, optional): Max retry attempts (default: 3)
• cache (boolean, optional): Enable caching (default: true)
• cacheSize (number, optional): Cache size (default: 100)
• concurrent (number, optional): Max concurrent requests (default: 10)

Methods

getFile(fileKey, options?)

Extract complete Figma file with automatic pagination fallback.

Returns: Promise<SimplifiedDesign | string> (string when format: "toon")

Options:

• format ("json" | "toon"): Output format (default: "json")
• extractors: Custom extractor functions
• maxDepth: Maximum traversal depth
• nodeFilter: Filter function for nodes
• includeComponents: Include component definitions (default: true)
• includeComponentSets: Include component set definitions (default: true)

getNodes(fileKey, options)

Extract specific nodes by IDs.

Returns: Promise<SimplifiedDesign>

Options:

• ids (string[], required): Node IDs to fetch
• extractors: Custom extractor functions
• maxDepth: Maximum traversal depth
• nodeFilter: Filter function for nodes

streamFile(fileKey, config

（内容节选自官方 README）

安装

# 安装到当前项目
npx skills add figma-skill

# 全局安装
npx skills add figma-skill -g

来源

• 作者：eekrain
• 仓库：https://github.com/eekrain/figma-skill
• npm 包：figma-skill