@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

package/src/components/Button/button.principles.stories.tsx

@@ -0,0 +1,369 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+import {
+  Plus, Trash2, Settings, RefreshCw,
+  MoreVertical, Save, Maximize2, Share2,
+  ChevronDown, Download, Bell,
+} from 'lucide-react'
+import { Button } from './button'
+import { ButtonGroup } from './button-group'
+import { Badge } from '@/design-system/components/Badge/badge'
+
+const meta: Meta = {
+  title: 'Design System/Components/Button/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-secondary mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-wrap gap-2 items-center">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-secondary'}`}>{children}</p>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── WhenToUse — 何時使用 Button ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Button 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Button/展示" name="危險 語意"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Danger 語意</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Button/展示" name="滑鼠移過 / 鍵盤聚焦"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">滑鼠移過 / 鍵盤聚焦</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Button/展示" name="純圖示加 Tooltip"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">純圖示加 Tooltip</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+    </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div>
+      <Rule
+        title="❌ 不用 Button 做標籤或指示器"
+        note="Button 語義是「可點擊動作」。如果只是顯示狀態、不需使用者互動，用 Badge 或 Tag 代替。Jira 的「已解決」標籤、Stripe 的「active」指示不會設計成按鈕"
+      >
+        <div className="flex gap-2 items-center">
+          <Button variant="primary" size="sm">Active</Button>
+          <Label warn>❌ 當標籤用 → 下方才對</Label>
+        </div>
+        <div className="flex gap-2 items-center mt-3">
+          <Badge count={1} />
+          <Label>✅ Badge 表達計數 / 狀態</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 不用多個 primary 按鈕搶焦點"
+        note="Primary 語義是「這個畫面最重要的動作」。多個 primary 時使用者無法判斷優先順序，改用 primary + secondary + tertiary。Notion 對話框永遠只有一個藍色按鈕"
+      >
+        <div>
+          <div className="mb-4">
+            <Button variant="primary">保存</Button>
+            <Button variant="primary" className="ml-2">另存新檔</Button>
+            <Label warn>❌ 兩個都搶焦點</Label>
+          </div>
+          <div>
+            <Button variant="primary">保存</Button>
+            <Button variant="secondary" className="ml-2">另存新檔</Button>
+            <Label>✅ 主次分明</Label>
+          </div>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 不用 primary + danger 做可反悔的操作"
+        note="primary + danger 語義是「立即不可逆」。如移至垃圾桶還能復原，改用 secondary + danger。Linear 的刪除先確認"
+      >
+        <div>
+          <div className="mb-4">
+            <Button variant="primary" danger startIcon={Trash2}>刪除</Button>
+            <Label warn>❌ 風險高，無法復原</Label>
+          </div>
+          <div>
+            <Button variant="secondary" danger startIcon={Trash2}>移至垃圾桶</Button>
+            <div><Label>✅ secondary + danger，後續可復原</Label></div>
+          </div>
+        </div>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const VariantRule: Story = {
+  name: '變體 選擇',
+  render: () => (
+    <div>
+      <Rule
+        title="primary — 最高視覺重量，每個操作區最多一個"
+        note="這個畫面或操作區最重要的單一主要動作，超過一個主要動作時改用 secondary"
+      >
+        <Button variant="primary" startIcon={Plus}>新增</Button>
+      </Rule>
+
+      <Rule
+        title="secondary — 正面與負面選項並存時的配對"
+        note="兩個並列選項時使用：正面選項用 secondary，負面選項加 danger。若只有一個主要動作，改用 primary"
+      >
+        <Button variant="secondary">儲存草稿</Button>
+        <Button variant="secondary" danger>放棄變更</Button>
+      </Rule>
+
+      <Rule
+        title="tertiary — 最常用的非主要按鈕（日常預設選擇）"
+        note="確認/取消配對的取消方、輔助操作、卡片 CTA 幾乎都用 tertiary"
+      >
+        <Button variant="tertiary">取消</Button>
+        <Button variant="tertiary" startIcon={Save}>另存草稿</Button>
+        <Button variant="tertiary" startIcon={Download}>匯出</Button>
+      </Rule>
+
+      <Rule
+        title="text — 低視覺重量輔助動作"
+        note="不需特別強調的操作；工具列 icon-only 按鈕常用 text"
+      >
+        <Button variant="text" startIcon={RefreshCw}>重新整理</Button>
+        <Button variant="text">查看更多</Button>
+        <Button variant="text" size="sm" iconOnly startIcon={Settings} aria-label="設定" />
+      </Rule>
+
+      <Rule
+        title="pressed prop — 單一功能目前啟用中（binary toggle）"
+        note="設定 pressed 時 Button 自動寫入 aria-pressed + data-state，由 variant 的 data-[state=on] 分支套用樣式。僅 secondary/tertiary/text 支援 toggle 視覺，primary/link 傳入無效果。描述「這個按鈕自己的功能是否開啟」，不表達多選一"
+      >
+        <div className="flex items-center gap-2">
+          <Button variant="text" size="sm" iconOnly startIcon={Maximize2} aria-label="全螢幕（關閉）" />
+          <span className="text-footnote text-fg-muted">→ 啟用後 →</span>
+          <Button variant="text" pressed size="sm" iconOnly startIcon={Maximize2} aria-label="全螢幕（開啟中）" />
+        </div>
+        <Label warn>⚠️ 多選一（視圖切換）不用 pressed → 用 Segmented Control</Label>
+      </Rule>
+
+      <Rule
+        title="link — 帶使用者前往其他頁面的按鈕"
+        note="視覺上像連結但需要 button 行為（React Router、事件處理）。放在內容區，不用於操作列，不嵌入段落文字（段落內用 HTML <a> 代替）"
+      >
+        <Button variant="link">前往設定</Button>
+      </Rule>
+    </div>
+  ),
+}
+
+export const PrimaryRule: Story = {
+  name: '主要按鈕限制',
+  render: () => (
+    <div>
+      <Rule title="✅ 正確 — 唯一的 primary" note="單一最強視覺入口讓使用者立即辨識主要路徑;其餘動作降為 tertiary,避免同一操作區出現競爭焦點。">
+        <Button variant="primary">確認</Button>
+        <Button variant="tertiary">取消</Button>
+      </Rule>
+
+      <Rule title="❌ 錯誤 — 兩個 primary 同時出現，使用者無法判斷優先順序" note="兩個相同最高視覺重量的動作互相競爭,使用者必須先讀文案才能判斷主路徑,因此同一操作區最多保留一個 primary。">
+        <Button variant="primary">儲存</Button>
+        <Button variant="primary">另存新檔</Button>
+        <Label warn>視覺重量相同 → 無法分辨主次</Label>
+      </Rule>
+
+      <Rule
+        title="✅ 卡片清單 CTA 用 tertiary"
+        note="重複出現的 CTA 應使用 tertiary，避免頁面充斥填滿按鈕，稀釋 primary 的信號強度"
+      >
+        {['官網改版', '行動裝置 App', '設計系統'].map(name => (
+          <div key={name} className="border border-border rounded-lg px-4 py-3 flex items-center gap-3 min-w-40">
+            <span className="text-body flex-1">{name}</span>
+            <Button variant="tertiary" size="xs">開啟</Button>
+          </div>
+        ))}
+      </Rule>
+    </div>
+  ),
+}
+
+export const DangerRule: Story = {
+  name: '危險 時機',
+  render: () => (
+    <div>
+      <Rule
+        title="primary + danger — 立即且不可逆，點下去就發生"
+        note="必須是最後一道關卡，沒有後續確認"
+      >
+        <Button variant="primary" danger startIcon={Trash2}>永久刪除</Button>
+        <Button variant="tertiary">取消</Button>
+      </Rule>
+
+      <Rule
+        title="secondary + danger — 有警示意圖但點下去還可反悔"
+        note="通常後面還有一層確認提示"
+      >
+        <Button variant="secondary">儲存草稿</Button>
+        <Button variant="secondary" danger>放棄變更</Button>
+      </Rule>
+
+      <Rule
+        title="text + danger — 低強調的危險操作"
+        note="工具列刪除等有後續確認的場景；視覺干擾最小"
+      >
+        <Button variant="text" danger startIcon={Trash2}>刪除</Button>
+        <Button variant="text" danger size="sm" iconOnly startIcon={Trash2} aria-label="刪除" />
+      </Rule>
+
+      <Rule title="❌ 錯誤 — 在有後續確認的流程中使用 primary danger" note="primary danger 承諾『點下即完成不可逆動作』;若後面還有確認或可復原,提前使用最高危險強度會誤報操作後果。">
+        <Button variant="primary" danger>移至垃圾桶</Button>
+        <Label warn>移至垃圾桶還可以復原 → 不應用 primary danger</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const IconRule: Story = {
+  name: '圖示語意',
+  render: () => (
+    <div>
+      <Rule
+        title="startIcon — 描述這個按鈕做什麼（動詞圖示）"
+        note="icon 是 label 的圖示說明，與文字傳達同一個動作"
+      >
+        <Button variant="primary" startIcon={Plus}>新增</Button>
+        <Button variant="tertiary" startIcon={Download}>匯出</Button>
+        <Button variant="tertiary" startIcon={RefreshCw}>重新整理</Button>
+      </Rule>
+
+      <Rule
+        title="endIcon — 指示按鈕會開啟下一層（展開 / 選單）"
+        note="告訴使用者「點這裡還有更多」，不描述動作本身"
+      >
+        <Button variant="tertiary" endIcon={ChevronDown}>篩選條件</Button>
+        <Button variant="tertiary" startIcon={Bell} endIcon={ChevronDown}>通知</Button>
+      </Rule>
+
+      <Rule
+        title="❌ endIcon 不應使用動詞性圖示"
+        note="endIcon 的位置傳達「這裡可以展開」，放動詞圖示會讓使用者以為有第二個獨立操作"
+      >
+        <Button variant="tertiary" endIcon={Download}>匯出</Button>
+        <Label warn>↑ 右側 Download 讓人以為可以直接下載，與展開選單的意圖衝突</Label>
+      </Rule>
+
+      <Rule
+        title="icon + 下拉指示 — 無文字 dropdown trigger"
+        note="不加 iconOnly（保留 endIcon 展開指示）；必須設定 aria-label"
+      >
+        <Button variant="tertiary" startIcon={Settings} endIcon={ChevronDown} aria-label="設定選項" />
+        <Label>↑ startIcon 描述功能，endIcon 指示展開，兩者並存</Label>
+      </Rule>
+
+      <Rule
+        title="icon + overlay 角標 — 通知類按鈕"
+        note="用 `overlayBadge` prop 傳入 Badge,Button 內部自動把 badge 中心對齊 icon top-right corner(Material BadgedBox 設計準則)——不手刻 `relative + absolute -top-1 -right-1` 讓 badge 飄到按鈕 chrome 邊緣"
+      >
+        <Button
+          variant="tertiary"
+          size="sm"
+          iconOnly
+          startIcon={Bell}
+          aria-label="通知 (3)"
+          overlayBadge={<Badge count={3} variant="critical" />}
+        />
+        <Label>↑ overlayBadge prop 自動定位,Button 保持正方形,badge 貼 icon 不飄 chrome 角</Label>
+      </Rule>
+
+      <Rule
+        title="溢出選單 — 一律 MoreVertical，放在群組末端"
+        note="溢出按鈕是群組的一部分，不是獨立操作層。末端溢出與群組溢出的判斷規則見 Patterns / 操作列"
+      >
+        <ButtonGroup>
+          <Button variant="text" size="sm" iconOnly startIcon={Download} aria-label="匯出" />
+          <Button variant="text" size="sm" iconOnly startIcon={Share2} aria-label="分享" />
+          <Button variant="text" size="sm" iconOnly startIcon={MoreVertical} aria-label="更多操作" />
+        </ButtonGroup>
+        <Label>↑ MoreVertical 在群組末端，左側不加分隔線</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const OrderRule: Story = {
+  name: '排序與對齊',
+  render: () => (
+    <div>
+      <Rule
+        title="視覺重量序列 — 決定按鈕在群組中的相對位置"
+        note="按視覺重量由高至低排列，最強吸引力的動作放在「起點」位置。danger 是顏色疊加，不影響排序位置；同 variant 內 danger 排在非 danger 之後（遠離主要焦點）"
+      >
+        <Button variant="primary">發布</Button>
+        <Button variant="secondary">儲存草稿</Button>
+        <Button variant="secondary" danger>放棄變更</Button>
+        <Button variant="tertiary">預覽</Button>
+        <Button variant="text">查看歷史</Button>
+      </Rule>
+
+      <Rule
+        title="水平排列 — 對齊方向鏡像排序，主按鈕永遠在「起點」"
+        note="靠左：動作由左發起（表單送出），primary 在最左。靠右：動作是確認補充（對話框底部），primary 在最右。排序規則不因對齊方向改變，只是方向鏡像"
+      >
+        <div className="flex flex-col gap-4 w-full">
+          <div className="flex items-center gap-3">
+            <ButtonGroup align="start">
+              <Button variant="primary">確認</Button>
+              <Button variant="tertiary">取消</Button>
+            </ButtonGroup>
+            <Label>靠左 — primary 最左，動作從左發起</Label>
+          </div>
+          <div className="flex items-center justify-between w-full">
+            <Label>靠右 — primary 最右，對話框確認場景</Label>
+            <ButtonGroup align="end">
+              <Button variant="tertiary">取消</Button>
+              <Button variant="primary">確認</Button>
+            </ButtonGroup>
+          </div>
+        </div>
+      </Rule>
+
+      <Rule
+        title="垂直排列 — primary 最上，視覺動線由上往下"
+        note="使用者眼睛最先掃到最上方，最希望被點擊的動作放第一個。所有按鈕撐滿容器寬度"
+      >
+        <div className="w-[200px]">
+          <ButtonGroup orientation="vertical">
+            <Button variant="primary">確認送出</Button>
+            <Button variant="tertiary">取消</Button>
+          </ButtonGroup>
+        </div>
+      </Rule>
+
+      <Rule
+        title="Toolbar 場景"
+        note="Toolbar 中業務操作與工具操作的全局排序、分隔線規則、溢出機制見 Patterns / 操作列"
+      >
+        <span className="text-caption text-fg-muted">→ Design System / Patterns / 操作列</span>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Button/button.spec.md

@@ -8,18 +8,18 @@ traits:
   - hasSizes
   - hasInteractiveStates
 variants:
-  primary:    # ★ cva default
-    when: "主要 action / CTA"
+  primary:
+    when: "主要 action / CTA。**必 explicit `variant=\"primary\"`,不靠預設**(2026-06-06 起預設改低 emphasis)"
     world-class: ["Polaris Button primary", "Material Filled Button", "Atlassian Primary"]
   secondary:
     when: "陪襯 primary 的次要 action"
     world-class: ["Polaris Button default", "Material Tonal Button"]
