figma-to-design-md

Generate AI-readable design system documentation from a Figma file.

Extracts variables, styles, and components via Figma REST API, and outputs structured markdown specs that AI agents (Cursor, Claude, Copilot) can consume directly.

Quick navigation

• How it works
• Installation
• Usage
• Output structure
• Figma setup tips
• Repository layout
• Pipeline
• Testing
• Contributing

How it works

Figma file ──▶ figma-to-design-md ──▶ specs/
                                        ├── design-system.md
                                        ├── foundations/
                                        │   ├── colors.md
                                        │   ├── typography.md
                                        │   ├── spacing.md
                                        │   └── radii.md
                                        ├── components/
                                        │   ├── README.md
                                        │   ├── button.md
                                        │   └── ...
                                        └── gaps.md

The tool connects to the Figma REST API, reads your variables (local), styles, and components, then generates clean markdown tables and descriptions that an AI coding agent can reference.

Installation

# run directly
npx figma-to-design-md extract --file <fileKey> --token <FIGMA_TOKEN>

# or install globally
npm i -g figma-to-design-md

Requires Node.js 18+ (uses native fetch).

Usage

Get a Figma personal access token

1. Open Figma account settings → Personal access tokens
2. Create a token with File content: Read-only scope

Get the file key

From any Figma URL:

https://www.figma.com/design/ABC123xyz/My-Design-System?node-id=0-1
                              ^^^^^^^^^^^
                              this is the file key

Run

# Full extraction (variables + styles + components)
figma-to-design-md extract --file ABC123xyz --token figd_xxx

# Foundations only (variables and styles)
figma-to-design-md extract --file ABC123xyz --mode foundations

# Components only
figma-to-design-md extract --file ABC123xyz --mode components

# Custom output directory
figma-to-design-md extract --file ABC123xyz --out ./docs/design

# Token via environment variable
export FIGMA_TOKEN=figd_xxx
figma-to-design-md extract --file ABC123xyz

# Scope to a specific page or frame (by Figma node ID)
figma-to-design-md extract --file ABC123xyz --node 123:456

CLI options

| Flag | Description | Default | |------|-------------|---------| | --file <key> | Figma file key (required) | — | | --token <token> | Figma personal access token | $FIGMA_TOKEN | | --out <dir> | Output directory | ./specs | | --mode <mode> | full | foundations | components | full | | --node <id> | Scope component extraction to a specific page/frame | — | | -v, --version | Print version | — | | -h, --help | Print help | — |

Output structure

design-system.md

Top-level overview: counts of variables, styles, components, and links to detailed files.

foundations/*.md

| File | Contents | |------|----------| | colors.md | All COLOR variables + FILL styles | | typography.md | Font-related FLOAT variables + TEXT styles | | spacing.md | Variables matching space, gap, padding, margin | | radii.md | Variables matching radius, round, corner |

Variables with multiple modes (e.g., Light / Dark) show all values.

components/*.md

One file per component with:

• Description (from Figma)
• Figma node ID
• Variant table (for COMPONENT_SET)
• Usage placeholder

gaps.md

Heuristic warnings: missing descriptions, no tokens, undocumented components, etc.

Figma setup tips

For best results:

• Name variables consistently — use prefixes like color/, spacing/, radius/ so the tool can categorize automatically
• Add descriptions to components and variables in Figma — they appear in the generated docs
• Use variable collections for tokens rather than local styles
• Organize components clearly — the tool traverses the full file tree by default; use --node to scope to a specific page for speed

Repository layout

figma-to-design-md/
├── bin/
│   └── figma-to-design-md.js    # CLI entry point
├── lib/
│   ├── figma-api.js             # Figma REST API client (zero deps)
│   ├── parse-variables.js       # Transform variables API → structured data
│   ├── parse-styles.js          # Group styles by type
│   ├── generate-foundations.js  # Build foundations/*.md
│   ├── generate-components.js   # Build components/*.md
│   └── generate-summary.js      # Build design-system.md + gaps.md
├── test/                        # Unit tests (node:test)
├── package.json
├── LICENSE
└── README.md

Pipeline

This tool pairs well with design-system-ai-starter for a full Figma-to-AI pipeline:

Figma ──▶ figma-to-design-md ──▶ specs/
                                    │
                                    ▼
          design-system-ai-starter ──▶ .cursor/rules/
                                       CLAUDE.md
                                       AGENTS.md
                                         │
                                         ▼
                                  AI agent uses specs
                                  when writing code

Testing

npm test

Runs unit tests and a full-pipeline integration test (22 tests covering parsing, generation, gap detection, and edge cases).

Contributing

See CONTRIBUTING.md.

License

MIT