Статичная спека
Дизайнер меняет токен или вариант компонента в Figma. В документе остаётся прежнее описание, но внешне ничего не выдаёт расхождение. Чтобы заметить его, читателю приходится сверять два источника.
Design Docs · Личный R&D · 2026
Дизайн изменился. Какие спецификации теперь нужно проверить?
Я собрал прототип, который находит изменения в данных Figma и показывает, какие документы они затрагивают.
Непроверенная спецификация получает предупреждение, а подтверждение автора относится к конкретной версии изменения.
Кейс за минуту
Подробнее о результате ↓- Моя роль
- Соло R&D: спроектировал состояния документа, правила ревью, артефакты и собрал систему.
- Ключевое решение
- Разделил обновление данных и подтверждение документа: факты собирает код, текст проверяет человек.
- Результат
- Проверил сравнение слепков, предупреждения и подтверждение конкретной версии на собственной дизайн-системе.
design-docs / sync демонстрация
python -m docgen sync --fixture fixtures/demo-token-change.json
extract: слепок Figma → 55 variables, 12 text styles
normalize: имена токенов совпадают с источником
diff: найдено 1 изменение
color/success #237804 → #15803d
помечаю stale → tokens.md
notify:telegram отправлено
ожидаю проверку человека...
CHANGE#237804 → #15803d STATEactual → stale → actual GATEпроверка человека
01 Что проверено
Документ больше не выглядит проверенным по умолчанию.
В пилоте изменение токена попадает в отчёт, связанный документ получает предупреждение, а устаревшая кнопка подтверждения отклоняется. CSS-токены можно экспортировать из того же слепка отдельно.
Рабочий R&D-прототип на моей дизайн-системе: 14 документов, 12 компонентов и 55 переменных. В команде его ещё не использовали.
02 Проблема
Дизайн изменился, а документ всё ещё выглядит актуальным.
Перезапись не равна проверке
Автоматически обновить таблицу можно. Объяснение поведения компонента всё равно требует внимания автора, особенно если черновик написала модель. Новая дата на странице не означает, что этот текст кто-то проверил.
03 Доказательства · от правки до проверки
Одна синхронизация превращает правку в проверяемый пакет изменений.
В первом сценарии меняется только color/success. По нему видно, как система обнаруживает правку, предупреждает читателя и принимает подтверждение.
01Источник
Дизайнер меняет токен в Figma как обычно.
После правки дизайнер получает слепок через плагин Figma и запускает синхронизацию. Система сравнивает его с предыдущим.
02Факт
Система фиксирует одно изменение токена.
Код сравнивает значения color/success в двух слепках. Изменение и список затронутых документов определяются без участия модели.
03Код
Тот же слепок становится CSS-токенами.
Отдельная команда формирует tokens.css для Storybook. Экспорт переносит значения токенов, но не проверяет соответствие всего интерфейса макету.
04Сигнал
Предупреждение видно до содержимого документа.
Документ остаётся доступным в Notion. Предупреждение в начале страницы показывает читателю, что после изменения в Figma его ещё не проверили.
05Ревью
Проверка привязана к конкретному изменению.
Дизайнер проверяет документ по пакету изменений из сообщения. Если следующая синхронизация создаст новый пакет, кнопка из старого сообщения больше не сработает.
06Результат
После проверки документ снова становится актуальным.
После ревью автор подтверждает актуальный пакет. В Markdown сохраняется статус документа, а в журнале остаётся запись о проверке. Это подтверждение документа, не разрешение на выпуск кода.
Прогон B · крупное изменение
Отдельный прогон проверяет несколько типов изменений.
Во втором демонстрационном сравнении система нашла 18 изменений и отметила 9 документов для проверки. Среди изменений 8 новых компонентов и 9 новых использований. Этот прогон не продолжает историю с одним токеном.
Зачем проверять текст модели
Модель назвала Page Button — кнопку пагинации — «компонентом для CTA».
Такой черновик создаётся со статусом «устарело». Если опубликовать его в Notion до ревью, читатель увидит предупреждение. Статус не блокирует доступ к тексту и не исправляет ошибку: он показывает, что автор ещё не подтвердил содержание.
04 Архитектура
Машинные данные и авторский текст обновляются по-разному.
Из JSON-слепка код собирает таблицы вариантов и использования. Авторские описания сохраняются, чтобы следующая генерация не затёрла вручную написанные пояснения. Если данные изменились, документ получает статус «устарело» и ждёт ревью. Markdown хранится в git, а Notion показывает его опубликованную копию.
извлечь→
собрать→
опубликовать→
сравнениеСлепок изменился со времени прошлой синхронизации?затронутые документы помечаются «устарело» · изменения уходят в CHANGELOG
Код
извлекает и рендерит факты детерминированно
Модель
пишет changelog и черновики новых спек
Человек
единственный, кто снимает статус «устарело»
Дисциплина сигнала
Нет изменений — нет сообщения.
Если сравнение не нашло изменений, новый дайджест не отправляется. Так повторная синхронизация не добавляет одинаковые сообщения в чат.
Защита от устаревшего подтверждения
Старая кнопка не подтверждает новую правку.
Я привязал подтверждение к ID пакета, а не только к названию документа. Иначе человек мог бы открыть сообщение, отвлечься и подтвердить уже другую версию. Если синхронизация создала новый пакет, система отклонит кнопку из предыдущего.
18изменений в большом сравнении
9документов в составе
2ID слепка
1проверка человека
05 Проба моделей · 3 наблюдения
Проба моделей показала, почему черновик нужно проверять.
Проверял две задачи: запись в changelog и введение к спеке. Gemma 4 домыслила причину смены цвета, Claude отметил подозрительную привязку токена, Qwen 3.6 не запустилась. Это отдельные наблюдения, не сравнительный бенчмарк: ответ Claude получен в рабочей сессии, воспроизводимого API-прогона пока нет.
Входные изменения
color/success: #237804 → #2d8f06 · новый Status Tag · Button Primary/HoverGemma 4
9,6 ГБ · локально · режим черновика
Changelog
Значения из diff сохранены, но вместо 1–2 предложений получился пост с заголовками и эмодзи.
Введение к спеке
7 с · пригодно для черновика, но с лёгкой водой.
Что важно
Домыслила мотивацию: «обеспечит лучшую контрастность» — этого не было во входных данных.
Qwen 3.6
23 ГБ · локально · рабочая станция
Changelog
llama-server не смог выделить дополнительные 9,9 ГБ CUDA_Host buffer.
Введение к спеке
До второй задачи не дошла: модель не запустилась.
Что важно
После выгрузки Gemma 4 модель всё равно не поднялась: рабочей станции не хватило памяти.
Claude
облако · режим проверки
Changelog
Соблюла формат и заметила: смена Button hover с primary-hover на primary-bg похожа на ошибку биндинга.
Введение к спеке
Коротко описала роль и устройство Status Tag.
Что важно
Предложила проверить смену токена hover у автора изменения.
06 Артефакты · форма документации — тоже дизайн
Из одного слепка получаются разные рабочие артефакты.
CSS-токены используются в Storybook. В документах рядом с машинными таблицами остаются пояснения автора, а в чат приходит список изменений со ссылками на страницы.
07 Сценарий для команды
У каждого участника свой следующий шаг.
Пока инструмент использовал только я. Для командной проверки предусмотрел такой сценарий:
Дизайнер
Получает свежий слепок Figma и запускает синхронизацию. Проверяет черновик модели, дописывает поведение и правила применения.
Разработчик
Получает CSS-токены из слепка. Перед чтением спеки видит, проверена ли она после последнего обнаруженного изменения.
Лид
Получает дайджест со списком затронутых документов. По нему можно выбрать, что проверить, не перечитывая всю документацию.
08 Ограничения и рефлексия
Пилот подтвердил работоспособность механики, но не командный эффект.
Что уже работает
Извлечение из Figma, структурированное сравнение, пакет изменений, статусы «актуально» и «устарело», генерация артефактов, Telegram-дайджест и проверка на пилоте.
Что ещё нужно проверить
Воспроизводимый API-прогон с фиксированными версиями моделей, полевая проверка с участием разработчика, экспорт изображений в документы и командное внедрение на одном разделе.
Полный слепок получаю через плагин.
В пилоте слепок передаётся системе отдельным файлом. REST используется для проверки версии Figma. Полностью автоматическое получение свежих данных ещё не настроено.
Публикация в Notion может прерваться.
В прототипе содержимое страницы очищается и записывается заново. При сбое между этими шагами возможна неполная публикация. Это ограничение текущего способа обновления.
Подтверждение из чата работает в Telegram.
Бот получает нажатия без публичного callback URL. Интерактивные кнопки в Slack и Mattermost пока не подключены.
Что остаётся локальным
Локальная модель позволяет не отправлять данные дизайн-системы облачному провайдеру при генерации текста. Notion и Telegram остаются внешними сервисами, поэтому такой режим сам по себе не делает весь процесс локальным.
Вывод
Изменение обнаружено, документ предупреждает читателя, проверка относится к конкретной версии.
Следующий шаг — дать инструмент разработчику на одном разделе дизайн-системы. Проверил бы, замечает ли он предупреждение и понимает ли, что изменилось. Затем внёс бы две последовательные правки и проверил, понятно ли автору, почему старая кнопка подтверждения больше не работает.
