Как обучить ИИ-агентов писать чистый CSS: Google Modern Web Guidance, архитектура дизайн-токенов и тесты в Playwright

Как обучить ИИ-агентов писать чистый CSS: Google Modern Web Guidance, архитектура дизайн-токенов и тесты в Playwright

Генеративный ИИ стал привычным инструментом разработки, но качественная верстка остается для кодинг-агентов непростой задачей. Модели обучались на массивах архивного кода, поэтому по умолчанию воспроизводят устаревшие приемы: громоздкие скрипты для модальных окон вместо нативного тега <dialog>, хаки с соотношениями сторон вместо свойства aspect-ratio или слушатели изменения размера окна вместо современных медиавыражений.

Чтобы направить ИИ-помощников к современным стандартам веб-платформы, команда Chrome запустила экспериментальный проект Modern Web Guidance. Однако практический опыт показывает: одних платформенных рекомендаций мало. Без проектной системы дизайн-токенов и скриншотного тестирования сгенерированный код рискует нарушить визуальный стиль или сломаться в старых браузерах.

Что такое Modern Web Guidance и как устроен поиск

Modern Web Guidance — это набор специализированных навыков (skills) для автономных ИИ-агентов. База знаний содержит 103 руководства по технологиям веб-платформы и 131 практический сценарий использования.

Вместо загрузки всей документации в контекст модели реализован интерфейс командной строки (CLI):

1. Агент формулирует запрос (например, по анимации диалогов или стилизации popover).
2. Утилита ранжирует статьи по сходству и возвращает список идентификаторов.
3. Модель запрашивает только конкретный документ, получая точные примеры нативного HTML и CSS.

Руководства опираются на стандарт Baseline, отражающий поддержку технологий браузерами. Статус Newly available указывает на совместимость со всеми основными браузерами (Chrome, Edge, Firefox, Safari), а Widely available присваивается спустя 30 месяцев после этого рубежа, подтверждая безопасность использования без полифилов.

Почему платформенных стандартов недостаточно

Хотя Modern Web Guidance отлично подсказывает нативные API (например, @starting-style, функцию light-dark() или container queries), оно изолировано от конкретного приложения:

• База знаний не знает цветов бренда, сеток отступов и типографики проекта.
• Платформенные советы не учитывают соглашения о каскадных слоях (@layer).
• Общий стандарт не знает целевую матрицу браузеров ваших пользователей: если требуется поддержка старых систем, слепое внедрение новинок приведет к поломкам.

Требуется четкое разделение зон ответственности между стандартами, правилами и тестированием.

Разделение зон ответственности в агентной разработке

Трехуровневая архитектура дизайн-токенов

Чтобы агент не вставлял произвольные цвета и «магические числа», настраивается трехуровневая система CSS-переменных:

1. Примитивные токены (--p-*): хранят сырые базовые значения палитры (например, --p-color-brand-500: oklch(45% 0.23 270)). Компоненты к ним напрямую не обращаются.
2. Семантические токены (--s-*): задают роль элемента в интерфейсе и связываются с темами (--s-color-brand-primary: light-dark(var(--p-color-brand-500), var(--p-color-brand-300))).
3. Компонентные токены (--c-*): определяют точечные стили элементов с обязательным запасным значением (fallback) на семантический токен.

@layer tokens {
  :root {
    --p-color-brand-500: oklch(45% 0.23 270);
    --p-color-brand-300: oklch(85% 0.15 210);
    --s-color-brand-primary: light-dark(
      var(--p-color-brand-500), var(--p-color-brand-300)
    );
    color-scheme: light dark;
  }
}

@layer components.button {
  .button--primary {
    background: var(--c-button-background, var(--s-color-brand-primary));
  }
}

Такая структура позволяет модели настраивать отдельные элементы, не нарушая дизайн-систему сайта.

Алгоритм работы кодинг-агента

Взаимодействие с моделью строится по строгому сценарию:

1. Контекст проекта: агент считывает матрицу браузеров, слои @layer и правила именования токенов.
2. Запрос стандарта: через CLI извлекается профильное руководство Modern Web Guidance.
3. Генерация стилей: значения заменяются семантическими токенами, стили изолируются в @layer, верстка строится на нативном HTML.
4. Фолбеки: декоративные улучшения оформляются через progressive enhancement, а критические свойства снабжаются проверками @supports.
5. Валидация: результат проходит проверку доступности и визуальные тесты.

Установка и настройка окружения

Для интеграции базы знаний используется официальный пакет:

npx modern-web-guidance@latest install

Поиск и загрузка руководств выполняются командами:

npx modern-web-guidance@latest search "animate dialog modal"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

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

export DISABLE_TELEMETRY=1

Автоматическое тестирование верстки в Playwright

Для защиты от визуальных деградаций настраиваются скриншотные тесты во фреймворке Playwright:

import { test, expect } from '@playwright/test';

test('card layout is preserved in compact mode', async ({ page }) => {
  await page.setViewportSize({ width: 390, height: 844 });
  await page.goto('/components/card?density=compact');
  await expect(page.getByRole('heading')).toBeVisible();
  await expect(page).toHaveScreenshot('card-compact.png', {
    maxDiffPixels: 100,
  });
});

Первый запуск создает эталонный снимок (golden screenshot). При последующих прогонах тестовый раннер сравнивает рендеринг с эталоном. При запланированном обновлении дизайна снимки актуализируются командой npx playwright test --update-snapshots.

Чек-лист проверки перед коммитом

Перед слиянием кода, созданного ИИ-ассистентом, проверяется:

• Решения соответствуют целевому статусу Baseline и матрице проекта.
• Интерактивность построена на нативных тегах (<button>, <dialog>), проверен фокус и навигация с клавиатуры.
• Все стили используют семантические токены без прямого вызова примитивов.
• Для критических свойств прописаны фолбеки через @supports.
• Учтены предпочтения доступности (prefers-reduced-motion и контраст).
• Визуальные тесты в Playwright успешно пройдены.