Интерфейс по описанию и скриншотам

Интерфейс — место, где вайбкодинг работает лучше всего: результат видно сразу, а ошибка в отступе не уронит базу. Но и здесь агент без ориентиров делает «средний» интерфейс из обучающих данных, а без возможности посмотреть на результат — ещё и сломанный на телефоне. Делаем экран недельного расписания (пункт 4 плана) и разбираем, как дать агенту и описание, и глаза.

Сначала словарь интерфейса

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

:root {
  --color-bg: #ffffff;
  --color-text: #1f2328;
  --color-muted: #6e7781;
  --color-accent: #0b6bcb;
  --color-busy: #fde2e1;
  --color-mine: #dbeafe;
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 16px;
  --radius: 8px;
  --font: system-ui, sans-serif;
}

И строка в AGENTS.md: «Цвета, отступы и радиусы — только переменные из apps/web/src/ui/tokens.css; новые значения не вводить без просьбы». Если у компании есть дизайн-система или макет в Figma, токены берутся оттуда.

Описание словами

Хорошее описание экрана перечисляет не только то, что на нём есть, но и состояния. Агент почти всегда делает «счастливый путь» и забывает про пустой список, загрузку и ошибку.

Экран «Неделя» для комнаты: apps/web/src/pages/RoomWeek.tsx.

Структура: сверху название комнаты, вместимость, переключатель недель
(← неделя →, кнопка «Сегодня»). Ниже сетка: столбцы — дни пн–пт,
строки — 15-минутные слоты с 08:00 до 21:00, подписи каждый час.
Брони — блоки поверх сетки: название и автор. Свои брони — --color-mine,
чужие — --color-busy. Клик по свободному месту открывает форму брони
с предзаполненным временем.

Состояния: загрузка (скелетон сетки), ошибка API (сообщение и «Повторить»),
неделя без броней, очень длинное название встречи (обрезать с многоточием,
полный текст в title), архивная комната (сетка без возможности брони).

Узкий экран (до 768px): один день и переключатель дней вместо недели.
Доступность: блоки броней — кнопки с понятным aria-label, работает Tab.
Только токены из tokens.css, без новых зависимостей.

Эскизы и скриншоты

Картинка часто короче абзаца. Codex принимает изображения: в CLI их можно вставить в поле ввода или передать при запуске.

codex -i docs/sketches/week.png "Сверстай экран RoomWeek по эскизу. Требования — в моём следующем сообщении."

Что работает как вход:

• Эскиз от руки или в любом редакторе — для структуры. Агент не будет копировать «кривые линии», он поймёт сетку.
• Экспорт макета — для точной вёрстки. Указывайте, что важно: «отступы и иерархия как в макете, цвета — из токенов».
• Скриншот текущего состояния с пометками — для правок. Обведите проблему и подпишите: это точнее, чем «кнопка какая-то не такая».

Дайте агенту увидеть результат

Агент, который не видит отрисованную страницу, проверяет вёрстку только компиляцией. Есть несколько способов замкнуть цикл.

Встроенный браузер в ChatGPT desktop app. В режиме Codex браузер открывает локальный адрес рядом с диффом. В нём можно оставлять пометки прямо на элементах и просить агента их учесть, а упоминание @Browser в задаче даёт агенту самому открыть страницу и воспроизвести проблему. Документация советует держать каждую такую задачу достаточно маленькой, чтобы проверить её за один проход.

Playwright MCP. Подключается одной командой и даёт агенту управлять браузером из CLI:

codex mcp add playwright -- npx -y @playwright/mcp@latest

Сервер работает с деревом доступности страницы, а не с пикселями. Подробнее о MCP — в уроке курса по настройке.

Скриншоты по матрице разрешений. Самый надёжный вариант для регулярной проверки — тест, который снимает экран на нескольких ширинах:

import { test } from "@playwright/test";

const widths = [360, 768, 1440, 2560];

for (const width of widths) {
  test(`неделя комнаты, ${width}px`, async ({ page }) => {
    await page.setViewportSize({ width, height: 900 });
    await page.goto("/rooms/1/week?date=2026-10-19");
    await page.getByRole("grid").waitFor();
    await page.screenshot({ path: `e2e/screens/week-${width}.png`, fullPage: true });
  });
}

Снимки вы просматриваете сами или отдаёте агенту обратно через -i с вопросом «что здесь сломано». Узкие и очень широкие экраны ломаются чаще всего — длинная сетка на 4K растягивается, на 360px вылезает за край.

Важная оговорка из документации: содержимое страниц, которые открывает агент, — недоверенные данные. На своём localhost это не страшно, но не давайте агенту бродить по внешним сайтам в той же сессии, где у него есть доступ к коду и секретам.

Где в интерфейсе читать код

Вёрстку достаточно проверять глазами и тестами. Читать стоит одно: не переехала ли бизнес-логика только в интерфейс. Агент охотно блокирует в форме слоты длиннее 4 часов и на этом успокаивается. Правило R1 должно проверяться в API — интерфейс лишь подсказывает пользователю. Простой тест: отправьте запрос с пятичасовой бронью через curl в обход формы.