Rakhiya bcd9c37690 v1 — ТЗ на кафе правильного питания (12 разделов, шаблоны под цифры)

2026-09-25 09:57:48 +00:00

41 KiB

Raw Blame History

KT AI Design System v3.0 «Mono» (токены v5)

Канон дизайн-системы KT AI. v3.0 от 2026-06-21 – визуальный язык в духе ElevenLabs: light-first, тёплый near-white фон, near-black primary-кнопка (в dark инвертируется в near-white), плоские поверхности на hairline-границах и шёпот-тенях, крупные жирные тёмные заголовки, цвет – только функциональный (статусы, чарты, единичная AI-искра орба Төре). Синий демотирован в ссылки/фокус/идентичность KT, перестал быть цветом primary-действия. Геометрия и Attio-детали (rounded-rect теги, frameless-таблицы с горизонтальными разделителями рядов — без вертикальных колонок-сепараторов, property-rows) сохранены; aurora-свечение карточек и тяжёлые AI-ореолы убраны. История: CHANGELOG.md. Анатомия shell/таблиц/рядов: COMPONENTS.md. Продуктовый контракт прототипа: PRODUCT_CONTRACT.md.

Файлы:

Файл	Роль
`tokens.json`	ЕДИНСТВЕННЫЙ источник значений токенов. Правки только здесь
`scripts/build_tokens.py`	генератор: tokens.css, print.css, figma-variables.json, tailwind-preset
`kt-ai-tokens.css`	AUTOGENERATED: переменные, обе темы, @layer kt-tokens
`kt-ai-print.css`	AUTOGENERATED: @media print (light, A4, скрытие shell)
`figma-variables.json`	AUTOGENERATED: импорт в Figma Variables (dark/light)
`kt-ai-tailwind-preset.cjs`	AUTOGENERATED: preset для Next.js/kt-ai-shadcn
`kt-ai-components.css`	компоненты v2 на токенах, имена классов совместимы с v1
`COMPONENTS.md`	нормативная анатомия shell, таблиц, рядов, тулбаров (перенос из v1-архива)
`showcase.html`	живая галерея всех компонентов с переключателем тем – открыть в браузере
`icons/kt-ai-lucide-sprite.svg`	локальный monochrome Lucide-sprite
`COMPONENTS.md`	правила компоновки экрана (активно)
`ELEVENLABS_DESIGN.md`	эталон эстетики/плотности/деталей (язык ElevenLabs)
`archive/`	замороженный v1 (kt_design_system, DESIGN_v1_archive, kt_ai_terminal_tokens.css, kt_ai_terminal_routes, kt_ai_atomic_product_system) – только история, вынесен в `08_Дизайн-система_история/archive/`

Брендовые ассеты: 03_База знаний/Логотипы и бренд/ (ktai.svg, kt-logo.svg).

Принципы

Полный контракт UX-принципов (Нильсен, гештальт, законы взаимодействия): PRINCIPLES.md. Единый чек-лист «прошло или нет» (Definition of Done, прогонять при любом изменении UI): CHECKLIST.md. Оба обязательны при проектировании.

Плотный операционный интерфейс: первый экран – рабочая поверхность, не лендинг.
Плоские поверхности на hairline-границах: в light – лёгкая тень (card-shadow/shadow-sm) + рамка, в dark – рамка без тени. Полновесные тени – только у overlay (modal, drawer, dropdown, command, toast). Никаких декоративных свечений/градиентов в контенте. Blur – только на sticky-хроме (топбар bg-glass) и overlay.
Тихие границы, приглушённые метаданные, один primary-акцент на экран.
Mono-доминанта. Primary-действие – монохром: primary = near-black (light) / near-white (dark), белый/тёмный текст. Синий (link, focus, brand-blue) – ссылки, фокус и идентичность KT, не заливка кнопок. AI-градиент (ai-gradient) – единичная сдержанная искра только на орбе Төре, send-кнопке и кромке prompt-bar в фокусе; тяжёлые ореолы и aurora-свечение карточек убраны. Остальные цвета – только статусы, чипы и графики.
Геометрия компонентов не зависит от темы: темы меняют только цвет.
Никаких сырых hex в продуктовом CSS – только semantic-токены.

