design-system-ai-starter

Starter kit и CLI для подготовки реальной дизайн-системы к работе с AI coding agents.

Идея простая: у команды уже есть токены, CSS variables, theme-файлы и библиотека компонентов, но AI-агенты всё равно:

• выдумывают значения
• дрейфуют между сессиями
• не понимают дизайн-намерение из кода

Этот репозиторий помогает создать промежуточный слой между дизайн-системой и агентами:

• .cursor/rules/design-system.mdc
• CLAUDE.design-system.md
• AGENTS.design-system.md
• specs/foundations/*
• specs/tokens/token-reference.md

Быстрый старт

Сейчас основной путь использования такой: клонировать репозиторий и запускать CLI локально.

git clone https://github.com/AndrewAntoshkin/design-system-ai-starter.git
cd design-system-ai-starter
node ./bin/design-system-ai-starter.js help
node ./bin/design-system-ai-starter.js init ./my-ui-project
node ./bin/design-system-ai-starter.js sync-tokens --input ./examples/css-variables/tokens.css --target ./my-ui-project
node ./bin/design-system-ai-starter.js doctor ./my-ui-project

Метаданные пакета уже подготовлены под npm, но главный сценарий входа пока именно такой.

Команды

init

Раскладывает базовую AI-readable структуру в проект:

node ./bin/design-system-ai-starter.js init .

sync-tokens

Читает CSS variables или JSON-токены и обновляет markdown-спеки:

node ./bin/design-system-ai-starter.js sync-tokens --input ./tokens.css --target .

Поддерживается:

• CSS variables
• nested / flat JSON
• DTCG-подобный формат с $value / $type
• структуры с value / type
• массивы { name, value }

Важно:

• примеры examples/tailwind/design-tokens.ts и examples/chakra/theme.ts лежат в репозитории как reference patterns
• это не прямой input для sync-tokens
• сначала такие токены нужно экспортировать в CSS variables или JSON

doctor

Проверяет, что обязательные файлы существуют:

node ./bin/design-system-ai-starter.js doctor .

help и --version

node ./bin/design-system-ai-starter.js help
node ./bin/design-system-ai-starter.js --version

Для чего подходит

• существующая дизайн-система без agent-readable слоя
• проект с CSS variables или JSON токенами
• команда, которая хочет использовать Cursor / Claude без визуального дрейфа

Сейчас также поддерживаются foundation docs для:

• color
• spacing
• typography
• radius
• motion

Для чего не подходит

• как полноценный Figma exporter
• как DOM drift detector
• как генератор всей дизайн-системы с нуля

Это базовый operational layer, а не финальный полный продукт.

Demo

Сценарий before/after описан в demo/README.md.

demo/output/ закоммичен специально как пример сгенерированного результата, чтобы его можно было изучить без запуска CLI.