Skip to Content
设计

Button 按钮

Button 与 IconButton 的语义、尺寸、形状、状态和可访问性规范。

实时组件Button / IconButton / AIButton

AIButton 复用 Button 的尺寸与语义,同时增加独特的、可感知的 Qokit AI 状态。

选择 AI 按钮以预览其运行状态。

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。
  • 不要给 IconButton 设置 shape;圆形是它的组件契约。

不应使用 Button 的场景

  • 页签使用 Tabs/PillTabs/Segmented 等对应组件。
  • 菜单项使用 Menu/ActionMenu 对应组件。
  • 状态、标签和筛选结果使用 Pill 或状态组件。
  • 普通文本导航使用语义链接;只有需要按钮级视觉强调时才使用带 href 的 Button。

3. 语义层级 variant

Variant含义典型场景使用限制
primary当前区域的主要操作保存、发布、创建、立即体验一个任务区域通常只保留一个主操作
secondary明确但次一级的操作预览、取消、返回、导入不应和主操作争夺视觉注意力
ghost低强调、上下文工具操作关闭、更多、工具栏操作、轻量返回默认透明,不能作为唯一的关键 CTA
danger会删除或造成明显破坏的操作删除项目、移除内容、清空数据只表达破坏性语义,不作为普通强调色

variant 表达的是语义和视觉层级,不是形状。例如 ghost 可以是带文字的椭圆按钮,也可以是圆形 IconButton。

选择顺序:

  1. 找出当前任务唯一最重要的下一步,将其设为 primary。
  2. 仍需清晰可见的辅助操作使用 secondary。
  3. 工具栏或上下文中的低强调操作使用 ghost。
  4. 只有实际破坏性操作使用 danger,并沿用现有确认流程。

不要根据“哪个颜色更好看”选择 variant。

4. 尺寸 size

Size高度/直径文字字号推荐场景
sm40px14px顶部导航、紧凑工具栏、密集工作区
md44px15px默认表单、CMS、对话框和常规操作
lg48px16px营销页主要 CTA、需要更强触控性的主操作

默认尺寸为 md。

  • 同一按钮组使用同一尺寸。
  • 紧凑控件不得低于 40px;移动端主要操作优先使用至少 44px。
  • Button 的高度和 IconButton 的直径使用同一套尺寸 token,因此可以在同一工具栏中对齐;IconButton 的可见图标尺寸统一为 18px。
  • Button 文字字号由 size 对应的共享 token 决定,不继承 Header、Dialog 或其他父容器的字号。
  • 路由 CSS 可以控制按钮的排列、间距和必要的宽度,但不能重定义共享按钮的高度或字号。
  • 文案较长时优先调整布局或按钮容器,不要通过压缩高度、字体或左右间距解决。

5. 形状 shape

Shape表现使用范围
pill全圆角;带文字时为椭圆形平台默认,适用于营销页、Dashboard、Builder、CMS 和 Admin
rounded12px 圆角仅用于生成站点主题明确要求较小圆角时

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. 按钮与链接

操作和导航必须使用正确语义:

  • 提交、保存、打开弹层、切换状态等当前页面操作,使用不带 href 的 Button,最终渲染为 <button>。
  • 前往另一个路由或资源,使用带 href 的 Button,最终渲染为 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 不得移除共享 focus ring。
  • 不要把 hover 作为唯一提示,交互必须同时支持键盘和触控。
  • 禁用按钮只用于用户暂时无法执行的动作;如果需要解释原因,应提供邻近说明或 tooltip。
  • 错误、权限要求、风险、费用和其他任务关键信息必须保持可见;Tooltip 只能补充信息,不能成为发现这些信息的唯一方式。
  • 异步操作要防止重复提交,并保留可理解的进行中反馈。
  • 危险操作使用 danger,并复用现有危险确认 pattern;不要只依赖红色传达风险。
  • 中文或其他语言的按钮文案不得截断到无法理解。必须验证长文案和移动端宽度。

9. 样式职责边界

共享按钮的结构、语义和状态由 Button / IconButton 负责;视觉 token 和共享 CSS 由组件包负责;路由只负责布局。

共享层负责

  • DOM、链接/按钮语义、disabled 行为;
  • icon/label 槽位和可访问性类型约束;
  • variant、size、shape class;
  • 高度、圆角、内边距、字号、字体权重;
  • 背景、文字颜色、阴影、hover、focus-visible 和 disabled 状态。

路由层可以负责

  • 按钮组方向、间距、对齐和换行;
  • 响应式排列;
  • 特定工作流需要的 width: 100% 或容器宽度;
  • 不改变基础视觉的定位类名。

路由层不得负责

  • 重写按钮高度、字号、圆角、背景、文字颜色、阴影或 focus ring;
  • 使用硬编码颜色或 border-radius: 999px 重新实现共享按钮;
  • 新增 primary-alt、outline-blue、icon-round 等局部视觉变体;
  • 用 !important 与共享按钮契约竞争;
  • 直接复制 .qk-ui-button 的基础样式。

如果确实出现多个页面都需要的新语义变体,应先在共享 ButtonVariant、token 和 primitives.css 中建立统一契约,而不是在路由中新增样式。

10. API 速查

type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';

Button 的主要属性:

属性默认值说明
variantprimary语义和视觉层级
sizemd高度、文字字号及横向内边距
shapepillButton 的圆角形状
leadingIcon无文字前图标
trailingIcon无文字后图标
href无提供时渲染为链接
disabledfalse禁用交互
tooltip无共享 Tooltip 的补充内容;不能替代可见的关键信息或 aria-label
tooltipPlacementbottom首选方向;共享 Tooltip 可以翻转以保持在视口内
tooltipPortaltrue在裁剪容器之外渲染,且不增加布局包裹层
skin无按 skeleton/skin 契约提供 class 槽位和变量适配

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
  • 尺寸和颜色 token:packages/components/src/styles/foundations.css
  • 共享按钮样式:packages/components/src/styles/primitives.css
  • 公开组件接入契约:docs/public/design/component-integration.md

当文档与实现出现差异时,应在同一个改动中同步组件、token、样式和本文档。

本页目录