Getting Started

Extract variables, styles, and components from Figma via REST API and generate markdown specs that AI agents can consume directly.

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

Installation

# Run directly
npx figma-to-design-md extract --file <key> --token <token>

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

Setup

1. Get a Figma token

Open Figma Settings → Personal access tokens → Create with File content: Read-only scope.

2. Get the file key

From any Figma URL:

https://www.figma.com/design/ABC123xyz/My-Design-System
                              ^^^^^^^^^^^
                              this is the file key

3. Run

figma-to-design-md extract \
  --file ABC123xyz \
  --token figd_xxx

CLI Options

FlagDefaultDescription

--file <key>—Figma file key (required)

--token <token>$FIGMA_TOKENFigma personal access token

--out <dir>./specsOutput directory

--mode <mode>fullfull | foundations | components

--node <id>—Scope to a specific page/frame

--versionPrint version

--helpPrint help

Output Structure

design-system.md

Top-level overview with counts and links to all detailed files.

foundations/*.md

FileContents

colors.mdAll COLOR variables + FILL styles in markdown tables

typography.mdFont-related variables + TEXT styles

spacing.mdVariables matching space, gap, padding, margin

radii.mdVariables matching radius, round, corner

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

Foundations Example

What a generated colors.md looks like:

# Colors ## Variables (12 tokens) | Name | Collection | Light | Dark | |-------------------|------------|-----------|-----------| | color/primary | Theme | #3b82f6 | #60a5fa | | color/secondary | Theme | #6366f1 | #818cf8 | | color/bg | Theme | #fafafa | #0a0a0a | | color/text | Theme | #0a0a0a | #f5f5f5 | | color/muted | Theme | #737373 | #a3a3a3 | ## Styles (3 styles) | Name | Type | |-----------------|-------| | Primary Fill | FILL | | Background | FILL | | Text Default | FILL |

Components Example

What a generated component file looks like:

# Button > Primary action element with label and optional icon. - **Figma node:** 123:456 - **Type:** COMPONENT_SET ## Variants | Property | Values | |----------|-------------------| | Size | sm, md, lg | | Style | primary, outline | | State | default, hover | ## Usage _Add usage guidelines here._

Gap Detection

The tool automatically detects potential issues and writes them to gaps.md:

Missing descriptions

Components without Figma descriptions — agents can't understand intent

No tokens found

File has no local variables — specs will be incomplete

Undocumented components

Components exist but lack descriptions for agent consumption

Pipeline

Combine with design-system-ai-starter for a full workflow:

1. Extract from Figma → figma-to-design-md 2. Generate agent rules → design-system-ai-starter 3. AI writes UI code → Cursor / Claude / Copilot 4. Check live consistency → ds-health

View onGitHub →