figma-to-design-md — Andrew Antoshkin

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

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

Output Structure

design-system.md

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

foundations/*.md

File	Contents
colors.md	All COLOR variables + FILL styles in markdown tables
typography.md	Font-related 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.

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 descriptionsComponents without Figma descriptions — agents can't understand intent
No tokens foundFile has no local variables — specs will be incomplete
Undocumented componentsComponents exist but lack descriptions for agent consumption

Pipeline

The markdown from Figma is the input ds-context packs for a model:

figma-to-design-md extracts the spec ← you are here
ds-context packs it for the model
ui-repair patches violations
ds-eval scores the result

Source