-  tertiary:
-    when: "第三級 action(tool-like / icon-heavy)"
-    world-class: ["Material Outlined Button"]
-  text:
-    when: "文字樣式 — low emphasis / toolbar embedded"
-    world-class: ["Ant Button type=text", "Material Text Button"]
+  tertiary:    # ★ labeled cva default(2026-06-06 從 primary 改 — 對齊世界級「預設低 emphasis、按重要程度升」)
+    when: "**labeled 按鈕預設** / 第三級 action(tool-like / icon-heavy)。中性外框、清楚可點性,再按重要程度升 primary"
+    world-class: ["Material Outlined Button", "Ant Button default", "Polaris tertiary"]
+  text:    # ★ iconOnly cva default(2026-06-06 加)
+    when: "文字樣式 — low emphasis / toolbar embedded。**iconOnly 按鈕預設**(對齊 action-bar「純動作工具→text」+ Material 3「icon-only = no fill」)"
+    world-class: ["Ant Button type=text", "Material Text Button", "Material 3 icon-only no-fill"]
   link:
     when: "內文連結 — inline reading context"
     world-class: ["Polaris Link", "Ant Button type=link"]
@@ -47,7 +47,6 @@ benchmark:
   - Carbon Button: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Button
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 > **Foundational SSOT rationale**(cap 800,2026-04-25 approved):
 > Family 3 (Pill Layout) SSOT owner。SegmentedControlItem / Chip / Tag 繼承 Pill 結構;Dismiss canonical(X icon 色處理)cascade 到全 DS inline actions;Button sm/md/lg 與 Field sm/md/lg size pairing 是系統級 invariant。scope 本質 > 單一元件。
