Спецификация дизайн-системы

Философия

Манифест

Сначала поведение, потом оформление. Bits UI или HTML отвечают за семантику, токены за внешний вид. Недоступные действия не показываем. На экране не больше одного accent. Канон переносится между продуктами, productScope принадлежит бренду.

Принципы

• Поведение прежде украшения. Доступные примитивы дают базовое поведение. Декоративная оболочка без поведения не подходит.
• Честные состояния. Недоступные действия не показываем. Фейковый disabled и спиннеры в контролах скрывают состояние.
• Не больше одного акцента. Один accent задаёт ясную иерархию, а экран без него читается спокойно. Два главных действия заставляют пользователя выбирать между акцентами.
• Токены, не литералы. Все значения приходят из токенов. Литералы в компонентах расходятся со шкалами системы.
• Канон и productScope. Канон хранит переносимую логику. productScope хранит решения конкретного бренда.
• Меньше абстракций. Решение остаётся простым и читаемым. Абстракция без повторного применения только усложняет код.
• Текст помогает действовать и понимать. Текст называет действие, состояние или решение. Повторы и размытые фразы мешают увидеть главное.

Словарь канона

Одинаковые оси получают одинаковые имена во всех компонентах.

Общие правила

• Нет disabled. Недоступное действие не показываем, а не гасим.
• Нет loading у контролов. Первичную загрузку показывает область (areaStates), а не спиннер в контроле. Собственное ожидание есть только у компонента, который ждёт результата действия внутри себя — поиск в списке, подгрузка строк таблицы; область старше компонента: пока она грузится, содержимое скрыто целиком.
• Не больше одного accent на экран. Два главных действия ломают иерархию. Экран, который читают, а не правят, обходится без главного действия.
• Тема охватывает компоненты. Смена темы меняет поверхности, текст, контуры и состояния компонентов во всех скинах.
• Danger хранится в tone. Разрушающее сочетается с любым уровнем.
• Текст называет действие или подтверждение. Объект добавляется, только если без него неясен результат.
• Нативная семантика и видимый focus-visible. Используем Bits UI там, где есть подходящий примитив, иначе нативный контрол; клавиатурный фокус всегда различим.
• ДС задаёт компоненты, продукт задаёт экран. Общие компоненты сохраняют канонное поведение и токены. Состав, композиция, навигация и сценарий принадлежат продукту. При редактировании существующего экрана его структура сохраняется, пока задача явно не требует изменения; локальный блок собирается из компонентов, текста и раскладки и не требует регистрации в общей ДС. Паттерн рекомендует сочетание компонентов, но не запрещает остальные опубликованные экранные компоненты; их назначение и ограничения сохраняются.

Уровни композиции

Паттерн. Рецепт применения сущностей любого уровня. Паттерн описывает знание, а не степень композиции.

Для ИИ-агентов

ИИ-агенты получают тот же канон в машинных форматах. Все файлы ниже строятся из данных спецификации. Маршруты агент читает в agents.md или получает через MCP.

• llms.txt - индекс спецификации.
• spec.json - нормативный канон.
• examples.json - код живых примеров.
• scope.json - покрытие юнитов и компонентов скинами.
• tokens.json - токены в формате DTCG.

Практики

• Доступность - Фокус, клавиатура, доступные имена и контраст.
• Формы - Поля, обязательность, проверка значений и действия формы.
• Контент и тон - Интерфейсный текст и документация без лишних повторов.
• Иконки - Набор Phosphor целиком, вес от скина, размеры, цвет и доступные имена.

Примитивы

• Цвет
• Типографика
• Отступы
• Радиусы
• Тени
• Движение
• Иконки

Юниты