Архитектура токенов

Три уровня, имена v1 (--kt-ai-*) полностью сохранены – старые продукты работают без правок.

Primitives (--kt-blue-500, --kt-gray-900, --kt-green-a22...) – сырая палитра и шкалы. В продуктах напрямую НЕ используются.
Semantic – смысловые роли, переключаются темой:
- поверхности: --kt-ai-bg, -bg-soft, -bg-elevated, -bg-sunken;
- state-слои: -bg-hover, -bg-active, -selection;
- текст: -fg, -fg-muted, -fg-faint, -fg-on-fill;
- границы: -border, -border-strong, -divider;
- интерактив: -primary, -primary-hover, -primary-subtle, -link, -danger, -danger-hover;
- фокус: -focus-ring, -focus-shadow;
- статусы/чипы/чарты: как в v1;
- тени: -shadow-sm/md/lg/xl.
Component – размеры контролов: --kt-ai-control-h-sm/md/lg (28/32/40), layout-переменные v1.

Тема-независимые шкалы (в :root):

Spacing --kt-ai-space-1..12: 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64. Всё на 4px-сетке, плотный низ шкалы.
Типографика --kt-ai-text-2xs..3xl: 11, 12, 13, 14, 15, 18, 26, 32. Body = 13px (text-sm). Веса 400/500/600/700. Числа – JetBrains Mono с tabular-nums.
Трекинг зависит от размера (не одно значение на всё): крупные заголовки — отрицательный (-.02em дисплей, -.01em H1/H2), body — около 0. Тесним заголовки, body оставляем нейтральным.
Leading обратно размеру: плотный на крупных заголовках (leading-tight 1.25), свободнее на body (leading-normal 1.5). Иерархия строится связкой вес+размер+leading, а не размером одним.
Радиусы (значения — в tokens.json, scales.radius): xs, sm, md, tag, lg, xl, 2xl, 3xl, full. Nav-ряды lg; кнопки/инпуты xl; карточки, modal, command, prompt-bar – 3xl; теги/статусы – tag (rounded-rect, не pill).
Моушн --kt-ai-dur-fast/base/slow/slower (100/160/240/400ms), easing standard/enter/exit. prefers-reduced-motion обнуляет длительности автоматически.
Z-index: sticky 20, dropdown 30, drawer 40, modal 50, toast 60, tooltip 70.

Темы

Light – дефолт (:root, data-theme="light" или kt-ai-terminal-light): тёплый near-white, near-black primary – основной офисный вид (v3 «Mono», light-first). Dark – полноправный паритетный вариант (data-theme="dark" или kt-ai-terminal): near-black фон, primary инвертируется в near-white. data-theme="auto" следует за системной темой.

Правила паритета:

каждый semantic-токен определён в обеих темах; добавил токен в dark – обязан добавить в light;
интерактивный синий: dark #4b9ce2, light #0077c8 (AA-контраст на своих фонах); фирменный KT blue #0096d7 общий;
статусные пары построены зеркально: в dark светлый текст на прозрачной подложке, в light тёмный текст на прозрачной подложке;
проверка паритета – переключателем в showcase.html, это обязательный QA-шаг.

Компоненты (kt-ai-components.css)

Имена классов v1 сохранены (.kt-ai-card, .kt-ai-row, .kt-ai-chip, .kt-ai-nav-item, .kt-ai-table*, .kt-ai-search, .kt-ai-kbd, .kt-ai-icon-button, .kt-ai-segmented...). Новое в v2:

