gabrielmoreira Figma Reference Architecture
Overview
Production-ready architecture for Figma REST API integrations. Covers the three most common use cases: design token pipelines, asset export systems, and webhook-driven automation.
Prerequisites
- Understanding of Figma REST API endpoints
- TypeScript project setup
- Decision on deployment platform
Instructions
Step 1: Project Structure
figma-integration/
├── src/
│ ├── figma/
│ │ ├── client.ts # Typed REST API wrapper
│ │ ├── types.ts # Figma API response types
│ │ ├── errors.ts # FigmaApiError, FigmaRateLimitError
│ │ ├── cache.ts # LRU cache for API responses
│ │ └── walker.ts # Node tree traversal utilities
│ ├── services/
│ │ ├── token-extractor.ts # Design token extraction
│ │ ├── asset-exporter.ts # Image/icon export pipeline
│ │ ├── comment-syncer.ts # Comment sync to Slack/Jira
│ │ └── variable-syncer.ts # Variables API sync (Enterprise)
│ ├── webhooks/
│ │ ├── handler.ts # Webhook event router
│ │ ├── verify.ts # Passcode verification
│ │ └── processors/
│ │ ├── file-update.ts # FILE_UPDATE handler
│ │ ├── comment.ts # FILE_COMMENT handler
│ │ └── library.ts # LIBRARY_PUBLISH handler
│ ├── api/
│ │ ├── health.ts # Health check endpoint
│ │ ├── tokens.ts # Token API endpoint
│ │ └── assets.ts # Asset download endpoint
│ └── index.ts
├── scripts/
│ ├── extract-tokens.mjs # CLI: extract tokens from Figma
│ ├── export-icons.mjs # CLI: export icons from Figma
│ └── setup-webhooks.mjs # CLI: create/manage webhooks
├── output/
│ ├── tokens.css # Generated CSS custom properties
│ ├── tokens.json # Generated JSON tokens
│ └── icons/ # Exported SVG/PNG icons
├── tests/
│ ├── fixtures/ # Saved Figma API responses
│ └── *.test.ts
├── .env.example
└── package.json
Step 2: Data Flow Architecture
┌────────────────────────────────────────────────┐
│ Figma Cloud │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Files API │ │Images API│ │ Webhooks V2 │ │
│ │ /v1/files │ │/v1/images│ │ /v2/webhooks │ │
│ └─────┬─────┘ └────┬─────┘ └──────┬───────┘ │
└────────┼──────────────┼───────────────┼─────────┘
│ │ │
┌────▼────┐ ┌────▼────┐ ┌─────▼────┐
│ Token │ │ Asset │ │ Webhook │
│Extractor│ │Exporter │ │ Handler │
└────┬────┘ └────┬────┘ └─────┬────┘
│ │ │
┌────▼────┐ ┌────▼────┐ ┌─────▼────┐
│ Cache │ │ Cache │ │ Event │
│ (LRU) │ │ (URLs) │ │ Queue │
└────┬────┘ └────┬────┘ └─────┬────┘
│ │ │
┌────▼──────────────▼───────────────▼────┐
│ Output Layer │
│ tokens.css │ icons/ │ Slack/Jira │
└─────────────────────────────────────────┘
Step 3: Key Components
Figma Client (see figma-sdk-patterns):
// Singleton with retry, rate limit handling, and caching
const client = new FigmaClient(process.env.FIGMA_PAT!);
// All API calls go through the client
const file = await client.getFile(fileKey); // GET /v1/files/:key
const nodes = await client.getFileNodes(fileKey, ids); // GET /v1/files/:key/nodes
const images = await client.getImages(fileKey, ids); // GET /v1/images/:key
const comments = await client.getComments(fileKey); // GET /v1/files/:key/comments
const vars = await client.getLocalVariables(fileKey); // GET /v1/files/:key/variables/local
Token Extraction Pipeline (see figma-core-workflow-a):
// file → styles → nodes → CSS/JSON tokens
export async function extractTokens(fileKey: string): Promise<DesignToken[]> {
const file = await client.getFile(fileKey);
const styleNodes = await client.getFileNodes(fileKey, Object.keys(file.styles));
return parseTokensFromNodes(file.styles, styleNodes);
}
Asset Export Pipeline (see figma-core-workflow-b):
// file → find components → render images → download
export async function exportIcons(fileKey: string, frameId: string) {
const frame = await client.getFileNodes(fileKey, [frameId]);
const componentIds = findComponents(frame).map(n => n.id);
const imageUrls = await client.getImages(fileKey, componentIds, { format: 'svg' });
return downloadAll(imageUrls);
}
Webhook Handler (see figma-webhooks-events):
// Verify passcode → route event → process async
export function webhookRouter(event: FigmaWebhookEvent) {
switch (event.event_type) {
case 'FILE_UPDATE': return handleFileUpdate(event);
case 'LIBRARY_PUBLISH': return handleLibraryPublish(event);
case 'FILE_COMMENT': return handleComment(event);
}
}
Step 4: Configuration
// src/config.ts
export const config = {
figma: {
token: process.env.FIGMA_PAT!,
fileKey: process.env.FIGMA_FILE_KEY!,
webhookPasscode: process.env.FIGMA_WEBHOOK_PASSCODE,
},
cache: {
fileTTL: 5 * 60 * 1000, // 5 minutes for file metadata
imageTTL: 24 * 60 * 60 * 1000, // 24 hours for image URLs
maxEntries: 500,
},
api: {
maxConcurrent: 3,
retryAttempts: 3,
requestTimeout: 30_000,
},
};
Output
- Structured project layout with clear separation
- Data flow from Figma API to local artifacts
- Reusable client, cache, and pipeline components
- Configuration management for all environments
Error Handling
| Layer | Error | Recovery |
|---|---|---|
| Client | 429 Rate Limited | Retry with Retry-After header |
| Client | 403 Forbidden | Alert on token expiry; fail gracefully |
| Cache | Cache miss storm | Stale-while-revalidate pattern |
| Webhook | Duplicate events | Idempotency via event timestamp |
| Export | Image render null | Skip node, log warning |
Examples
Scaffold the Step 1 project structure and trace one request through the layers (Step 2 data flow):
src/
├── client/figma-client.ts # typed REST client (retry + rate-limit aware)
├── services/token-sync.ts # orchestration: fetch → transform → emit
├── webhooks/receiver.ts # V2 webhook endpoint (passcode-verified)
├── cache/file-cache.ts # version-keyed response cache
└── config/index.ts # env-validated configuration
A LIBRARY_PUBLISH webhook arriving becomes, in order:
receiver.ts verify passcode → enqueue {file_key}
token-sync.ts fetch /v1/files/{key}/styles → resolve nodes → transform
file-cache.ts invalidate stale entry (keyed by file version)
emit write tokens.json → open PR via CI
Component contracts and the config schema: references/key-components.md, references/configuration.md.
Resources
Next Steps
For multi-environment setup, see figma-multi-env-setup.