• Button- Запускает действие или оформляет переход как действие.
• Toggle Button- Включает или выключает один устойчивый режим.
• Flipper- Перебирает по кругу закрытый список значений одной круглой кнопкой-значком.
• Link- Переводит пользователя к другому месту или ресурсу.
• Input- Принимает однострочное свободное значение.
• Input Number- Вводит число и изменяет его на заданный шаг.
• Slider- Выбирает число или границы диапазона на шкале.
• Select- Выбирает одно значение из короткого известного списка.
• Combobox- Выбирает одно значение из длинного плоского списка с поиском.
• Textarea- Многострочное текстовое поле.
• Input Color- Поле выбора цвета.
• InputDate- Поле выбора одной даты.
• Input Time- Вводит точное время суток с минутной точностью.
• Checkbox- Выбирает один независимый бинарный признак в форме.
• Radio- Выбирает ровно одно значение из видимого взаимоисключающего набора.
• Switch- Мгновенное переключение состояния без подтверждения.
• Segmented Control- Выбор одного сегмента из ряда.
• Alert- Показывает короткое системное сообщение рядом с местом реакции.
• Avatar- Стабильный визуальный идентификатор пользователя.
• Thumbnail- Миниатюра изображения или плейсхолдер заданного размера и пропорции.
• Divider- Разделяет соседние блоки горизонтальной или вертикальной линией.
• Icon- Иконка по имени из словаря канона и размеру шкалы, вне кнопки.
• Logo- Бренд-марка продукта: словесный знак ADMY на токенах скина.
• Progress- Показывает ход одной текущей операции.
• Meter- Показывает текущее числовое состояние внутри известного диапазона.
• Chart- Плейсхолдер графика заданного типа и высоты.
• Chart Line- Тренд по времени: ломаная с градиентной областью, штриховой сеткой, подписями оси и подсказкой по наведению.
• Chart Bars- Столбцы по категориям: одна серия или стопка серий, скруглённый верх, подписи оси, подсказка с итогом и разбивкой.
• Chart Donut- Доли целого: кольцо с итогом в центре или круг; сегменты с зазором, подсказка со значением и долей.
• Chart Ranked- Ранжированные полосы: подпись, полоса от максимума, значение и доля; одна или две колонки.
• Legend- Расшифровка серий: точка цвета, подпись, значение и мини-полоса доли; строками или в линию.
• Kpi- Ключевой показатель: подпись капсом, крупное число, плашка изменения и заметка.
• Delta- Плашка изменения: стрелка и текст на тонированной подложке — рост, падение, нейтрально.
• Skeleton- Обозначает форму ещё не готового содержимого.
• Loader- Показывает короткое ожидание без измеримого хода и известной структуры.
• Status- Компактный бейдж статуса.
• Indicator- Точка-маркер рядом с подписью: непрочитанное, счётчик выбранного, состояние строки.
• Tag- Компактная метка для фильтров, сегментов и выбранных значений.
• Badge- Короткая метка на цветной подложке: «NEW», «BETA», счётчик в строке.
• Tooltip- Коротко поясняет назначение существующего интерактивного элемента.
• Title- Заголовок блока плашкой и заголовок секции строкой: текст, подсказка, действие справа.
• Label- Подпись вне поля: группа контролов, значение в сводке, переключатель — в стиле подписи поля.
• Description- Пояснение или ошибка под группой, блоком или значением — в стиле футера поля.
• EntityId- Идентификатор записи «ID 4444444»: префикс и значение в строке приглушённым цветом.
• Amount- Денежная сумма с валютой и разрядами; отрицательная — цветом опасности.
• Stars- Оценка звёздами: наведение показывает будущую оценку, клик закрепляет её.
• Code- Блок кода: тёмная плашка или светлая область с заголовком и прокруткой.
• QR Code- Квадрат с QR-кодом на белой подложке; сам код приходит картинкой.
• Animation- Область заданного размера под анимацию продукта: Lottie, Rive, видео.
• Recaptcha- Рамка под виджет проверки «я не робот» с текстом ошибки под ней.
• Client Version- Плашка у верхнего края окна: доступна новая версия, кнопка обновления.
• Lang Menu- Список языков интерфейса: код, название, текущий выделен.
• User Name- Почта или логин пользователя строкой в нижнем регистре.
• Toast- Показывает очередь кратких сообщений о завершившихся событиях.
• Copy Field- Показывает готовое значение и кладёт его в буфер обмена одним действием.

