| name | figma-reference-architecture |
| 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 <jeremy@intentsolutions.io> |
| 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 │
└─────────────────────────────────────────┘