Кнопки .kt-ai-btn: варианты data-variant="primary|ghost|danger" (без атрибута – вторичная), размеры data-size="sm|lg". Один primary на экран.
Формы: .kt-ai-field (label + контрол + hint/error), .kt-ai-input, .kt-ai-select, .kt-ai-textarea, data-invalid="true", .kt-ai-checkbox, .kt-ai-switch. Фокус: border primary + --kt-ai-focus-shadow.
Tabs .kt-ai-tabs/.kt-ai-tab (data-active), сегменты как в v1.
Banner .kt-ai-banner data-tone="info|warn|risk|ok" – строчные предупреждения в контенте.
Modal .kt-ai-modal-overlay/.kt-ai-modal – bg-elevated, radius-2xl, shadow-xl, анимация rise.
Toast .kt-ai-toast-stack/.kt-ai-toast data-tone – нижний правый угол, точка-индикатор тона.
Tooltip .kt-ai-tooltip[data-tip] – чистый CSS.
Skeleton .kt-ai-skeleton (shimmer), Empty .kt-ai-empty (иконка + title + действие).
KPI .kt-ai-kpi-strip/.kt-ai-kpi – тихая метрик-полоса, не карточки.
Avatar, .kt-ai-divider, .kt-ai-status-pill с точкой-индикатором.
Drawer .kt-ai-drawer – правая панель деталей (правило: детали в drawer, не на новой странице).
Документ-артефакт .kt-ai-doc / .kt-ai-doc-list – карточка выходного документа (иконка + имя + статус/формат + кнопка «Скачать»). То, что продукт ПРОИЗВОДИТ (ТС, отчёт, СЗ), показывается как скачиваемый документ — в drawer (секция «Документы» из _docs строки) и в nav-секции-коллекции (nav.view="documents", фильтр по docType). Контракт: table.rows[]._docs.

Новое в v2.3 «Aurora × Attio»:

Карточки – card-bg/card-border/card-shadow токены: в dark – hairline-рамка + фиолетовое aurora-свечение из угла (data-glow="strong" – усиленный hero-вариант с двойным свечением), в light – белая поверхность с тенью без рамки. Радиус — radius-3xl.
Кнопки (Attio) – secondary: поверхность bg-elevated + рамка + shadow-sm, радиус 8; ghost/danger без поверхности.
Теги (Attio) – chip/status-pill/filter-chip: rounded-rect radius-tag (5px), не pill.
Таблицы (ElevenLabs) – дефолт frameless full-bleed: hairline под шапкой и между рядами, без вертикальных колонок-сепараторов (тихо, воздушно), заголовки sentence-case 12px medium muted; контейнерный вариант – data-framed="true". Для стабильности ширин при фильтрации фильтруемым таблицам задаётся table-layout:fixed + colgroup.
Property-row .kt-ai-prop (.k – иконка+метка 148px, .v – значение, data-empty) – детали объекта в drawer/карточке.
AI-aurora – токены ai-accent, ai-gradient (синий → фиолет): градиентная кромка prompt-bar в фокусе + ореол, градиентные send-кнопка и streaming-каретка, орб-атрибуция вместо ✦, .kt-ai-btn[data-ai="true"] – точка входа AI. Градиент НЕ используется вне AI-моментов.
Тихая ссылка .kt-ai-link[data-arrow] – «Подробнее →», стрелка сдвигается на hover.
Dot-grid текстура на .kt-ai-empty. Mono-голос: label, cmd-group, время уведомлений, ключи filter-chips. Активный таб – синий. Трекинг заголовков -.02em/-.01em. Sidebar-ряды 26px.

Новое в v2.2:

