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

Философия

Манифест

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

Принципы

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

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

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

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

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

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

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

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

ИИ-агенты получают тот же канон в машинных форматах. Все файлы ниже строятся из данных спецификации. Маршруты агент читает в 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- Список или ряд с перестановкой строк за рукоятку и стрелками.

Структуры

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

Скоуп и скины

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