Кнопка Button
Спецификации семантики, размеров, форм, состояний и доступности для Button и IconButton.
AIButton использует размеры и семантику кнопки, добавляя при этом отличительное, заметное состояние Qokit AI.
Выберите кнопку ИИ, чтобы просмотреть её рабочее состояние.
Спецификации компонента Button в Qokit
Этот документ определяет правила использования кнопок в платформе Qokit, Builder, CMS, Dashboard, Admin, маркетинговых страницах и сгенерированных сайтах. Цель — унифицировать компоненты, семантику, формы, размеры, иконки, состояния и доступность кнопок, избегая перепроектирования кнопок через локальный CSS в отдельных маршрутах.
1. Базовая модель
Кнопки классифицируются не просто по «овальным» и «круглым», а состоят из пяти независимых измерений:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Тип компонента определяет, имеет ли кнопка видимый текст и должна ли она сохранять квадратную область нажатия.
- Семантический приоритет определяет приоритет кнопки и её цвет в рамках текущей задачи.
- Размер определяет фиксированную высоту, размер шрифта текста и область касания.
- Форма определяет только скругление углов, не выражая приоритет или бизнес-семантику.
- Пространственный уровень указывает только, поднимается ли элемент управления над текущей плоскостью, не изменяя семантику действия.
Не создавайте новые типы кнопок путём комбинирования новых имён классов. Сначала выбирайте из существующих свойств общих компонентов.
2. Выбор компонента
Button
Используется для всех действий с видимым текстом, включая:
- Текстовые кнопки;
- Кнопки с иконкой перед текстом;
- Кнопки с иконкой после текста;
- Ссылки на странице, оформленные как кнопки.
Button в платформе по умолчанию использует полностью скруглённый pill, визуально представляя собой овальную форму. Пока кнопка содержит видимый текст, её не следует заменять на круглую кнопку-иконку.
variant отделена от теней: primary по умолчанию использует raised, secondary, danger, ghost по умолчанию используют flat. Действия внутри строк списков, карточек, панелей инструментов и составных капсул должны быть flat; независимые основные действия могут использовать raised; только действия, парящие над контентом, используют floating. Независимые капсулы или сегментные элементы управления отрисовывают тень только один раз на внешнем уровне; маршруты не должны переопределять общие уровни через локальный CSS.
import { Button } from '@qokit/components/ui';
<Button type="button" variant="primary">
保存
</Button>
<Button
leadingIcon={<SaveIcon aria-hidden="true" />}
type="button"
variant="primary"
>
保存
</Button>
<Button
href="/projects"
trailingIcon={<ArrowRightIcon aria-hidden="true" />}
variant="secondary"
>
查看项目
</Button>IconButton
Используется для компактных действий с инструментами, где есть только иконка без видимого текста, например: закрыть, ещё, назад, переключить меню или удалить.
IconButton сохраняет равную ширину, высоту и полное скругление при каждом размере, поэтому визуально является круглой кнопкой. По умолчанию используется ghost, а на уровне типов требуется aria-label.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Правила:
- Сама иконка использует
aria-hidden="true", название кнопки предоставляется черезaria-label. - Для незнакомых иконок или иконок с потенциально неоднозначным значением следует одновременно использовать общий
Tooltip; tooltip не может заменятьaria-label. - Не используйте DOM-атрибут
titleв качестве подсказки продукта и не устанавливайте одновременноtooltipс ручной обёрткой в Tooltip. - Tooltip — это информационный слой только для чтения, а не овальная кнопка. Он использует общие компактные скругления Tooltip и не должен повторно использовать визуальные эффекты
pill, hover, pressed или focus кнопки. - Не используйте
Buttonс пустым текстом, скрытым текстом или фиксированной шириной для имитацииIconButton. - Не устанавливайте
shapeдляIconButton; круглая форма — это контракт компонента.
Сценарии, где не следует использовать Button
- Для вкладок используйте соответствующие компоненты Tabs/PillTabs/Segmented.
- Для пунктов меню используйте соответствующие компоненты Menu/ActionMenu.
- Для состояний, меток и результатов фильтрации используйте Pill или компоненты состояния.
- Для обычной текстовой навигации используйте семантические ссылки; только когда необходимо визуальное выделение уровня кнопки, используйте
Buttonсhref.
3. Семантические уровни variant
| Вариант | Значение | Типичные сценарии | Ограничения использования |
|---|---|---|---|
primary | Основное действие в текущей области | Сохранить, опубликовать, создать, попробовать сейчас | Обычно только одно основное действие на область задачи |
secondary | Явное, но вторичное действие | Предпросмотр, отмена, назад, импорт | Не должно конкурировать за визуальное внимание с основным действием |
ghost | Низкий акцент, контекстные действия с инструментами | Закрыть, ещё, действия панели инструментов, лёгкий возврат | По умолчанию прозрачный; не может быть единственным ключевым CTA |
danger | Действие, которое удаляет или наносит значительный ущерб | Удалить элемент, удалить контент, очистить данные | Выражает только разрушительную семантику, не используется как обычный акцентный цвет |
variant выражает семантический и визуальный уровень, а не форму. Например, ghost может быть овальной кнопкой с текстом или круглым IconButton.
Порядок выбора:
- Найдите единственный наиболее важный следующий шаг в текущей задаче и назначьте его как
primary. - Для вспомогательных действий, которые всё ещё должны быть чётко видны, используйте
secondary. - Для действий с низким акцентом в панели инструментов или контексте используйте
ghost. - Только для реально разрушительных действий используйте
danger, следуя существующему процессу подтверждения.
Не выбирайте вариант исходя из того, «какой цвет красивее».
4. Размеры size
| Размер | Высота/диаметр | Размер шрифта | Рекомендуемые сценарии |
|---|---|---|---|
sm | 40px | 14px | Верхняя навигация, компактные панели инструментов, плотные рабочие области |
md | 44px | 15px | Формы по умолчанию, CMS, диалоги и обычные действия |
lg | 48px | 16px | Основные CTA маркетинговых страниц, основные действия с повышенной тактильностью |
Размер по умолчанию — md.
- Одна группа кнопок использует один размер.
- Компактные элементы управления не должны быть меньше 40px; основные действия на мобильных устройствах должны использовать не менее 44px.
- Высота
Buttonи диаметрIconButtonиспользуют один и тот же набор токенов размеров, поэтому их можно выровнять в одной панели инструментов; видимый размер иконкиIconButtonунифицирован до 18px. - Размер шрифта текста
Buttonопределяется общим токеном, соответствующим size, и не наследует размер шрифта Header, Dialog или другого родительского контейнера. - CSS маршрута может управлять расположением, отступами и необходимой шириной кнопок, но не может переопределять общую высоту или размер шрифта кнопок.
- При длинном тексте предпочтительнее скорректировать макет или контейнер кнопки, а не решать проблему сжатием высоты, шрифта или боковых отступов.
5. Форма shape
| Форма | Внешний вид | Область применения |
|---|---|---|
pill | Полное скругление; с текстом — овальная форма | По умолчанию для платформы; подходит для маркетинговых страниц, Dashboard, Builder, CMS и Admin |
rounded | Скругление 12px | Только когда тема сгенерированного сайта явно требует меньшего скругления |
Button по умолчанию shape="pill". Фронтенд платформы не должен явно устанавливать rounded, а также не должен переопределять скругление в локальном CSS.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton всегда круглая и не участвует в бизнес-выборе pill / rounded.
6. Правила иконок
- Иконка перед текстом использует
leadingIcon, иконка после текста используетtrailingIcon. - Одна кнопка обычно использует только одну вспомогательную иконку.
- Знакомые действия, такие как сохранить, добавить, назад, могут использовать иконку для усиления узнаваемости, но иконка не может заменять видимый текст ключевых кнопок.
- Стрелки, обозначающие продолжение, вход или раскрытие, обычно размещаются после текста; иконка возврата обычно размещается перед текстом.
- Не размещайте вручную макет иконки и текста в
children; компонент уже предоставляет слоты icon и label. - Используйте общие иконки и наследуйте
currentColor; не кодируйте жёстко цвет или размер иконок в CSS маршрута. - Состояние загрузки должно сохранять исходные ширину и высоту кнопки и предоставлять понятный короткий текст или существующую обратную связь о загрузке; не допускайте скачков панели инструментов из-за переключения текста.
7. Кнопки и ссылки
Действия и навигация должны использовать правильную семантику:
- Для действий на текущей странице, таких как отправка, сохранение, открытие модального окна, переключение состояния, используйте
Buttonбезhref, что в итоге рендерится как<button>. - Для перехода к другому маршруту или ресурсу используйте
Buttonсhref, что в итоге рендерится как Next.js<Link>. - Кнопки без отправки внутри формы должны явно указывать
type="button"; кнопки отправки должны явно указыватьtype="submit". - Не используйте
onClickдля имитации обычной навигации по странице.
Отключённые ссылки используют aria-disabled и выходят из порядка Tab; отключённые нативные кнопки используют disabled. Состояние отключения нельзя выражать только снижением прозрачности; бизнес-логика также должна блокировать действие.
8. Состояния и доступность
Общие компоненты единообразно отвечают за состояния hover, focus-visible, disabled и цвета. Бизнес-код всё ещё должен соответствовать:
- Hover для обычных невыбранных кнопок использует
--control-surface-hover; нажатие, выбор и раскрытие используют--control-surface-active.focus-visibleсохраняет--focus-ringна нейтральных поверхностях; стили маршрута не должны объединять hover и постоянное состояние в одно правило светло-синего цвета. - Названия кнопок должны быть прямыми, конкретными и описывать, что произойдёт, например «Сохранить», «Опубликовать сайт», «Удалить элемент».
IconButtonдолжен предоставлять локализованныйaria-label.- Декоративные иконки используют
aria-hidden="true", чтобы избежать повторного озвучивания скринридером. - Клавиатурный фокус должен быть видимым; CSS маршрута не должен удалять общее кольцо фокуса.
- Не используйте hover как единственную подсказку; взаимодействие должно поддерживать и клавиатуру, и касание.
- Отключённые кнопки используются только для действий, которые пользователь временно не может выполнить; если необходимо объяснить причину, предоставьте пояснение рядом или tooltip.
- Ошибки, требования разрешений, риски, расходы и другая критически важная информация о задаче должны оставаться видимыми; Tooltip может только дополнять информацию, а не быть единственным способом её обнаружения.
- Асинхронные операции должны предотвращать повторную отправку и сохранять понятную обратную связь о процессе выполнения.
- Опасные действия используют
dangerи повторно используют существующий шаблон подтверждения опасных действий; не полагайтесь только на красный цвет для передачи риска. - Текст кнопок на китайском или других языках не должен обрезаться до непонятного состояния. Необходимо проверять длинный текст и ширину на мобильных устройствах.
9. Границы ответственности за стили
Структура, семантика и состояния общих кнопок отвечают Button / IconButton; визуальные токены и общий CSS отвечают пакет компонентов; маршруты отвечают только за макет.
Отвечает общий уровень
- DOM, семантика ссылки/кнопки, поведение disabled;
- Слоты icon/label и ограничения типов доступности;
- Классы variant, size, shape;
- Высота, скругление, внутренние отступы, размер шрифта, насыщенность шрифта;
- Фон, цвет текста, тени, состояния hover, focus-visible и disabled.
Может отвечать уровень маршрута
- Направление, отступы, выравнивание и перенос групп кнопок;
- Адаптивное расположение;
width: 100%или ширина контейнера, необходимые для определённых рабочих процессов;- Классы позиционирования, не изменяющие базовый визуальный стиль.
Не должен отвечать уровень маршрута
- Переопределение высоты, размера шрифта, скругления, фона, цвета текста, теней или кольца фокуса кнопки;
- Повторная реализация общих кнопок с использованием жёстко закодированных цветов или
border-radius: 999px; - Добавление новых локальных визуальных вариантов, таких как
primary-alt,outline-blue,icon-round; - Конкурирование с контрактом общих кнопок через
!important; - Прямое копирование базовых стилей
.qk-ui-button.
Если действительно появляется новый семантический вариант, необходимый для нескольких страниц, сначала следует установить единый контракт в общих ButtonVariant, токенах и primitives.css, а не добавлять стили в маршруте.
10. Краткая справка по API
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Основные свойства Button:
| Свойство | Значение по умолчанию | Описание |
|---|---|---|
variant | primary | Семантический и визуальный уровень |
size | md | Высота, размер шрифта текста и горизонтальные отступы |
shape | pill | Форма скругления Button |
leadingIcon | Нет | Иконка перед текстом |
trailingIcon | Нет | Иконка после текста |
href | Нет | При наличии рендерится как ссылка |
disabled | false | Отключение взаимодействия |
tooltip | Нет | Дополнительный контент для общего Tooltip; не может заменять видимую ключевую информацию или aria-label |
tooltipPlacement | bottom | Предпочтительное направление; общий Tooltip может перевернуться, чтобы остаться в области просмотра |
tooltipPortal | true | Рендеринг за пределами обрезанного контейнера без добавления обёрточного слоя макета |
skin | Нет | Предоставление слотов class и адаптации переменных по контракту skeleton/skin |
IconButton наследует применимые свойства Button, но не предоставляет shape, leadingIcon или trailingIcon; он требует aria-label, по умолчанию variant="ghost".
Рекомендуется явно указывать variant и нативный type кнопки в бизнес-коде, чтобы семантика действия была чётко видна при проверке кода.
11. Часто используемые комбинации
// 主要操作:椭圆形文字按钮
<Button type="submit" variant="primary">
保存
</Button>
// 次要操作
<Button type="button" variant="secondary" onClick={onPreview}>
预览
</Button>
// 低强调文字操作
<Button type="button" variant="ghost" onClick={onCancel}>
取消
</Button>
// 图标 + 文字,仍然使用 Button
<Button
leadingIcon={<PlusIcon aria-hidden="true" />}
type="button"
variant="primary"
>
新建内容
</Button>
// 纯图标:圆形按钮
<IconButton aria-label="更多操作" tooltip="更多操作" type="button">
<MoreIcon aria-hidden="true" />
</IconButton>
// 危险操作
<Button type="button" variant="danger" onClick={openDeleteConfirm}>
删除项目
</Button>12. Контрольный список проверки
Перед отправкой UI, связанного с кнопками, подтвердите:
- Приоритетно ли использовались
ButtonилиIconButton? - Выбран ли правильный компонент для кнопок с текстом и только с иконкой?
- Есть ли только один чёткий
primaryв текущей области задачи? - Используются ли
secondary,ghost,dangerпо семантике, а не по предпочтению цвета? - Сохраняет ли
Buttonплатформы значение по умолчаниюpill, аIconButtonостаётся круглым? - Каждый Tooltip остаётся информационным слоем с компактными скруглениями, а не выглядит как кликабельная овальная кнопка?
- Устранены ли нативные
titleбраузера, всплывающие подсказки CSSdata-tooltip, повторяющиеся подсказки и синонимичные Tooltip текстовых кнопок? - Используются ли только размеры
sm,md,lg, и одинаковы ли высота и размер шрифта в одной группе? - Явно ли установлены правильные
typeдля нативных кнопок? - Скрывают ли иконки повторяющуюся информацию для скринридера, и есть ли у
IconButtonлокализованныйaria-label? - Полны ли состояния focus-visible, disabled, асинхронных операций и подтверждения опасных действий?
- Обрабатывает ли CSS маршрута только макет, не переопределяя базовый визуальный стиль кнопок?
- Проверены ли длинный текст, размеры касания и расположение групп кнопок на ширине десктопа и мобильных устройств?
13. Источники реализации
- API компонента:
packages/components/src/ui/Button/Button.tsx - Экспорты компонента:
packages/components/src/ui/Button/index.ts - Токены размеров и цветов:
packages/components/src/styles/foundations.css - Общие стили кнопок:
packages/components/src/styles/primitives.css - Контракт подключения публичных компонентов:
docs/public/design/component-integration.md
Когда документация и реализация расходятся, компонент, токены, стили и данный документ должны быть синхронизированы в рамках одного изменения.