Skip to Content
設計

Button 按鈕

Button 與 IconButton 的語意、尺寸、形狀、狀態與無障礙規範。

即時元件按鈕/IconButton/AI按鈕

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。

選擇順序:

  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、樣式與本文件。

本頁目錄