AGENTS.md для дизайн-системи: щоб AI брав ваші токени

Знайома картина. Ви пів року збирали дизайн-систему: токени, компоненти, документація, все акуратно. Приходить розробник з Cursor або Claude Code, каже "зроби мені сторінку налаштувань" - і на виході отримує UI, у якому bg-blue-500, padding: 18px і власноруч зліплений <button>. Візуально майже схоже. Системно - повз усе.

Проблема не в тому, що модель дурна. Проблема в тому, що вона не знає про вашу систему нічого. Її дефолт - типовий Tailwind з мільйона репозиторіїв, на яких її вчили. І поки ви не скажете інакше, вона писатиме саме так.

Далі - як це фіксується. Не одним магічним промптом, а чотирма шарами, які ставляться за один робочий день.

Шар 1: AGENTS.md - місце, куди агент точно подивиться

AGENTS.md - це звичайний markdown-файл у корені репозиторію з інструкціями для AI-агентів. Формат виріс зі спільної роботи команд OpenAI Codex, Cursor, Amp, Google Jules і Factory, зараз ним опікується Agentic AI Foundation під Linux Foundation, і його читають понад 20 інструментів: VS Code, GitHub Copilot, Cursor, Claude Code, Aider, Zed, Gemini CLI та інші.

Два факти, які важливі саме для дизайн-системи:

• Виграє найближчий файл. Агент шукає AGENTS.md угору по дереву від файлу, який редагує. Тобто в монорепо можна покласти окремий файл у packages/ui/ - і правила дизайн-системи діятимуть тільки там, не заважаючи бекенду.
• Обов'язкових полів немає. Це просто markdown, будь-які заголовки. Тому не треба вигадувати схему - пишіть як для нового джуна в перший день.

Мінімальний файл для UI-пакета виглядає приблизно так:

Чотири рядки. Але вони закривають 80% типових промахів, бо тепер у агента є адреса, куди йти, і заборона, яку не можна тихо обійти.

Шар 2: DESIGN.md - окремо про візуал

AGENTS.md за традицією про інженерію: як зібрати, як тестувати, які конвенції коду. Візуальні правила там тонуть. Тому у 2026-му поруч з'явився DESIGN.md - той самий підхід, але про те, як продукт має виглядати: палітра, типографічна шкала, шкала відступів, радіуси, тіні, правила щільності і тон UI-копірайту.

Це поки не стандарт, а конвенція, яка швидко розходиться - але вона працює, бо агент читає обидва файли як звичайний контекст. Що туди варто покласти:

• Семантичні токени з призначенням, а не просто список змінних. Не "--color-accent: #A8FF57", а "--color-accent - лише для головної дії на екрані, максимум одна на в'ю".
• Типографічна шкала з реальними ролями: h1 / section / body / caption. Без цього агент вигадає власні розміри.
• Шкала відступів і жорстка заборона проміжних значень.
• Тон UI-текстів. Одне речення на кшталт "коротко, без окличних знаків, кнопки - дієсловом" економить години правок мікрокопі.

Правило обсягу просте: якщо ви пишете третю сторінку - ви робите щось не так. Довгий файл правил агент розмиває по контексту і починає ігнорувати.

Індекс компонентів: щоб агент не винаходив другий Button

Окремий рядок про те, що ламається найчастіше. Агент не бачить вашу бібліотеку цілком - він бачить лише ті файли, які встиг відкрити. Якщо у вас 60 компонентів, шанс, що потрібний DataTable потрапить йому на очі, невеликий. Тому він робить свій. Через місяць у вас чотири таблиці, і жодна не ваша.

Лікується списком на одну сторінку - прямо у файлі правил або окремим components.md поруч:

Один рядок на компонент, без опису пропсів - пропси агент прочитає з типів. Важлива саме колонка "коли": вона прибирає найдорожчу помилку, коли модель бачить компонент, але не розуміє, що це саме той випадок. І там же корисно писати заборони прямим текстом ("не збирай label + input окремо") - вони працюють краще за позитивні формулювання.

Шар 3: golden examples - код навчає краще за прозу

Це найнедооціненіша частина. Замість того, щоб описувати словами, як має виглядати правильний компонент, тримайте директорію на кшталт src/design-system/examples/ з кількома еталонними реалізаціями: форма, таблиця з порожнім станом, модалка, сторінка налаштувань.