Topbar .kt-ai-topbar – канонический glass-хром: sticky, bg-glass + blur(8). Blur разрешён только здесь и на overlay.
AI-диалог: .kt-ai-chat + .kt-ai-msg data-role="user|assistant" (ассистент – полная ширина без пузыря, пользователь – пузырь bg-soft ≤76%), data-streaming="true" – каретка; .kt-ai-prompt-bar (autogrow textarea + .kt-ai-prompt-send, data-busy), .kt-ai-suggestions/.kt-ai-suggestion – стартовые подсказки, .kt-ai-source-pill – ссылка-источник в ответе, .kt-ai-gen-label – атрибуция «Сгенерировано ИИ» (обязательна для AI-контента).
Menu .kt-ai-menu-anchor > .kt-ai-menu[data-open] – dropdown действий (kebab в рядах таблиц): .item (data-danger), .sep.
Command palette – достроена: .kt-ai-command-overlay, .cmd-input, .cmd-list, .cmd-group, .cmd-item[data-active], .cmd-empty.
Filter-chips .kt-ai-filterbar + .kt-ai-filter-chip (.k – имя фильтра, .remove) + .clear-all – применённые фильтры над таблицей.
Radio .kt-ai-radio, .kt-ai-radio-group.
Toast: .action (undo-ссылка) и .close.
Popover .kt-ai-popover-anchor > .kt-ai-popover[data-open] (data-align="right") – якорный интерактивный слой (date-picker, настройки колонок).
Bulk-bar data-floating="true" – плавающий вариант снизу по центру для длинных таблиц.
Row actions .kt-ai-row .actions / .kt-ai-table tr .actions – тихие действия, видимы на hover/focus-within/selected; на touch видимы всегда.
Активный пункт навигации получает 2px-акцент слева (работает и в icon-rail).

Анатомия shell, таблиц, рядов – COMPONENTS.md (перенесено из v1-архива, нормативно).

Operational Dashboard Contract

Boilerplate задаёт обязательный shell: sidebar, .kt-ai-topbar, theme toggle и AI-кнопку Төре. Эти элементы нельзя перерисовывать, заменять самодельными глифами или делать декоративными. Main content проектируется под задачу процесса.
Для рабочих очередей, реестров и консолидации закупок предпочтителен classic app-shell: таблица как главный объект, детали в drawer, короткие workflow-status, одно primary-действие. Custom workspace, матрица, split-view или decision panel используются только когда таблица + drawer не решают основную работу пользователя.
H1/topbar title – короткий рабочий объект, 1-3 слова. Не использовать описание процесса как заголовок.
Subtitle – одна короткая scope-фраза до 90 символов.
KPI показывают рабочее состояние текущего пользователя: новые, требуют решения, риски, ждут документы, просрочено, закрыто сегодня, SLA или сумма риска. ROI, FTE, экономия часов и тенге эффекта не выводятся на пользовательский dashboard по умолчанию. Эти метрики относятся к management/reporting view, паспорту или расчёту эффекта проекта. Исключение – операционный экран консолидации, где пользователю нужны рабочие числа для решения: сколько ТС обработано, сколько имеют потенциал консолидации, какой предварительный потенциал экономии в тенге.
Search, theme toggle, AI button and visible primary actions must work in the prototype when shown. Search inputs are empty by default and must not be prefilled with arbitrary examples.
Primary filters – только workflow-status, максимум 4 пункта плюс Все. Confidence, risk type, системы и длинные причины не попадают в default segmented filters.
Workflow status, confidence и riskType моделируются разными полями.
Labels компактные: filter до 2 слов, status до 4 слов, table header до 2 слов; детали и длинные объяснения – в drawer/help.
UI-copy не показывает внутреннюю кухню генерации: модель вернула, fallback, не проходит дизайн-систему, shell, JSON и похожие формулировки запрещены в пользовательском интерфейсе.
Голос интерфейса нейтрален и продуктовый. Запрещены: дисклеймеры прототипа («это прототип на дизайн-системе», «данные иллюстративны»); нравоучения про human-in-the-loop («AI не действует на клиента сам», «решение подтверждает человек», «контрольная точка») — человек-в-контуре показывается контролами (рекомендация + кнопки accept/reject), а не объяснениями; лозунг-лейблы капсом («РЕШЕНИЕ — ЗА ВАМИ») — секции называются нейтральными существительными («Решение»). Любой продукт-специфичный текст (что сделал агент, разбор) живёт в контракте (scenario.aiSummary), а не зашит в shell — иначе он протекает в другие продукты. Валидатор ловит эти формулировки (PREACHY_LANG).

Состояния интерактива