@@ -59,7 +58,7 @@ benchmark:
 Button 是最基礎的互動元件，用於觸發操作或導覽。
 基於 shadcn/ui Button，橋接設計系統 token，支援 uiSize 自動縮放。
 
-**Layout Family**：本元件是 **CLAUDE.md 4-Family Model Family 3（Pill Layout）的 SSOT 擁有者 + action trigger sub-profile canonical**。SegmentedControlItem / Chip / Tag 繼承本元件的 Pill Layout 結構。
+**Layout Family**：依 `patterns/element-anatomy/element-anatomy.spec.md` 的 4-Family taxonomy,本元件是 **Family 3（Pill Layout）的 SSOT 擁有者 + action trigger sub-profile canonical**。SegmentedControlItem / Chip / Tag 繼承本元件的 Pill Layout 結構。
 
 ---
 
@@ -89,17 +88,16 @@ Button 是最基礎的互動元件，用於觸發操作或導覽。
 **結構**：
 
 ```
-[startIcon? 16/20px] [<span px-1>label</span>] [<span gap-1>badge? + endIcon?</span>]
+[startIcon? 16/20px] [label(兩側隱性 4px 呼吸)] [badge? + endIcon?(內部 4px)]
 ```
 
 - 單行不 wrap
 - Label 兩側隱性 4px 呼吸(icon ↔ label / label ↔ suffix 對稱)
 - 右側 suffix(badge + endIcon)內部 4px
 
