--- name: figma-reference-architecture-8df181d63a4e description: 'Reference architecture for production Figma API integrations. Use when designing a new Figma integration, planning project structure, or establishing patterns for design-to-code pipelines. Trigger with phrases like "figma architecture", "figma project structure", "figma integration design", "figma best practices layout". ' allowed-tools: Read, Grep version: 1.6.0 license: MIT author: Jeremy Longshore tags: - saas - figma compatibility: Designed for Claude Code --- # 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`): ```typescript // 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`): ```typescript // file → styles → nodes → CSS/JSON tokens export async function extractTokens(fileKey: string): Promise { 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`): ```typescript // 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`): ```typescript // 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 ```typescript // 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): ```text 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: ```text 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 - [Figma REST API](https://developers.figma.com/docs/rest-api/) - [Figma REST API OpenAPI Spec](https://github.com/figma/rest-api-spec) - [Figma Webhooks V2](https://developers.figma.com/docs/rest-api/webhooks/) ## Next Steps For multi-environment setup, see `figma-multi-env-setup`. --- Source attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/figma-pack/skills/figma-reference-architecture/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Jeremy Longshore Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/figma-pack/skills/figma-reference-architecture/SKILL.md Attribution basis: Source repository record Fields of work: Design, Development & Engineering, Product Management Roles: Frontend Developer, Growth Product Manager, Product Designer, Technical Product Manager, UX Designer Specialties: API, Design, DevOps, Figma, Frontend, Git, Testing Tools: Figma Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: c6462f2e2415bedc5f3847c312c5ed486607f838b572d438719c5d4129709d46