Карточки и уровни поверхностей
Правила использования теней, прозрачности, градиентов и размытия фона для контентных карточек, оболочек рабочей области, всплывающих слоёв, теней и фонов.
Контентные карточки остаются плоскими; внешняя оболочка передаёт группировку рабочей области.
Стандартная карточка контента не использует внешнюю тень.
Выбор и статус передаются через цвет и иерархию информации.
Материалы поверхностей и правила иерархии
В этом документе описано, в каких сценариях интерфейс Qokit использует тени, прозрачность, градиенты и размытие фона. Применяется к платформе в целом, Builder, CMS, Dashboard, Studio и Admin. Маркетинговые страницы и сгенерированные сайты могут быть более выразительными, но эффекты должны принадлежать текущей теме и обеспечивать читаемость контента.
Основные принципы
Визуальные эффекты выражают структуру, а не украшают каждый блок:
- Контент различается по разнице фонового цвета.
- Контейнеры выражают принадлежность через прозрачность или сдержанные градиенты.
- Всплывающие слои выражают иерархию через тени.
- Интерактивность выражает состояние через цвет и кольцо фокуса.
Отдельные непрозрачные карточки и поля ввода используют общую лёгкую тень первого уровня; списки, вложенные поверхности и прозрачные группы остаются плоскими; явные тени используются только для настоящих всплывающих слоёв.
Порядок определения
Перед добавлением материальных эффектов определите роль поверхности:
- Это отдельная непрозрачная карточка или поле ввода? Используйте общую тень первого уровня поверхности или поля.
- Это строка списка, вложенная карточка, повторяющийся вариант или прозрачная группа? Оставьте плоской.
- Организуете ли вы несколько внутренних контентных карточек в рабочую область? Используйте Shell.
- Перекрывает ли элемент контент страницы или появляется над текущей плоскостью? Используйте тень всплывающего слоя.
- Находится ли элемент в состоянии перетаскивания, масштабирования или временного наведения? Используйте временную тень.
- Нужно ли просто выразить hover, выбор или фокус? Используйте общую роль hover, интерактивный фоновый цвет и кольцо фокуса.
Не накладывайте одновременно тени, прозрачность, градиенты и размытие, если роль поверхности этого не требует.
Матрица сценариев
| Роль поверхности | Тень | Прозрачность или градиент | Размытие фона |
|---|---|---|---|
| Отдельные непрозрачные контентные карточки, карточки метрик | Общая лёгкая тень первого уровня | Допустима лёгкая разница фонового цвета | Нет |
| Строки списка, вложенные карточки, прозрачные группы, повторяющиеся варианты | Нет | Допустима лёгкая разница фонового цвета | Нет |
| Группирующий Shell внутри страницы | Нет | Рекомендуется | Обычно не требуется |
| Боковая панель или постоянный Shell рабочей области | Лёгкая | Рекомендуется | Допустимо, если за ним виден контент |
| Dialog, Popover, Dropdown, контекстное меню | Явная тень всплывающего слоя | Фон должен быть достаточно непрозрачным для читаемости | Допустимо |
| Превью перетаскивания, состояние масштабирования, плавающее превью | Временно усиленная | Опционально | Обычно не требуется |
| Hover | Сохранить или слегка усилить тень первого уровня | Можно изменить фон | Без изменений |
| Состояние выбора или активации | Нет | Акцентный фон или сдержанный градиент | Без изменений |
| Поля ввода, поля поиска | Очень лёгкая тень поля | Использовать цвет поверхности элемента управления | Обычно не требуется |
| Отдельное основное действие, отдельная капсула, оболочка сегментированного элемента управления | Очень лёгкая тень элемента управления | Использовать цвет поверхности элемента управления | Обычно не требуется |
| Панель инструментов и прозрачные внутренние элементы управления | Нет | Использовать цвет поверхности элемента управления или прозрачность | Обычно не требуется |
| Визуальные карточки маркетинговых страниц или сгенерированных сайтов | Определяется темой | Допустимо | Использовать сдержанно |
Сопоставление компонентов
<Card>по умолчанию используетlayer="content": общая лёгкая тень первого уровня, без рамки, скругление20pxпо умолчанию; приглушённые, вложенные, списочные и прозрачные варианты остаются плоскими.<Card layer="shell">: на странице отвечает только за группировку, использует прозрачную или слегка градиентную поверхность и остаётся плоским; постоянный Shell рабочей области получает свою иерархию от текущего режима.<Card shape="pill">: для компактных однострочных карточек, скругление в форме овальной капсулы.SidebarNavigation: отдельный Shell рабочей области, сохраняет явные градиенты, прозрачность, размытие и лёгкую тень.PromptPanelв Studio при использовании в качестве контейнера рабочей области: использовать--workspace-shell-shadow.DialogPanel, выпадающие меню, Popover, контекстные меню и концептуальный браузер: использовать тень всплывающего слоя.- Холст Builder, предпросмотр устройств, предпросмотр сгенерированных сайтов, превью перетаскивания и состояние масштабирования: поскольку представляют отдельную плоскость предпросмотра или временный интерактивный слой, могут сохранять специальные тени.
Не создавайте карточки контента, плавающие слоями друг над другом. Если внешняя группировка действительно необходима, она должна быть плоским Shell. Кроме настоящих всплывающих слоёв, в одной цепочке DOM-предков допускается не более одной обычной тени контента или элемента управления.
Использование переменных дизайна (Token)
Предпочитайте общие Token, не кодируйте эффекты жёстко:
- Тень контентной карточки:
--card-shadow: var(--qk-shadow-surface) - Тень контентной карточки при hover:
--card-shadow-hover: var(--qk-shadow-surface-hover) - Тень поля:
--input-shadow: var(--qk-shadow-field) - Тень активного поля:
--input-state-shadow: var(--qk-shadow-field-active) - Тень элемента управления:
--qk-shadow-control/--qk-shadow-control-hover - Тень элемента управления основного действия:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - Размытие контентной карточки:
--card-backdrop-filter: none - Поверхность Shell:
--card-shell-surface - Размытие Shell:
--card-shell-backdrop-filter - Тень Shell рабочей области:
--workspace-shell-shadow - Поверхность Dialog:
--dialog-surface, обеспечивает сдержанный тематический градиент - Размытие Dialog:
--dialog-backdrop-filter - Тень всплывающего слоя Dialog:
--dialog-shadow - Скругление Dialog: переиспользует
--card-radius - Клавиатурный фокус:
--focus-ring - Тень всплывающего слоя: использовать существующие Token Dialog, Dropdown, Menu или всплывающего слоя уровня страницы
Обычные контентные карточки и панели рабочей области не должны использовать усиленный общий Token --shadow.
Глобальные тени следуют тихой шкале «короткое смещение, низкая прозрачность, нарастание по уровню размещения». Обычные Card, поля и элементы управления не должны углублять или увеличивать общие тени в маршрутах; Popover и Dialog выражают отделение от страницы через большее смещение и радиус размытия, а не через наложение тёмно-серого тумана.
Правила взаимодействия
Наведение (Hover)
- Контентные карточки не должны подниматься выше уровня
--qk-shadow-surface-hover. - Не поднимайте контентные карточки через
translateY. - Используйте лёгкое изменение фона или чёткую обратную связь элемента управления.
- Не меняйте форму, чтобы избежать несогласованности скруглений или обрезки теней.
Выбор и активация
- Используйте акцентную поверхность, состояние иконки, семантическое состояние или сдержанный градиент.
- Не выражайте состояние только через тень.
Клавиатурный фокус
- Используйте общее правило focus-visible или
--focus-ring. - Общая тень карточки не может заменять индикатор фокуса.
- Должен быть чётко виден как в светлой, так и в тёмной теме.
Перетаскивание и масштабирование
- Усиленная тень допустима только пока слой перемещается или изменяет размер.
- Временная тень должна быть удалена после завершения взаимодействия.
- Переполняемые контейнеры не должны обрезать эффекты обратной связи перемещаемого слоя.
Прозрачность и размытие фона
Прозрачность выражает принадлежность внешней поверхности и рабочей области. Размытие фона имеет смысл только тогда, когда за поверхностью действительно есть видимый контент, цвет или изображение.
- Не используйте размытие на сплошном фоне — оно только увеличивает стоимость рендеринга и не выражает иерархию.
- Текст, иконки и элементы управления должны быть чётко читаемы независимо от фона за ними.
- Когда браузер не поддерживает размытие фона, должен быть непрозрачный или читаемый запасной фон.
- Интенсивность размытия в плотных интерфейсах должна быть сдержанной.
- Необходимо проверять как в светлой, так и в тёмной теме.
Исключения, допускающие сохранение теней
- Shell боковой панели рабочей области
- Dialog, Popover, Dropdown, меню и модальные панели
- Концептуальный браузер Studio и подтверждающие всплывающие слои
- Холст Builder, рамки устройств и плоскости предпросмотра сгенерированных сайтов
- Превью перетаскивания, обратная связь масштабирования и временные плавающие инструменты
- Кнопки основного действия, для которых общий Token кнопки уже определяет тень
- Визуальные элементы маркетинговых страниц и сгенерированных сайтов, управляемые текущей темой
Эти исключения не должны влиять на обычные контентные карточки через широкие селекторы или общие Token.
Контрольный список проверки
- Отдельные непрозрачные контентные карточки и поля ввода используют только общую роль лёгкой тени первого уровня.
- Отдельные основные действия, отдельные капсулы и оболочки сегментированных элементов управления используют только общую роль очень лёгкой тени элемента управления.
- Группировка на странице, строки списка, вложенные карточки, прозрачные группы, повторяющиеся Tab/Pill, панели инструментов и внутренние элементы составных элементов управления остаются плоскими.
- Поиск, фильтрация, сортировка, переключение вида и встроенные основные действия в панели инструментов остаются плоскими; лёгкая тень обычных полей ввода не должна проникать в панель инструментов, за исключением кольца клавиатурного фокуса.
- Когда Segmented находится внутри карточки, диалога или панели инструментов с уже имеющейся тенью, оболочка и выбранный элемент остаются плоскими; при клике мышью кольцо клавиатурного фокуса не отображается.
- Кроме настоящих всплывающих слоёв, в одной цепочке предков не накладываются несколько обычных теней.
- Hover не вызывает вертикального смещения контентных карточек.
- Вложенные контентные карточки удалены, либо внешний слой явно определён как Shell.
- Только настоящие Shell используют
--workspace-shell-shadow. - Только настоящие всплывающие слои и временные интерактивные слои используют усиленные тени.
- За размытием фона есть видимый контент и предусмотрен читаемый запасной фон.
- focus-visible использует кольцо фокуса.
- Светлая и тёмная темы сохраняют достаточную контрастность.
- Поверхности со скруглениями не обрезают обратную связь hover, focus, перетаскивания или всплывающего слоя.
- На десктопной и мобильной ширине не появляется новых горизонтальных переполнений.
- Проверка
npm run ui:check-card-surfaces --workspace @qokit-ai/webпройдена.