Дизайн-система как ТЗ для агента: шесть итераций магазина SexyGram

Обычное задание для агента звучит так: «сделай магазин, вот референс». Дальше агент достраивает недостающее из среднего по интернету — и получается витрина, которую вы уже видели сто раз. Я попробовал зайти с другой стороны: сделать дизайн-систему источником истины и снять с неё спецификации, на которые агент может ссылаться построчно. Проект — SexyGram, репозиторий ragastar/sexygram.

Почему макет сам по себе плохое ТЗ

Агент отлично пишет код по описанию состояния. Он плохо угадывает намерение. Фраза «карточка товара как на макете» не содержит ни отступов, ни радиусов, ни поведения на 390px. Агент подставит дефолты фреймворка, и вы будете три итерации объяснять, что кнопка должна быть pill, а тень мягче.

Дизайн-система закрывает этот разрыв, потому что описывает состояния явно. Токены, сетки, компоненты, темы — всё это уже формализовано. Остаётся одно: заставить агента читать систему как текстовый документ. Картинку он всё равно додумает.

Что было на входе

Источник дизайна — папка Система дизайна интернет-магазина/design_handoff_sexygram/. Внутри HTML-холст SexyGram-design-system.dc.html на 14 разделов плюс README-хэндофф. Холст интересен тем, что это живой прототип с инлайн-стилями: значения лежат прямо в разметке, их можно снять дословно.

В прототипе три визуальных направления:

• 1a — «Неон-поп», светлая тема, основное направление
• 1b — «Тёмная витрина», золото как премиум-акцент
• 1c — «Тёплый минимал»

Шесть спек вместо одного брифа

Из холста я снял шесть документов — docs/specs/01..06. Каждый закрывает свой слой: базовая система (Foundation), десктоп-витрина, мобильные экраны, админка, кабинет клиента, письма.

Главное правило при их написании — у любого значения есть адрес. Формулировка «фон карточки светлый» не годится. В спеке стоит «design/SexyGram-design-system.dc.html, строки 1701–2183». Спека 02 по десктоп-витрине ссылается на строки 1241–1700, где живут разделы 2a и 2b. Агент может открыть файл и проверить себя, вместо того чтобы верить моему пересказу на слово.

Второе правило важнее первого. Всё, чего в прототипе нет, помечено фразой «не задано в прототипе». Это единственный способ отличить решение дизайнера от пробела. Пересказ агент дополняет фантазией молча. Явная пометка заставляет его остановиться и спросить.

Расхождения всплывают до кода

Самый полезный побочный эффект: при снятии спек нашлось расхождение. README описывал два направления, на холсте их оказалось три — «Тёплый минимал» в README отсутствовал полностью. Я вынес это отдельным блоком «Расхождения с README» прямо в спеку 01.

При обычном подходе такая штука вылезает на ревью, когда полвитрины уже собрано. Здесь она стоила абзаца текста.

Порядок коммитов

План реализации — монолит на Next.js 15 App Router, SSR/SSG для публичных страниц, Prisma и Postgres для данных. Порядок работы видно по истории от 2 августа:

1. каркас витрины и главная
2. страница товара — галерея, блок «Что внутри», варианты, липкая панель
3. корзина, чекаут, кабинет, блог, лендинг и стыковка каркаса
4. каталог с фильтрами — сайдбар, сетка, мобильная шторка
5. подключение Postgres: витрина переехала с фикстур на базу
6. подготовка к переносу на VPS
7. авторизация — вход, регистрация, роли, тестовые учётки

Логика простая: сначала визуальный слой на фикстурах, потом данные, потом доступы. Пока витрина живёт на фикстурах, агент правит вёрстку без риска сломать схему БД. Когда пиксели совпали со спекой, подключается Postgres — и дальше отладка идёт только по данным.

Это и есть шесть итераций: шесть слоёв спецификации, каждый следующий опирается на закрытый предыдущий.

Что я бы поменял

Спеки писались после холста, и на это ушло заметное время. В следующий раз попробую снимать их сразу при сборке прототипа — прототип и спека делаются одним проходом, пока значения ещё в голове.

Второе: пометку «не задано в прототипе» стоит превратить в жёсткое правило для агента — «встретил такую пометку, остановись и задай вопрос». В первой итерации это работало на честном слове, и пара мест всё-таки была достроена по вкусу модели.

Вывод

Дизайн-система работает как ТЗ ровно в той мере, в какой она адресуема. Картинка — плохой контекст. HTML-прототип с инлайн-стилями и спека со ссылками на строки — хороший: агент проверяет себя сам, а разговор с ним идёт про конкретные расхождения. Вкусовщина из обсуждения уходит.