Button 按鈕
Button 與 IconButton 的語意、尺寸、形狀、狀態與無障礙規範。
AI按鈕重用按鈕的大小與語意,同時加入明顯且可辨識的 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、樣式與本文件。