DESIGN.md от Google Labs
DESIGN.md
Формат DESIGN.md для агентов и CLI: проверка контраста и ссылок, сравнение версий, экспорт токенов в Tailwind и DTCG
- 28 487 ★ репозитория
- Последний коммит
- Apache-2.0
Минимальный доступ
Почему такой уровень
- CLI запускается через npx как пакет npm, он читает указанный файл или стандартный ввод и печатает результат, а запись в файл идет только через ваше перенаправление вывода
Установка
Ручная установка
npx @google/design.md lint DESIGN.mdЗапуск без установки, нужен Node.js 18 или новее. В PowerShell на Windows используйте `npx -p @google/design.md designmd lint DESIGN.md`.
Доступ и проверки
Как мы проверяемМинимальный доступИнструмент ничего не запускает и не ходит в сеть.
- CLI запускается через npx как пакет npm, он читает указанный файл или стандартный ввод и печатает результат, а запись в файл идет только через ваше перенаправление вывода
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
DESIGN.md — формат файла, в котором визуальный стиль продукта описан так, чтобы его читал и человек, и ИИ-агент. В начале файла стоит блок YAML с токенами: цвета, типографика, скругления, отступы и компоненты. Ниже идет текст в Markdown, где по разделам в фиксированном порядке (обзор, цвета, типографика, сетка, глубина, формы, компоненты, что делать и чего не делать) объясняется, зачем выбраны эти значения и как их применять. Токены дают агенту точные значения, текст — причины. Компоненты ссылаются на токены записью вида `{colors.primary}`, а варианты вроде наведения оформляются отдельными записями. Вместе с форматом в репозитории лежит CLI `@google/design.md` с четырьмя командами. Команда `lint` разбирает файл и возвращает JSON с замечаниями: битые ссылки на токены, отсутствие основного цвета и типографики, пары цветов компонента с контрастом ниже 4,5:1 по WCAG AA, неиспользуемые цвета, неверный порядок разделов, опечатки в ключах. Команда `diff` сравнивает две версии файла и сообщает об изменениях токенов и о регрессии, если ошибок или предупреждений стало больше. Команда `export` переводит токены в конфиг Tailwind v3, блок `@theme` для Tailwind v4 или файл по формату W3C DTCG. Команда `spec` выводит текст спецификации, чтобы вставить его в промпт агента. Чтобы агент читал формат, ничего ставить не нужно: достаточно дать ему файл DESIGN.md и попросить собирать интерфейс по нему. CLI нужен для проверки файла перед тем, как на него будет опираться агент.
Для кого. Для дизайнеров и фронтенд-разработчиков, которые хотят зафиксировать дизайн-систему в одном файле для агента и проверять ее линтером.
Подходит, если
- Агент каждый раз выбирает свои цвета и шрифты, и их нужно закрепить в файле проекта
- Нужно проверить, что у пар цвета текста и фона в компонентах хватает контраста по WCAG AA
- Дизайн-систему обновили, и надо увидеть, какие токены добавились, изменились или пропали
- Токены из DESIGN.md нужно получить в виде конфига Tailwind или файла DTCG
- Спецификацию формата требуется подставить в промпт агента перед созданием файла
Не подходит, если
- Нужен готовый скилл для Claude Code или Cursor: каталог `.agents/skills` в репозитории содержит служебные скиллы для разработки самого проекта
- Файл DESIGN.md надо получить с существующего сайта: CLI только читает и проверяет файл, снимать токены с сайта он не умеет, для этого в каталоге есть `extract-design-system`
- На машине нет Node.js 18 или новее: CLI опубликован как npm-пакет
- Нужна устойчивая спецификация: формат имеет версию `alpha`, и авторы предупреждают об изменениях
Пример запроса к агенту
Проверь DESIGN.md линтером и скажи, у каких кнопок не хватает контраста, затем выгрузи токены для TailwindОграничения
Формат в версии `alpha`: спецификация, схема токенов и CLI развиваются, и авторы ждут изменений. Версия CLI в манифесте 0.4.0.
Линтер ищет формальные проблемы и не оценивает, красив ли стиль. Контраст он проверяет только у пар `backgroundColor` и `textColor` в компонентах: если компонентов нет, этой проверки не будет. Основной цвет и типографику он требует отдельными предупреждениями, иначе агент подставит свои.
Порядок разделов задан жестко: допустимо пропустить раздел, но присутствующие должны идти в порядке спецификации, а повтор заголовка раздела считается ошибкой и файл отвергается. Неизвестные заголовки и цвета с допустимым значением принимаются без ошибки.
Коды выхода различаются по командам: `lint` и `diff` возвращают 1 при ошибках или регрессии, `export` возвращает 2, если файл не прочитан. В PowerShell на Windows запись `npx @google/design.md` может не дать вывода из-за расширения `.md` в имени команды. В этом случае запускайте `npx -p @google/design.md designmd`.
Лицензия Apache-2.0.
Как отключить. Если CLI установлен в проект, удалите его командой `npm uninstall @google/design.md`. При запуске через `npx` ничего не остается, кроме кэша npm. Файл DESIGN.md удалите из корня проекта или уберите ссылку на него из инструкций агента.
Частые вопросы
Из каких частей состоит файл DESIGN.md?
Из блока YAML с токенами в начале и текста в Markdown под ним. Токены задают точные значения, текст по разделам объясняет, как их применять.
Какие проверки выполняет `lint`?
Одиннадцать правил. Ошибку дают только битые ссылки на токены, правило `broken-ref`. Остальные замечания имеют уровень предупреждения или подсказки: отсутствуют основной цвет и типографика, низкий контраст, неиспользуемые токены, порядок разделов, опечатки в ключах.
В какие форматы экспортируются токены?
Через `export --format` доступны `json-tailwind` для Tailwind v3, `css-tailwind` для блока `@theme` в Tailwind v4 и `dtcg` для формата W3C Design Tokens. Значение `tailwind` — псевдоним `json-tailwind`.
Что показывает команда `diff`?
Какие токены добавлены, удалены и изменены в разделах цветов, типографики, скруглений, отступов и компонентов, а также число замечаний линтера до и после. Если ошибок или предупреждений стало больше, она сообщает о регрессии и возвращает код 1.
Можно ли вызвать линтер из кода?
Да, пакет отдает функцию `lint` из `@google/design.md/linter`. Она принимает строку Markdown и возвращает находки, сводку и разобранную дизайн-систему.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
CLI-инструментыПлагин и npx CLI, которые создают DESIGN.md по спецификации google-labs-code/design.md из официальных шаблонов
designlang
designlang (design-extract)
CLI и MCP-сервер, который читает готовый сайт и достает из него дизайн-систему: токены DTCG, конфиг Tailwind, переменные Figma и брендбук
Реестр устанавливаемых дизайн-скиллов: готовые файлы SKILL.md и DESIGN.md с токенами, правилами компонентов и доступностью под разные стили
Коллекция файлов DESIGN.md по эстетическим семействам и рецептов ремикса для задания стиля интерфейса агенту
CLI, который вытаскивает дизайн-систему любого сайта в токены: цвета, шрифты, отступы, тени за один запуск
Генератор DESIGN.md для Figma
DESIGN.md generator for Figma
Плагин Figma от TypeUI: собирает стили файла и генерирует DESIGN.md и SKILL.md для Claude Code, Codex и Cursor
Сравнение с похожими
Записи с тем же главным запросом: чем они отличаются.
| Запись | Официальный | Звезды репозитория | Главное отличие |
|---|---|---|---|
| DESIGN.md от Google Labs (эта запись) | да | 28 487 | |
| DESIGN.md | нет | 9 | плагин и npx CLI, которые создают DESIGN.md по этой спецификации из готовых шаблонов |
| extract-design-system | нет | 251 | снимает цвета, шрифты и отступы с публичного сайта и сохраняет их как токены |
Коротко о README
В репозитории лежат полная спецификация в `docs/spec.md`, три примера с готовыми файлами DESIGN.md, токенами в JSON и конфигом Tailwind (`atmospheric-glass`, `paws-and-paths`, `totality-festival`) и исходники CLI на TypeScript с тестами для каждого правила линтера. Рядом есть файлы с принципами проекта и правилами участия, набор тестовых DESIGN.md в каталоге фикстур и сборка в GitHub Actions. Главная страница показывает короткий пример файла, использование команд и таблицу правил.