Button 按钮
Button 与 IconButton 的语义、尺寸、形状、状态和可访问性规范。
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。
选择顺序:
- 找出当前任务唯一最重要的下一步,将其设为
primary。 - 仍需清晰可见的辅助操作使用
secondary。 - 工具栏或上下文中的低强调操作使用
ghost。 - 只有实际破坏性操作使用
danger,并沿用现有确认流程。
不要根据“哪个颜色更好看”选择 variant。
4. 尺寸 size
| Size | 高度/直径 | 文字字号 | 推荐场景 |
|---|---|---|---|
sm | 40px | 14px | 顶部导航、紧凑工具栏、密集工作区 |
md | 44px | 15px | 默认表单、CMS、对话框和常规操作 |
lg | 48px | 16px | 营销页主要 CTA、需要更强触控性的主操作 |
默认尺寸为 md。
- 同一按钮组使用同一尺寸。
- 紧凑控件不得低于 40px;移动端主要操作优先使用至少 44px。
Button的高度和IconButton的直径使用同一套尺寸 token,因此可以在同一工具栏中对齐;IconButton的可见图标尺寸统一为 18px。Button文字字号由 size 对应的共享 token 决定,不继承 Header、Dialog 或其他父容器的字号。- 路由 CSS 可以控制按钮的排列、间距和必要的宽度,但不能重定义共享按钮的高度或字号。
- 文案较长时优先调整布局或按钮容器,不要通过压缩高度、字体或左右间距解决。
5. 形状 shape
| 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. 按钮与链接
操作和导航必须使用正确语义:
- 提交、保存、打开弹层、切换状态等当前页面操作,使用不带
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 的主要属性:
| 属性 | 默认值 | 说明 |
|---|---|---|
variant | primary | 语义和视觉层级 |
size | md | 高度、文字字号及横向内边距 |
shape | pill | Button 的圆角形状 |
leadingIcon | 无 | 文字前图标 |
trailingIcon | 无 | 文字后图标 |
href | 无 | 提供时渲染为链接 |
disabled | false | 禁用交互 |
tooltip | 无 | 共享 Tooltip 的补充内容;不能替代可见的关键信息或 aria-label |
tooltipPlacement | bottom | 首选方向;共享 Tooltip 可以翻转以保持在视口内 |
tooltipPortal | true | 在裁剪容器之外渲染,且不增加布局包裹层 |
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、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 - 尺寸和颜色 token:
packages/components/src/styles/foundations.css - 共享按钮样式:
packages/components/src/styles/primitives.css - 公开组件接入契约:
docs/public/design/component-integration.md
当文档与实现出现差异时,应在同一个改动中同步组件、token、样式和本文档。