figma-to-design-md

Как устроено

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

Установка

# Запустить сразу
npx figma-to-design-md extract --file <key> --token <token>

# Или установить глобально
npm i -g figma-to-design-md

Настройка

1. Возьми токен Figma

Открой настройки Figma. Зайди в Personal access tokens и создай токен с правом File content: Read-only.

2. Возьми ключ файла

Из любой ссылки на файл в Figma:

https://www.figma.com/design/ABC123xyz/My-Design-System
                              ^^^^^^^^^^^
                              это ключ файла

3. Запусти

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

Параметры

Флаг	По умолчанию	Описание
--file <key>	—	Ключ файла Figma (обязательно)
--token <token>	$FIGMA_TOKEN	Персональный токен Figma
--out <dir>	./specs	Папка для результата
--mode <mode>	full	full \| foundations \| components
--node <id>	—	Ограничить страницей или фреймом
--version		Показать версию
--help		Показать справку

Структура файлов

design-system.md

Обзор: счётчики и ссылки на подробные файлы.

foundations/*.md

Файл	Содержимое
colors.md	Все переменные COLOR и стили FILL в markdown-таблицах
typography.md	Переменные шрифта и стили TEXT
spacing.md	Переменные с space, gap, padding, margin
radii.md	Переменные с radius, round, corner

Если у переменной несколько режимов, например Light и Dark, в файл попадают все значения.

Пример основ

Как выглядит готовый colors.md:

# 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 |

Пример компонента

Как выглядит файл компонента:

# 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._

Заглушка _Add usage guidelines here._ оставлена намеренно: CLI выгружает из Figma только фактическую структуру (описание ноды, свойства и варианты) и не додумывает за команду правила применения.

Пробелы и передача в контекст

Инструмент сам замечает пустые места в файле Figma и пишет их в gaps.md:

Нет описанийУ компонентов нет описания в Figma. Агент не понимает, для чего они.
Нет токеновВ файле нет локальных переменных. Markdown получится неполным.
Компоненты без документацииКомпоненты есть, а описания для агента нет.

После того как пробелы заполнены, полученные markdown-таблицы можно напрямую подать в ds-lint (флаг --tokens) или упаковать под бюджет токенов через ds-context.

Код на GitHub