-**為什麼用 label 兩側隱性呼吸而非外層 gap**:
-- Icon-only(無 label)→ 外層 padding 公式 `(field-height - icon)/2` 自然對齊,無需 gap
-- Has-label → label 兩側隱性 4px 給 icon 跟文字之間 / label 跟 suffix 之間,**單一規則產生兩側 symmetric spacing**
-- 若用外層 gap-1,icon-only 時要再加條件移除;label 兩側機制更穩(實作 class 細節詳 `button.tsx`)
+**間距機制(對齊 button.tsx 實作)**:
+- Has-label → 外層 `gap-1`(sm/md/lg;xs 為 `gap-0`)+ label 兩側隱性 `px-1` **並用**:label 兩側對稱呼吸由 `px-1` 單一規則產生;icon ↔ label 實際視覺間距 = gap + padding = 8px(xs 為 4px)
+- Icon-only(無 label)→ `ICON_ONLY_BASE`(`aspect-square p-0 gap-0`,padding-free 派)條件移除 padding 與 gap,從 `h-field-X` 推 width=height,flex-center 讓 icon 自然置中
 
 ### Sub-profile 1: Action trigger（canonical: Button）
 
@@ -120,7 +118,7 @@ Members: **Button, SegmentedControlItem, Chip**。
 - **24px 固定**（不隨 density 縮放），配合工具列密集排佈
 - **主要用法**: icon-only（無 label 或極短 label），text editor / design canvas toolbar 情境
 - **不配對 Field**（Field 家族用 sm/md/lg），純 standalone utility
