Skip to Content
Дизайн

Кнопка Button

Спецификации семантики, размеров, форм, состояний и доступности для Button и IconButton.

Живой компонентКнопка / IconButton / AIButton

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.

Порядок выбора:

  1. Найдите единственный наиболее важный следующий шаг в текущей задаче и назначьте его как primary.
  2. Для вспомогательных действий, которые всё ещё должны быть чётко видны, используйте secondary.
  3. Для действий с низким акцентом в панели инструментов или контексте используйте ghost.
  4. Только для реально разрушительных действий используйте danger, следуя существующему процессу подтверждения.

Не выбирайте вариант исходя из того, «какой цвет красивее».

4. Размеры size

РазмерВысота/диаметрРазмер шрифтаРекомендуемые сценарии
sm40px14pxВерхняя навигация, компактные панели инструментов, плотные рабочие области
md44px15pxФормы по умолчанию, CMS, диалоги и обычные действия
lg48px16pxОсновные 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:

СвойствоЗначение по умолчаниюОписание
variantprimaryСемантический и визуальный уровень
sizemdВысота, размер шрифта текста и горизонтальные отступы
shapepillФорма скругления Button
leadingIconНетИконка перед текстом
trailingIconНетИконка после текста
hrefНетПри наличии рендерится как ссылка
disabledfalseОтключение взаимодействия
tooltipНетДополнительный контент для общего Tooltip; не может заменять видимую ключевую информацию или aria-label
tooltipPlacementbottomПредпочтительное направление; общий Tooltip может перевернуться, чтобы остаться в области просмотра
tooltipPortaltrueРендеринг за пределами обрезанного контейнера без добавления обёрточного слоя макета
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 браузера, всплывающие подсказки CSS data-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

Когда документация и реализация расходятся, компонент, токены, стили и данный документ должны быть синхронизированы в рамках одного изменения.

На этой странице