Ключова вимога: ці приклади мають компілюватися і проганятись у CI. Тоді вони не протухають. Документація застаріває мовчки, а зламаний приклад падає збіркою - і ви про це дізнаєтесь того ж дня.

Механіка тут проста: у файлі правил ви пишете один рядок з посиланням на директорію, а всю решту роботи робить код. Агент відкриває приклад, бачить реальні імпорти, реальні токени, реальні пропси - і копіює патерн. Це набагато надійніше, ніж переказувати той самий патерн словами.

Шар 4: лінтери, які не залишають вибору

Інструкції - це прохання. Лінтер - це стіна. Агенти сприймають помилку компіляції як інструкцію до ремонту і самі себе виправляють, тому механічні правила працюють краще за будь-який промпт.

Три штуки, які дають найбільший ефект:

1. Stylelint на сирі значення. Забороніть hex, rgb і довільні px у стилях - лишіть тільки токени. Це різко звужує простір рішень: агенту більше не треба вгадувати, який саме синій.
2. ESLint no-restricted-imports. Закрийте legacy-папки і прямі імпорти внутрішніх файлів. Найважливіше - текст помилки: пишіть у ньому, звідки імпортувати правильно. Агент прочитає це повідомлення і полагодить сам.
3. Типи замість домовленостей. Якщо у вас variant="ghost" не поєднується з tone="danger", зробіть це неможливим на рівні типів через discriminated union. Тоді галюцинований стан компонента просто не збереться.

І фінальна петля: одна команда npm run verify:ui, яка ганяє типи, лінт і Storybook interaction tests. У AGENTS.md пишете, що без неї PR не відкривають. Агент запускає, бачить червоне, чинить - без вашої участі.

Чому правила іноді не спрацьовують

Файл є, а агент усе одно хардкодить кольори. Чотири причини, у такому порядку частоти:

• Файл завеликий. Три сторінки правил конкурують за увагу з рештою контексту, і частина просто губиться. Ріжте до списку, який читається за 30 секунд.
• Правила без адреси. "Використовуй наші токени" - це нічого. "Токени в src/tokens/semantic.css, приклад використання в examples/SettingsPage.tsx" - це вже інструкція, за якою можна піти.
• Два джерела правди в коді. Якщо половина продукту досі на старих стилях, агент чесно скопіює старий патерн - він же в продакшені. Спочатку прибирайте legacy або закривайте його лінтером, потім чекайте від агента чистоти.
• Немає зворотного зв'язку. Без лінта і типів модель не дізнається, що помилилася. Порушення, яке нічим не ловиться, повторюватиметься нескінченно.

Чого ці файли не роблять

Щоб не було завищених очікувань. Файли правил дають відповідність системі, але не дають хорошого дизайну. Ієрархія екрана, логіка кроків, що показати першим, коли даних нема - це все ще ваша робота. Агент з ідеальним AGENTS.md зробить системно чистий, але посередній екран, якщо в промпті не було задуму.

Друге: паритет з Figma ці файли теж не закривають. Якщо потрібно, щоб код відповідав конкретному фрейму піксель у піксель, це інший інструмент - MCP-сервер, який віддає агенту дані прямо з макета. Про це є окремий розбір нижче в "Читайте також", і кілька практичних прогонів я показував на YouTube-каналі UX Hero.

Третє: це не разова дія. Додали компонент - додайте рядок в індекс. Змінили правило - оновіть приклад. Файл правил, який відстав від коду на два місяці, шкідливіший за його відсутність, бо агент довіряє йому більше, ніж треба.

План на тиждень

• День 1. AGENTS.md у корені UI-пакета. Чотири правила, не більше.
• День 2. DESIGN.md: токени з призначенням, типографіка, відступи, тон текстів.
• День 3. Індекс компонентів: список того, що вже є, з однорядковим "коли використовувати".
• День 4. Два golden examples з реального продукту. Підключити їх у CI.
• День 5. Stylelint на токени + no-restricted-imports з підказкою в тексті помилки.
• День 6. Команда verify:ui і згадка про неї у файлі правил.
• День 7. Тест: дайте агенту задачу "зроби екран налаштувань" і порахуйте, скільки сирих значень він притягнув. Це ваша базова метрика на наступний місяць.

---

Суть в одному реченні: ваш кодбейс - це і є ваш промпт. Файли правил лише вказують агенту, куди дивитись, а вчиться він на тому коді, який у вас реально лежить. Тому найшвидший спосіб покращити результат AI - це навести лад у системі, а не переписувати промпт удвадцяте.