AGENTS.md — применить дизайн-систему KT AI (инструкция для ИИ-агента)

Это инструкция для ИИ-агента (Claude Code / Codex). Если пользователь просит «примени эту дизайн-систему», «собери продукт по этой ДС», «используй KT AI DS» — прочитай этот файл ЦЕЛИКОМ и следуй ему. Папка этой ДС далее — DS/ (папка, где лежит этот файл).

Железное правило (Definition of Done)

Экран продукта НЕ готов, пока он:

построен на ките/токенах KT AI (не вёрстка с нуля);
для списков / дашбордов / очередей / сравнений / чата — собран через продуктовый контракт, а не руками;
прошёл гейт: validate_product.py --strict = 0/0 И проход по DS/CHECKLIST.md глазами.

«Зелёный валидатор» ≠ «готово». Не объявляй экран готовым без прохода CHECKLIST.

⚠️ Если в проекте УЖЕ есть экран/прототип (частая ошибка!)

Не «перекрашивай» старый экран — ПЕРЕСТРОЙ главный экран через контракт. Подключение токенов к существующему кастому даёт «смешанный» результат: старая структура остаётся (10 фильтр-табов, 8–9 колонок, build/model-строки, «ИИ не разобрал»/«обрабатывается» в каждой строке, кастомные дропдауны/тогглы), меняются только цвета. Это НЕ применённая ДС — это перекраска.

Правильно для главного экрана данных:

собери config.json по контракту (DS/docs/PRODUCT_CONTRACT.md) из реальных данных проекта;
отрендери <KTAIShell><KTScreen contract={config}/></KTAIShell>;
удали старый компонент экрана — не патчь его. Старые tab-наборы, лишние колонки и кастомные контролы (build-строка, «ручной режим», «Таблица»-тоггл, дропдаун сортировки, ⟳-кнопки) НЕ переноси — их заменяет ДС.

Не оставляй два «дизайна» рядом. Если экран не построен через контракт — он не прошёл п.2 Железного правила.

Шаг 1 — прочитай канон (в этом порядке)

DS/README.md → DS/docs/GOAL.md → DS/docs/PRINCIPLES.md + DS/docs/ELEVENLABS_DESIGN.md (почему так) → DS/docs/DESIGN.md + DS/COMPONENTS.md (чем строить) → DS/docs/PRODUCT_CONTRACT.md + DS/docs/ARCHETYPES.md (контракт) → DS/CHECKLIST.md (гейт, по которому принимаешь).

Шаг 2 — выбери РАНТАЙМ под стек проекта (ДС двухрантаймовая!)

Один контракт — два рантайма. Сначала определи стек проекта, потом бери рантайм:

React / Next.js / npm → React-кит (DS/templates/kt-ai-shadcn/). Установка (см. DS/templates/kt-ai-shadcn/PROTOTYPING_WORKFLOW.md): из папки кита python3 -m http.server 4188, в проекте npx shadcn@latest add http://127.0.0.1:4188/r/kt-ai-starter.json. Даёт токены/тему, типы, KTScreen+KTAIShell, иконки. Рендер: <KTAIShell><KTScreen contract={config}/></KTAIShell>.
Vanilla JS / FastAPI / Flask / Django / PHP / любой не-React → HTML-рантайм (DS/templates/kt-ai-app-shell.html). Это самодостаточный HTML/CSS/JS-app-shell, гидрируется JSON-конфигом: контракт кладётся в <script id="kt-app-config" type="application/json">…</script>, скрипт сам читает CFG = JSON.parse(...) и рендерит весь экран (очередь, KPI, drawer, темы). React/npm НЕ нужны.
- Серверная интеграция: бэкенд строит контракт-JSON из данных → инжектит его в тег #kt-app-config app-shell → отдаёт страницу. Логику инжекта можно взять из DS/scripts/build_prototype.py (он делает ровно это).
- CSS/спрайт/feedback.js инлайнятся в app-shell один раз (как делает build_prototype.py), дальше per-request меняется только конфиг.

В обоих случаях источник правды — один и тот же config.json по DS/docs/PRODUCT_CONTRACT.md.

Шаг 3 — строй экраны через контракт

Список / дашборд / очередь / сравнение / чат → собери config.json по DS/docs/PRODUCT_CONTRACT.md (+ DS/product.schema.json), выбери архетип по DS/docs/ARCHETYPES.md. Отрендери выбранным рантаймом (React <KTScreen> или HTML-инжект конфига). Структура, поведение и стиль приходят разом — не верстаешь руками.
Нестандартный экран → на компонентах/токенах по DS/docs/DESIGN.md + DS/COMPONENTS.md.

Шаг 4 — гейт (обязателен на КАЖДОМ экране)

Есть контракт → python3 DS/scripts/validate_product.py <config>.json --strict → должно быть 0/0.
Всегда → пройди DS/CHECKLIST.md (G0–G8) глазами в обеих темах и на узком экране.

Жёсткие правила (то, что чаще всего ломают)

Цвета/размеры — только var(--kt-ai-*), не сырой hex. Значения правятся в DS/tokens.json.
Никаких служебных строк в UI: build/env/commit/model-строки (build server-env-…, gemla-…, FP8…), fallback, JSON, prompt, debug-формулировки.
Первичных фильтр-табов ≤ 4 + «Все» (закон Хика). 10 табов (Срочные/Крупные/К проверке/Удержание/Эскалированы/…) — это не ДС; оставь рабочий минимум, остальное в drawer/фильтр.
Колонок мало и по делу (обычно 5–6, не 8–9). Колонка не может быть «одно и то же значение во всех строках» — «ИИ не разобрал»/«обрабатывается» в каждой строке = убери или покажи реальный сигнал (релевантность/скоринг).
Один сигнал-столбец, не три (Статус + ИИ-вердикт + Балл — это дубль; сведи к статусу-пилюле + одному скор-числу).
Даты — ДД.ММ.ГГГГ, время чч:мм; не сырой ISO, без мусорных 00:00:00/09:00:00.
Дубли строк — дедуп. Один primary на экран. Статус — пилюлей, не цветом текста. Create-кнопки с ведущим «+».
Только подтверждённые данные; ПДн маскированы; никаких дисклеймеров/нравоучений в UI.
Один фильтрующий поиск на экран; AI-кнопка Төре — в топбаре у поиска.

Чтобы применялось в КАЖДОЙ сессии автоматически

Добавь в CLAUDE.md проекта пользователя одну строку:

UI собирается по дизайн-системе KT AI: следуй design-system/AGENTS.md. Экран не готов без validate_product.py --strict (0/0) и прохода CHECKLIST.md.

Тогда правила в контексте каждой сессии Claude Code, без напоминаний.

8.6 KiB Raw Blame History Unescape Escape