Компоненты

• Stat List- Показатели виджета: строки «подпись — значение» с линиями или ячейки в ряд с подписью капсом.
• Checkbox Group- Множественный выбор из набора с общей подписью.
• InputDateRange- Поле выбора диапазона дат.
• Input Time Range- Вводит начало и окончание одного интервала внутри суток.
• File Upload- Выбирает один или несколько локальных файлов до отправки формы.
• Accordion- Сворачивает вторичные разделы статьи или формы.
• Tabs- Переключает одну из нескольких равноправных панелей.
• Breadcrumbs- Показывает путь от верхнего раздела к текущей странице.
• Pagination- Переключает страницы одной длинной выдачи.
• Menu- Собирает связанные действия и ссылки в раскрывающийся список.
• Dialog- Изолирует одну модальную задачу или обязательное подтверждение.
• Entities List Dialog- Кнопка со значком списка открывает диалог, где значения вставляются текстом по строке.
• Drawer- Выдвижная панель фильтров у правого края с подвалом «применить / сбросить».
• Popover- Показывает компактную интерактивную панель рядом с trigger.
• Popover Preview- Миниатюра в строке таблицы; клик раскрывает панель с полноразмерной картинкой.
• Multi Select- Собирает несколько значений из длинного плоского списка с поиском.
• Select Toggle- Режим «включить / исключить» над списком выбранных значений.
• Subscription Limit- Диапазон дней подписки: дорожка и два числовых поля «от» и «до».
• Tag Input- Собирает свободные метки: текст становится чипом по Enter или запятой.
• Toggle Group- Выбирает один или несколько связанных режимов в горизонтальной группе.
• Picker- Выбор одного варианта плитками с иконкой, названием и описанием.
• Scheduler- Недельная сетка 7 × 24: клик по ячейке, дню или часу включает показы.
• Feedback- Форма отзыва в острове: вопрос, звёзды, галочки, текст, отправка и благодарность.
• Table- Сравнивает набор строк по общим именованным колонкам.
• Column Settings- Диалог: порядок и видимость колонок за рукоятку и чекбоксы, компактный вид, ширина колонок.
• Toolbar- Объединяет связанные действия, ссылки и режимы в одну клавиатурную панель.
• Steps- Показывает положение текущего этапа в фиксированном процессе.
• Dualist- Двухпанельный мультиселект.
• Extra Group- Компактная строка из числовых значений через слеш.
• Combo- Повторяющиеся строки формы с кнопкой удаления у каждой, кроме последней пустой.
• Fields Group- Строки из нескольких полей в одной рамке с делителями и кнопкой удаления.
• Input Select- Составной input из сегментов-селектов.
• UserMenu- Аватар с caret-кнопкой в шапке раскрывает меню профиля, настроек и выхода.
• User Card- Карточка пользователя: аватар, ID и имя на поверхности с тенью.
• User Line- Строка пользователя: аватар, ID, имя и почта через тире, опционально баланс.
• Drag And Drop- Список или ряд с перестановкой строк за рукоятку и стрелками.

Структуры

• Форма- Поля, валидация, обратная связь и одно главное действие.
• Редактор сущности- Длинная настройка одной сущности: секции слева, поля в центре, сводка справа.
• Список сущностей- Длинная выдача однородных сущностей: отбор сверху, строки в середине, страницы снизу.
• Обзор раздела- Раздел показывают, а не правят: содержимое одним потоком и сводка сбоку.
• Дашборд- Показатели за период плиткой: человек смотрит на числа, меняет срез и уходит.
• Подтверждение разрушения- Последняя проверка перед необратимым или дорогим действием.
• Группа выбора- Один или несколько вариантов с явной моделью выбора.
• Каркас приложения- Глобальная навигация, основное содержимое и адаптивный доступ к ним.

Скоуп и скины

• Скоуп - покрытие юнитов и компонентов скинами.
• Скины - одни компоненты в разных визуальных стилях.