-- **Icon-only 時**自動套用 `px-[calc((field-height-xs - 16px)/2)]` = `px-1`（4px）以產生正方形 hit box
+- **Icon-only 時**套用 `ICON_ONLY_BASE`（`aspect-square p-0 min-w-0 gap-0`，padding-free 派），靠 `aspect-square` 從 `h-field-xs` 推 width=height 產生正方形 hit box（詳「iconOnly 的邊界」節）
 
 雖然 code 允許 xs 帶短 label（text-caption 12px），但**主要場景應該是 icon-only**。有 label 的 compact button 建議直接用 `sm`（28px）。
 
@@ -144,7 +142,7 @@ Tag md 和 Button xs 同 24px，但：
 - Tag md `px-1` / text-body 14px / font-normal / cursor-text
 - Button xs `px-2` / text-caption 12px / font-medium / cursor-pointer
 
-**不統一的世界級理由**（對照 Material / Polaris / Atlassian / Ant / Carbon 共識）： <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**不統一的 DS 內部理由**：
 - **padding 跟著 role**：action 要大命中區 + 視覺重量；indicator 要緊湊低視覺權重
 - **font-weight 跟著 role**：action medium（吸引點擊）；indicator normal（passive 讀取）
 - **font-size 跟著 pairing**：Tag md pair Field md（14px field typography）；Button xs 是 standalone utility button（compact toolbar，用 12px）