Единая лестница: default → hover (-bg-hover или border-strong) → active/selected (-bg-active) → focus-visible (outline -focus-ring) → disabled (opacity .4). Hover-переходы dur-fast, появления dur-base, drawer/modal dur-slow. Нажатие кнопки: scale(.98) 60ms.

Движение (motion)

Правила — не украшение, а поведение. Каждое имеет причину.

Длительности по типу: микро/hover 100–150мс (dur-fast 100), обычное появление/смена 150–250мс (dur-base 160), overlay/drawer/modal ~240мс (dur-slow). Дольше 300мс движение начинает раздражать; короче — пропадает читаемость перехода.
Появляйся от scale(.95), не от scale(0) (и не от opacity:0 в одиночку): элемент «подрастает» из своего места, а не возникает из ниоткуда. Уводи так же — до .95, не в 0.
Отклик на нажатие, не на отпускание: подсветка/scale(.98) на pointer-down мгновенно; коммит — на pointer-up. Лаг убивает ощущение прямоты.
Переходы прерываемы и обратимы: закрывающийся drawer можно открыть на полпути. Анимируй от ТЕКУЩЕГО значения (presentation), а не от целевого — иначе «прыжок».
Вход и выход по одному пути; overlay привязан к источнику: меню/popover растут из кнопки (transform-origin = триггер), drawer уходит туда, откуда пришёл. На реверсе — зеркальный easing (ease-enter ↔ ease-exit).
Анимируй только transform и opacity (композиторные, без ре-лейаута). Не анимируй width/height/top/left/box-shadow — дёргается кадр.
prefers-reduced-motion обнуляет длительности автоматически (токены + компоненты); оставляем только opacity/цвет, что помогают понять переход.

Иконки

Lucide из локального sprite, монохром через currentColor, stroke 1.75. Размеры 16 (база), 14 (плотные ряды), 20 (крупные). Без CDN-шрифтов и CSS-псевдоиконок. Правила и список имён – v1-архив.

Доступность и QA

Контраст: основной текст ≥ 7:1, muted ≥ 4.5:1, faint только для необязательных подписей.
Фокус видим всегда: глобальный :focus-visible в components.css.
prefers-reduced-motion поддержан на уровне токенов (обнуляет длительности).
prefers-contrast: more: толще фокус-кольцо, границы = border-strong, ссылки подчёркнуты, обводка у пилюль.
prefers-reduced-transparency: reduce: blur на sticky-топбаре снимается, фон становится плотным (легибельность > эффект).
Чек-лист перед сдачей экрана — единый гейт CHECKLIST.md (Definition of Done): обе темы, состояния loading/empty/error, один primary, нет сырых hex, адаптив, паритет, валидатор 0/0. Прогоняется при любом изменении UI, не только при сдаче нового экрана.

Подключение

<link rel="stylesheet" href="kt-ai-tokens.css">
<link rel="stylesheet" href="kt-ai-components.css">
<body class="kt-ai-app" data-theme="dark">

Для Next.js-прототипов – кит templates/kt-ai-shadcn (внутри папки ДС, рядом с app-shell — ДС одна самодостаточная папка; переменные совместимы, источник значений – kt-ai-tokens.css; установка – его templates/kt-ai-shadcn/PROTOTYPING_WORKFLOW.md).

Два рантайма одного контракта. HTML app-shell (templates/kt-ai-app-shell.html) — демо-рантайм с роутингом разделов: рендерит nav-секции (view="documents", мастер steps), баннер-навигацию (banner.actionNav), коллекции документов. React-кит — одноэкранный handoff для разработки: рендерит главный архетип-экран (queue/dashboard/…) + drawer (включая секцию «Документы» из _docs), но НЕ роутит вторичные nav-секции — это намеренно (их реализует разработчик под свой роутер). Поэтому nav.view, steps, banner.actionNav — поведение HTML-рантайма; в React это точки расширения.

Миграция v1 → v2

Заменить подключение archive/kt_ai_terminal_tokens.css на пару kt-ai-tokens.css + kt-ai-components.css. Все старые переменные и классы продолжают работать.
Hardcoded-размеры и цвета постепенно переводить на шкалы (--kt-ai-space-*, --kt-ai-text-*, semantic-цвета).
Новые компоненты (кнопки, формы, modal, toast, banner, skeleton, empty) не писать заново – брать из components.css.
Паритет тем проверять в showcase.html.

Ритм отступов (правило близости)

space-* – сырая шкала для внутренних отступов компонента. Расстояние МЕЖДУ блоками экрана берётся из отдельной шкалы stack-* – одно значение на роль, а не решение каждого компонента:

Токен	Значение	Когда
`--kt-ai-stack-tight`	12px	внутри группы: подпись ↔ контрол, контрол ↔ контрол в одном ряду
`--kt-ai-stack-block`	16px	между элементами одного блока; полоса карточек KPI; панель управления ↔ то, чем она управляет
`--kt-ai-stack-group`	24px	между блоками экрана: шапка / баннер / KPI / чарт / таблица. Значение по умолчанию
`--kt-ai-stack-region`	32px	поля рабочей области, топбар ↔ заголовок
`--kt-ai-pad-card`	20px	интерьер карточки/секции

Почему шкала, а не space-* напрямую: раньше каждый компонент выбирал отбивку сам, и на одном экране получалось пять разных значений для одного и того же отношения «блок ↔ блок» (8/12/16/20/24). Глаз не читает такую разницу как иерархию – он читает её как небрежность, и экран выглядит захламлённым при формально верных токенах. Ровно так разошлись два рантайма: HTML-шелл давал 16/20, React-кит 24/28.

Правило разрешения споров прежнее: если сомневаешься, к какой группе элемент относится визуально – он стоит неправильно. Секционный разрыв (40+, space-10) остаётся для смены смысла страницы, а не для соседних блоков одного экрана.

Одинаковый зазор — не ритм

Шкала не означает «поставь stack-group на всё». Ровно так экран становится плоским: панель фильтров, её вкладки и карточки списка расходятся на одно и то же расстояние, и глаз не видит ни одной группы — только столбец одинаково далёких полос. Разнобой читается как небрежность, равномерность — как «здесь ничто ни с чем не связано». Обе ошибки одинаково дорогие.

Рецепт экрана — три ступени, не одна:

шапка страницы                        ← 24 (stack-group): регион
системный баннер                      ← 24 (stack-group): регион
┌ панель управления                   ← 12 (stack-tight): фильтры и вкладки — ОДНА вещь
│   фильтры
│   вкладки
└                                     ← 16 (stack-block): панель ближе к тому, чем управляет
┌ содержимое                          
│   KPI · чарт · карточки списка      ← 16 между блоками, 12 между однородными карточками
└

Выражается стеком, а не своим классом продукта: <div class="kt-ai-v" data-gap="group|block|tight|region">. Если продукту понадобился собственный app-stack-* — это сигнал, что группировку не выразили, а обошли.

Проверка одной фразой: пройди по вертикали и назови каждый зазор. Если все числа разные — сломана согласованность. Если все одинаковые — сломана группировка. Правильно, когда чисел ровно столько, сколько на экране уровней вложенности.

Отзывчивость

Брейкпоинты: sm 640 / md 832 / lg 1024 / xl 1280 (--kt-ai-bp-*; в media-запросах значения дублируются числом – var() там недоступен).

Shell – три состояния (реализовано в components.css):

≥ lg: полный sidebar 232px.
md..lg: icon-rail 52px – подписи прячутся; в разметке подписи пунктов оборачивать в <span class="nav-label">.
< md: sidebar = overlay-drawer (data-open="true"), в топбаре burger; drawer документов – full-screen.

Touch (pointer: coarse): токены контролов автоматически растут (sm 36, md 44, lg 48, nav-row 40, table-row 52) – компоненты масштабируются сами, ничего переопределять не нужно.