@@ -169,7 +167,7 @@ Tag md 和 Button xs 同 24px，但：
 
 - `startIcon`：最多一個，放在最左側
 - `badge` 和 `endIcon` 可同時出現在右側
-- `badge` 傳入 Badge 元件（通知計數指示器）。Badge 層級應匹配按鈕的視覺重量——深色底按鈕（primary、secondary+danger）只適合 `critical`，詳見 `badge.spec.md`
+- `badge` 傳入 Badge 元件（通知計數指示器）。Badge 層級受按鈕底色的 contrast floor 約束——深色底按鈕（primary、secondary+danger）floor 為 `high`（`high` / `critical` 可直接用；`low` / `medium` 被迫 bump 是設計錯配訊號），詳見 `badge.spec.md`「各容器的 contrast floor 對照」
 
 ---
 
@@ -189,8 +187,8 @@ Variant 控制**視覺強調等級**（visual weight），不決定語意意圖
 
 **世界級對照(per-variant)**:
 - `primary` ≈ Material `Filled` / Polaris `Primary` / Ant `type="primary"` / Carbon `Primary`
-- `secondary` ≈ Material `Outlined` / Polaris `Default` / Ant `type="default"` / Carbon `Secondary`
-- `tertiary` ≈ Material `Tonal/Filled Tonal` / Atlassian `Subtle` / Ant `type="dashed"`(近似)
+- `secondary` ≈ Material `Tonal/Filled Tonal` / Polaris `Default` / Carbon `Secondary`
+- `tertiary` ≈ Material `Outlined` / Ant `type="default"` / Polaris `tertiary`
 - `text` ≈ Material `Text` / Polaris `Plain` / Ant `type="text"` / Atlassian `Subtle-Link`
 - `link` ≈ Polaris `Plain+removeUnderline=false` / Ant `type="link"` / Apple HIG Borderless
 
@@ -274,7 +272,7 @@ const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
 
 完整 rationale(包含 2026-04-25 從 padding-formula 派切換的 bug origin)+ 4 家世界級對照 → **SSOT 在 `tokens/uiSize/uiSize.spec.md`「Icon-only 元件的 padding canonical」節**。本 spec 不重複,只 pointer。
 
-**icon-only 按鈕內建自動 tooltip：** 當 `iconOnly` 為 true 時，Button 自動以 `aria-label` 的值渲染 tooltip。開發者不需要額外包 `<Tooltip>`——tooltip 是元件保證的行為，不是開發者「記得要加」的外部組合。
+**icon-only 按鈕內建自動 tooltip：** 當 `iconOnly` 為 true 且非 `asChild` 時，Button 自動以 `aria-label` 的值渲染 tooltip（`asChild` 因 Radix Slot 單 child 限制不包 Tooltip，consumer 需自包）。開發者不需要額外包 `<Tooltip>`——tooltip 是元件保證的行為，不是開發者「記得要加」的外部組合。
 
 `aria-label` 是給螢幕閱讀器的，tooltip 是給所有人看的，兩者語意相同，由同一個值驅動。
 