Мобильный топбар: на < sm в топбаре остаются логотип (без текста), статус-чип с ellipsis и одно главное действие; текстовые кнопки прячутся или сворачиваются в иконки; элементы с flex-shrink:0 допустимы только для иконок и тумблера. Бургер для off-canvas панелей – иконка menu из спрайта (три линии), не самодельные глифы. Горизонтальный скролл страницы запрещён и гасится системой на < md (overflow-x hidden на .kt-ai-app/.kt-ai-shell).

Таблицы: горизонтальный скролл внутри table-wrap; первая колонка может быть sticky (.kt-ai-sticky-first); при < md и более 4 колонок – переключаться на список карточек.

API компонентов (enum-контракт)

Компонент	Атрибут	Значения
`.kt-ai-btn`	data-variant	(нет) = secondary, `primary`, `ghost`, `danger`
`.kt-ai-btn`	data-size	(нет) = md, `sm`, `lg`
`.kt-ai-btn`	data-loading	`true` – спиннер, клики заблокированы
`.kt-ai-chip`	data-tone	`gray`, `green`, `orange`, `blue`, `purple`, `red`
`.kt-ai-chip`	data-removable	присутствие + `<span class="remove">×</span>`
`.kt-ai-status-pill`	data-status	`ok`, `warn`, `risk`, `info`
`.kt-ai-banner`, `.kt-ai-toast`	data-tone	`ok`, `warn`, `risk`, `info`
`.kt-ai-input/.kt-ai-textarea`	data-invalid	`true`
`.kt-ai-field`	data-invalid	`true` — красит вложенный input/select/textarea (удобно, когда состояние живёт на поле)
`.kt-ai-table`	data-density	(нет) = 48px, `compact`/`dense` 38, `relaxed` 56 (значения из `tokens.json`)
`.kt-ai-table th`	data-sort	присутствие = сортируемая, `asc`, `desc`
`.kt-ai-step-item`	data-state	(нет) = upcoming, `current`, `done`
`.kt-ai-combobox`	data-open	`true` – меню видно
`.kt-ai-table td`	data-label	подпись ячейки в мобильном card-режиме (≤640px). Без неё значение просто выравнивается влево
`.kt-ai-switch-row`	—	готовая строка «подпись + свитч справа». Сам `.kt-ai-switch` — только трек 34px
`.kt-ai-modal`	—	ОБЯЗАТЕЛЬНО внутри `.kt-ai-modal-overlay` — оверлей и есть центрирующий контейнер (`position: fixed` + flex). Соседями они не работают: модалка встанет в поток и уедет со скроллом
`.kt-ai-scroll-locked`	—	на `<html>`, пока открыт модал/drawer: иначе фон скроллится под оверлеем. Снимать при закрытии
`.kt-ai-disclosure`	data-open	`true` — раскрыт. Карточка, разворачивающаяся НА МЕСТЕ. Для очередей, где объекты сравнивают: drawer закрывает список и заставляет открывать по одному. Части: `-head` (кнопка, `aria-expanded`), `-chevron`, `-body`, `-actions`
`.kt-ai-kpi`	—	подпись всегда над значением, порядок `.label`/`.value` в разметке любой
`.kt-ai-combobox .option`	data-selected, data-active	`true`
`.kt-ai-dropzone`	data-drag	`true` – состояние перетаскивания
`.kt-ai-table-bulkbar`	data-open	`true`
`.kt-ai-sidebar`	data-open	`true` (только < md, overlay)
`.kt-ai-notif-item`	data-unread	`true`
`.kt-ai-theme-toggle`	data-mode	`dark`, `light` – бегунок и подсветка иконки
`.kt-ai-diff .line`	data-op	`add`, `del`
nav-item, tab, segmented .seg, pagination .page-btn	data-active	`true`
`.kt-ai-msg`	data-role	`user`, `assistant`
`.kt-ai-msg`	data-streaming	`true` – каретка генерации
`.kt-ai-prompt-bar`	data-busy	`true` – ввод заблокирован на время генерации
`.kt-ai-menu`, `.kt-ai-popover`	data-open	`true`
`.kt-ai-menu .item`	data-danger	`true` – деструктивный пункт
`.kt-ai-popover`	data-align	(нет) = left, `right`
`.kt-ai-table-bulkbar`	data-floating	`true` – плавающий снизу
`.kt-ai-command .cmd-item`	data-active	`true`
`.kt-ai-card`	data-glow	`strong` – усиленное aurora-свечение (hero/AI)
`.kt-ai-btn`	data-ai	`true` – градиентная AI-кнопка (точка входа Төре)
`.kt-ai-table-wrap`	data-framed	`true` – контейнер с рамкой (дефолт – frameless)
`.kt-ai-link`	data-arrow	присутствие – тихая ссылка «… →»
`.kt-ai-prop .v`	data-empty	`true` – незаполненное значение
`.kt-ai-kpi-strip`	data-cards	`true` – сетка стат-карточек (radius-2xl, card-токены) вместо тихой полосы