@@ -300,10 +298,12 @@ const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
 - `disabled` 本身**不代表**正在載入；若需傳達載入中，應同時設定 `loading`
 - disabled 時品牌 / 狀態色完全移除，統一回到 neutral——避免「可用但弱化」的視覺誤導
 - danger 在 disabled 時同樣消失，呈現與非 danger 版本相同的外觀
+- `pressed` + disabled 並存:**disabled 視覺優先**——pressed 底色被 disabled token 取代(state > emphasis,同 M24 precedence;`aria-pressed` 語意仍保留)
+- 常見誤解:「disabled 時 badge 還能傳達待辦數」——badge 不應與 disabled / loading 並存(使用者無法互動,計數成誤導;規則同 loading 段)
 
 ### loading
 
-顯示 `CircularProgress`(indeterminate),自動 disabled,設定 `aria-busy`。
+顯示 `CircularProgress`(indeterminate),自動 disabled(`disabled={disabled || loading}`),設定 `aria-busy`。disabled + loading 並存時視覺以 disabled neutral token 為底,spinner 照常渲染(`text-current` 繼承 disabled 文字色)。
 
 **CircularProgress 永遠在左側(`startIcon` 位置)**,方向與行動發起一致:
 - 有 `startIcon` → icon 換成 CircularProgress(同位置替換)
@@ -340,16 +340,16 @@ const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
 |------|------|--------|
 | `variant` | **強制 `text`**(由 `dismiss` prop 內部 override)| 其他 variant chrome 太強,搶 dismiss 弱化語意 |
 | Icon 色 default | **`fg-muted`**(override Button text variant 預設 `foreground`) | 對齊 Inline Action dismiss 弱化,cross-implementation 一致 |
-| Icon 色 hover | `foreground` | 對齊 Inline Action hover |
+| Icon 色 hover | `fg-secondary` | 對齊 Inline Action 的一階 hover |
 | `iconOnly` | **強制 true** | dismiss 必 icon-only,帶 label 違反「可忽略」本質 |
 
 #### 觸發條件(Button 限定)
 
 **觸發** `dismiss` prop override:
-- `<Button dismiss />` 明示
-- callback = `onClose` / `onDismiss`(X close 語意)
+- `<Button dismiss />` 明示(唯一機械觸發;Button 無 `onClose` / `onDismiss` prop,不依 callback 自動觸發)
+- 語意判準:consumer 的點擊語意是 X close(關閉 surface / 忽略訊息)→ 應傳 `dismiss`
 
-**不觸發**(這些 callback 語意非 dismiss):
+**不該用 dismiss**(這些 callback 語意非 dismiss):
 - `onRemove` — collection 層面移除 item(用一般 Button / Inline Action)
 - `onClear` — 欄位清空 value(用 Inline Action)
 - `onDelete` — destructive remove(用一般 primitive,icon 選 Trash 自帶破壞性語意)
@@ -361,17 +361,18 @@ const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
 - FileItem / DataTable **row delete(Trash icon)**→ 一般 Button xs 或 Inline Action(看 row size),**不套 dismiss**
 - Tag dismiss X / Input clear X → Inline Action(host chrome padding 內,不是 Button)
 
-完整 predicate 見 `patterns/element-anatomy/item-anatomy.spec.md`「Predicate」+「Dismiss canonical」。
+完整 predicate 見 `patterns/element-anatomy/inline-action.spec.md`「Predicate:Inline Action vs Button iconOnly」+「Dismiss canonical — X close only」（2026-04-24 自 item-anatomy.spec.md 抽出）。
 
 #### `data-unbounded` attribute(2026-04-22 v5 canonical)
 
 Button 自動加 **`data-unbounded="true"`** attribute 當 **`variant === 'text'` OR `dismiss === true`** 任一成立。這是 DS-wide 視覺邊界 marker,讓容器(如 SurfaceHeader)可用 CSS selector 對無視覺邊界 button 套 layout 調整。
 
-**實際應用**:`SurfaceHeader` / `SurfaceFooter` 內建 CSS rule:
+**實際應用**:`SurfaceHeader` 內建 CSS rule(SSOT 在 `overlay-surface.tsx` `CHROME_UNBOUNDED_SLOT`,此處僅引述不重述完整公式;`SurfaceFooter` 不套此 rule):
 ```css
-[&_[data-unbounded]]:my-[calc((var(--field-height-xs) - var(--field-height-sm)) / 2)]
+[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,calc(var(--font-body-lg-size)*1.5))-var(--field-height-sm))/2)]
 ```
-→ md: my=-2px / lg: my=-4px
+→ slot 高度由 `--chrome-slot-h` 參數化(default 衍生 `calc(var(--font-body-lg-size)*1.5)`=24;Popover-tier override = `COMPACT_HEADER_SLOT` 衍生 21;皆 title 字級改自動跟)
+→ default(md): my=-2px / lg: my=-4px
 → 效果:Button native size 不變(sm 28/32,touch target 亦同),**layout 佔位縮到 24**(等效 xs 幾何),header = 24 + 2×tight = 48/56 = `--chrome-header-height` ✓
 
 **詳**:`patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」+ `tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」。
@@ -411,7 +412,7 @@ Button 自動加 **`data-unbounded="true"`** attribute 當 **`variant === 'text'
 - ❌ `startIcon` 不得放超過一個
 - ❌ `link` variant 不得嵌入段落文字——用 HTML `<a>` 代替
 - ❌ 不得直接使用 `variant="destructive"` 或 `variant="ghost"`——shadcn 內部 alias，僅供框架元件使用
-- ❌ `danger` 僅支援 `primary`、`secondary`、`text`——`tertiary` + danger 與 secondary 視覺完全相同（冗餘），`link` + danger 語義矛盾（連結暗示導覽，非破壞）
+- ❌ `danger` 僅支援 `primary`、`secondary`、`text`——`tertiary` + danger 無對應 compoundVariant,會靜默渲染成一般 tertiary（灰、無紅色 danger 視覺,並非等同 secondary),`link` + danger 語義矛盾（連結暗示導覽，非破壞）
 - ❌ `pressed` 不得用於多選一——應使用 Segmented Control
 - ❌ `pressed` 不得套用於 `primary` / `link`——主要操作不應 toggle、link 語意為導覽
 - ❌ `iconOnly` 不可與 `endIcon` 或 `badge` 並用——會破壞正方形結構
@@ -432,9 +433,9 @@ N/A(action trigger,無資料層)。
 
 ## A11y 預設
 
-**ARIA / Pattern**:繼承 Radix `slot` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/slot#accessibility)。
+**ARIA / Pattern**:預設渲染原生 `<button>`,自動繼承瀏覽器原生按鈕語意(button role / Enter / Space 觸發 / Tab 聚焦),無需額外 ARIA。`asChild` 時改用 Radix `Slot` 把 props 合併到 consumer child element(Slot 為純 prop-merger,a11y 仍由該 child 自負)。icon-only 模式傳入 `aria-label` 描述用途;**僅在非 `asChild` 時**自動包 Tooltip(`asChild` 因 Radix Slot 單 child 限制不包,consumer 需自管 child 的 `aria-label` 與 Tooltip)。`pressed` 定義時自動寫 `aria-pressed` + `data-state`。
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:鍵盤聚焦時(`focus-visible`)顯示 focus ring(`focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1`,以 box-shadow 實作並 `outline-none`);滑鼠點擊不觸發。Button 為單一互動元件,**不含** focus trap / focus restoration(那是 Dialog / 浮層的概念)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -442,19 +443,21 @@ N/A(action trigger,無資料層)。
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `action-bar.spec.md`
 - `alert.spec.md`
+- `badge.spec.md`
 - `bulk-action-bar.spec.md`
 - `chip.spec.md`
 - `data-table.spec.md`
 - `dropdown-menu.spec.md`
 - `element-anatomy.spec.md`
 - `file-upload.spec.md`
+- `header-canonical.spec.md`
+- `item-anatomy.spec.md`
+- `overlay-surface.spec.md`
+- `pagination.spec.md`
+- `segmented-control.spec.md`
 - `switch.spec.md`
+- `tabs.spec.md`
 - `tag.spec.md`
 - `tooltip.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `header-canonical.spec.md`