Локализация

Казахские строки длиннее русских на ~20%: запрещены фиксированные ширины под текст кнопок, чипов, пунктов меню; truncation с ellipsis + tooltip полного значения.
Числа: тысячи пробелом (1 240), тенге после числа (1 240 ₸), числа в таблицах — sans + tabular-nums (цифры Inter выровнены по ширине; в JetBrains Mono нет глифа ₸, из-за чего валюта подставлялась из другого шрифта и рвала колонку). Моноширинный остаётся только у .kt-ai-kbd и командных групп.
Даты: dd.mm.yyyy, время hh:mm, относительные («2 мин», «вчера») только в уведомлениях и лентах.

Чарты

Максимум 6 серий на график (порядок: chart-blue, green, orange, salmon, pink, red). Оси и подписи – fg-faint, сетка – divider. Заливка под линией – только primary-subtle и только для одной серии. Без 3D, теней и градиентов в данных. Пустое состояние графика – kt-ai-empty, не пустые оси.

Печать и экспорт

Подключить kt-ai-print.css (генерируется из tokens.json): при печати принудительно light-палитра, скрываются shell/кнопки/тосты, формат A4 с полями 18/16 мм, карточки и таблицы не разрываются. Элементы, которые не должны попасть в PDF, помечать data-no-print.

Иконочные кнопки и деструктивные действия

Icon-only кнопка обязана иметь tooltip (.kt-ai-tooltip[data-tip]) и aria-label. Деструктивные действия: никогда не icon-only; подтверждение в modal; кнопка подтверждения – глаголом действия («Удалить агента», «Отправить в Реестр»), никогда «Да»/«ОК»; для необратимых операций – ввод имени объекта.

Правило двух продуктов

Новый компонент попадает в систему только когда он понадобился второму продукту. До этого живёт в продукте. Это держит систему маленькой и честной.

Визуальная регрессия

scripts/visual_check.mjs (Playwright): скриншоты showcase в обеих темах и трёх ширинах (1280/900/600), сравнение с эталонами в scripts/__screenshots__/. Запуск локально: npx playwright install chromium && node scripts/visual_check.mjs. Прогонять при любом изменении tokens.json или components.css.

Do / Don't

Do: ряды вместо крупных карточек; таблица – главный объект экрана; детали в drawer; метрики тихой полосой (в дашбордах/кабинетах с 2-4 главными метриками – data-cards="true"); primary-действие монохромное (near-black/near-white); кнопки create/«Новый X» – с ведущим «+»; один фильтрующий поиск на экран; AI-кнопка Төре – в топбаре рядом с поиском; продукт-специфичный текст – в контракте, не в shell.
Don't: карточки в карточках; декоративные градиенты, свечения и blur в контенте (исключения: единичная AI-искра орба/send/prompt-bar, blur на sticky-хроме и overlay); синий как заливка primary-кнопки; больше одного primary; цвет hex напрямую; новые цвета/иконки/геометрия под отдельный продукт; разная геометрия в темах; дисклеймеры/нравоучения в UI; два одинаково фильтрующих поиска; лишний input/селект там, где хватает прямой кнопки.

41 KiB Raw Blame History Unescape Escape