@qijenchen/design-system 0.1.0-beta.85 → 0.1.0-beta.86

package/src/components/AppShell/app-shell.stories.tsx

@@ -68,7 +68,7 @@ const ISSUE_COLUMNS = [
  *
  * Per codex Layer B D3(2026-05-20):row-driven Aside trigger 才符合 Linear/Notion/Jira/Airtable
  * production 真實情境。row 右側 dedicated action button(`Button variant="text" size="xs" iconOnly`
- * per data-table.spec L193 canonical)→ click 開 Aside + 被選 issue active visual(pressed prop)。
+ * per data-table.spec L153 rowActions canonical)→ click 開 Aside + 被選 issue active visual(pressed prop)。
  * AppShell header toggle 降級為 secondary show/hide 不是主入口。
  */
 function IssuesView({ selectedId, asideOpen, onSelectIssue }: { selectedId?: string; asideOpen: boolean; onSelectIssue: (issue: Issue) => void }) {
@@ -118,7 +118,6 @@ function IssuesView({ selectedId, asideOpen, onSelectIssue }: { selectedId?: str
             </PopoverTrigger>
             <PopoverContent align="end" className="w-auto p-0">
               <DataTableFilterPanel
-                mode="flat"
                 columns={ISSUE_COLUMNS as any}
                 value={filterTree}
                 onChange={setFilterTree}
@@ -150,7 +149,7 @@ function IssuesView({ selectedId, asideOpen, onSelectIssue }: { selectedId?: str
         </div>
       </div>
       {/* DataTable:naked structure,layoutSpace 規則 1B 父層 mx 對齊 chrome 內容左右邊界。
-          rowActions:per data-table.spec L193 canonical(Button text xs iconOnly,固定 24px)+
+          rowActions:per data-table.spec L153 rowActions canonical(Button text xs iconOnly,固定 24px)+
           pressed={row.id === selectedId} 顯示當前選中(per codex D3 active visual)。 */}
       <div className="flex-1 min-h-0 mx-[var(--layout-space-loose)] mb-[var(--layout-space-loose)]">
         <DataTable
@@ -226,7 +225,7 @@ function IssueDetail({ issue }: { issue: Issue | null }) {
           <Tag size="sm" color={PRIORITY_COLOR[issue.priority]}>{issue.priority}</Tag>
         </div>
       </div>
-      <DescriptionList direction="horizontal" divided>
+      <DescriptionList orientation="horizontal" divided>
         <DescriptionItem label="Assignee">{issue.assignee}</DescriptionItem>
         <DescriptionItem label="Due">{issue.due}</DescriptionItem>
       </DescriptionList>
@@ -374,7 +373,7 @@ export const PrimarySidebarWithTabs: Story = {
 /**
  * primary-header mode(GitHub / Gmail / Slack 派)— global header 橫跨頂部 + local header 仍在 main col 頂。
  *
- * @usage-ref: app-shell.spec.md L74(primary-header 2-layer model)
+ * @usage-ref: app-shell.spec.md「primary-header = primary-sidebar + 一條 global header」段(2-layer model)
  * @usage-consumes: ChromeHeader + Sidebar viewportInsetTop + GlobalHeader + PageHeader + IssuesView
  *
  * 2026-05-21 v2 per user clarification「primary-header = primary-sidebar + 一條 global header」:

package/src/components/Avatar/avatar.tsx

@@ -375,7 +375,7 @@ export const avatarMeta = {
   // — item-anatomy AVATAR_SIZE 查表 / ProfileCard 40 等),無 discrete tier → 兩欄留空為 intentional 非漏填
   variants: {},
   sizes: {},
-  states: ['default', 'focus-visible', 'disabled'], // 2026-06-11 R2:本身無自有 hover/active(spec L279;hoverCard 互動屬 HoverCard),
+  states: ['default', 'focus-visible', 'disabled'], // 2026-06-11 R2:本身無自有 hover/active(spec「StateBehavior 範疇」段;hoverCard 互動屬 HoverCard),
   tokens: {
     bg: ['bg-surface-raised'],
     fg: ['--foreground', '--on-emphasis'],

package/src/components/Badge/badge.spec.md

@@ -379,14 +379,14 @@ Badge 是**計數 / 狀態視覺指示器**,本身**非互動元件**:
 - Badge 通常依附在互動元件上(Button / Nav Item),那些元件有自己的 state——Badge 隨父層視覺連動,不擁有獨立 state。
 - 計數變化(`count` 更新)屬資料更新不是 UI state 切換。
 
-對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix`。
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix` + `Accessibility`。
 
 ---
 
 ## 相關
 
 - `../Tag/tag.spec.md` — 分類標籤、狀態標記（Badge vs Tag 的詳細對照在本 spec 定位段落）
-- `../Avatar/avatar.spec.md` — `badgeCount` 內部消費 `<Badge variant="critical">`（遵循本 spec）;`status` 是 Avatar 自有 presence SVG（非 Badge 系統）,兩者可並存,詳該 spec
+- `../Avatar/avatar.spec.md` — `badgeCount` 內部消費 `<Badge variant="critical">`（遵循本 spec）;`status` 是 Avatar 自有 presence dot（內部 `span` + inline backgroundColor,非 Badge 系統）,兩者可並存,詳該 spec
 - `../Button/button.spec.md` — iconOnly Button + Badge overlay 通知 icon 的組合模式
 - `../Chip/chip.spec.md` — 可互動 filter（不是 Badge 的用途）
 - `../CircularProgress/circular-progress.spec.md` — Loading 狀態指示(取代 Spinner)

package/src/components/Breadcrumb/breadcrumb.anatomy.stories.tsx

@@ -342,19 +342,23 @@ export const StateBehavior: Story = {
           <Breadcrumb>
             <BreadcrumbList>
               <BreadcrumbItem>
-                <BreadcrumbLink href="#">Link(預設 fg-secondary)</BreadcrumbLink>
+                <BreadcrumbLink href="#">團隊空間</BreadcrumbLink>
               </BreadcrumbItem>
               <BreadcrumbSeparator />
               <BreadcrumbItem>
-                <BreadcrumbLink href="#">Hover 我(→ primary-hover)</BreadcrumbLink>
+                <BreadcrumbLink href="#">設計系統</BreadcrumbLink>
               </BreadcrumbItem>
               <BreadcrumbSeparator />
               <BreadcrumbItem>
-                <BreadcrumbPage>Current Page(foreground, 不可點)</BreadcrumbPage>
+                <BreadcrumbPage>元件規格</BreadcrumbPage>
               </BreadcrumbItem>
             </BreadcrumbList>
           </Breadcrumb>
         </div>
+        <p className="text-footnote text-fg-muted mt-3">
+          「團隊空間」「設計系統」為可點連結(預設 fg-secondary,移上去 hover 轉 primary-hover);
+          末項「元件規格」為當前頁(foreground,不可點)。
+        </p>
       </div>
     </div>
   ),

package/src/components/Breadcrumb/breadcrumb.principles.stories.tsx

@@ -18,7 +18,7 @@ import {
   DropdownMenuContent,
   DropdownMenuItem,
 } from '@/design-system/components/DropdownMenu/dropdown-menu'
-import { Tabs, TabsList, TabsTrigger } from '@/design-system/components/Tabs/tabs'
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/design-system/components/Tabs/tabs'
 import { Button } from '@/design-system/components/Button/button'
 
 const meta: Meta = {
@@ -159,6 +159,9 @@ export const UsageGuidance: Story = {
               <TabsTrigger value="customers">顧客</TabsTrigger>
               <TabsTrigger value="products">產品</TabsTrigger>
             </TabsList>
+            <TabsContent value="orders" className="text-body text-fg-muted mt-2">訂單列表、篩選與批次出貨</TabsContent>
+            <TabsContent value="customers" className="text-body text-fg-muted mt-2">顧客名單、分群與生命週期價值</TabsContent>
+            <TabsContent value="products" className="text-body text-fg-muted mt-2">商品目錄、庫存與上下架狀態</TabsContent>
           </Tabs>
         </div>
       </Rule>

package/src/components/Breadcrumb/breadcrumb.stories.tsx

@@ -190,7 +190,7 @@ export const DeclarativeAutoCollapse: Story = {
           <Breadcrumb>
             <BreadcrumbList
               items={[
-                { label: 'Long Organization Name', href: '/org' },
+                { label: 'Global Platform Infrastructure Group', href: '/org' },
                 { label: 'Product Engineering Team', href: '/team' },
                 { label: 'Design System Component Refactor Sprint 23' },
               ]}

package/src/components/BulkActionBar/bulk-action-bar.anatomy.stories.tsx

@@ -46,7 +46,7 @@ export const Overview: Story = {
                 <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
               </>
             }
-            onClear={() => {}}
+            onClearSelection={() => {}}
           />
         </div>
       </section>
@@ -87,7 +87,7 @@ export const Overview: Story = {
             <BulkActionBar
               selection={Array.from({ length: 50 }, (_, i) => `f-${i}`)}
               actions={<Button variant="tertiary" size="md" startIcon={Download}>下載</Button>}
-              onClear={() => {}}
+              onClearSelection={() => {}}
             />
           </div>
         </div>
@@ -115,7 +115,7 @@ function SelectionStateDemo() {
               <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
             </>
           }
-          onClear={() => setCount(0)}
+          onClearSelection={() => setCount(0)}
         />
         {count === 0 && <span className="text-caption text-fg-muted italic px-3 py-2 inline-block">↑ count=0 → BulkActionBar 不渲染</span>}
       </div>
@@ -162,7 +162,7 @@ function InspectorInner() {
               <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
             </>
           }
-          onClear={() => setSelectionCount(0)}
+          onClearSelection={() => setSelectionCount(0)}
         />
         {selectionCount === 0 && <span className="text-caption text-fg-muted italic px-3 py-2 inline-block">selection=0 → 不渲染</span>}
       </div>
@@ -196,7 +196,7 @@ export const Accessibility: Story = {
       <section>
         <H3>鍵盤(預期 consumer 在 page 層級監聽)</H3>
         <ul className="list-disc list-inside text-caption text-fg-secondary space-y-1">
-          <li><kbd>Esc</kbd> → 觸發 <code>onClear()</code>(consumer 在 page-level keydown 監聽)</li>
+          <li><kbd>Esc</kbd> → 觸發 <code>onClearSelection()</code>(consumer 在 page-level keydown 監聽)</li>
           <li>Tab 序:close → actions(count 是純文字 / aria 朗讀對象,非 tab stop)</li>
           <li>Hint CTA 是 <code>{`<button>`}</code>,鍵盤可達</li>
         </ul>
@@ -216,7 +216,7 @@ export const Accessibility: Story = {
                 <Button variant="tertiary" size="md" startIcon={Trash2} danger disabled>刪除(無權限)</Button>
               </>
             }
-            onClear={() => {}}
+            onClearSelection={() => {}}
           />
         </div>
       </section>

package/src/components/BulkActionBar/bulk-action-bar.principles.stories.tsx

@@ -83,7 +83,7 @@ export const UsageGuidance: Story = {
                 <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
               </>
             }
-            onClear={() => {}}
+            onClearSelection={() => {}}
           />
           <Label>↑ selection {`>`} 0 浮現,= 0 完全藏</Label>
         </Rule>
@@ -160,7 +160,7 @@ export const ActionVariantRule: Story = {
               <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
             </>
           }
-          onClear={() => {}}
+          onClearSelection={() => {}}
         />
         <Label>↑ tertiary 主 / tertiary danger 破壞性</Label>
       </Rule>
@@ -177,7 +177,7 @@ export const ActionVariantRule: Story = {
               <Button variant="primary" size="md" startIcon={Trash2} danger>刪除</Button>
             </>
           }
-          onClear={() => {}}
+          onClearSelection={() => {}}
         />
         <Label warn>↑ 兩顆都 primary → 視覺重量過高,跟 page Submit 競爭</Label>
       </Rule>
@@ -211,7 +211,7 @@ export const HintBannerRule: Story = {
             <BulkActionBar
               selection={Array.from({ length: 50 }, (_, i) => `f-${i}`)}
               actions={<Button variant="tertiary" size="md">下載</Button>}
-              onClear={() => {}}
+              onClearSelection={() => {}}
             />
           </div>
         </div>
@@ -222,7 +222,19 @@ export const HintBannerRule: Story = {
         title="❌ 自刻 hint banner / 用 contrast 底色 div"
         note="banner 是 Alert 的職責(自帶 a11y role / aria-live / 視覺一致性)。自刻會破壞跟其他 Alert 的視覺一致性,也漏 a11y"
       >
-        <Label warn>(範例省略)有 Alert 元件不用是浪費</Label>
+        <div className="border border-divider rounded-md overflow-hidden">
+          <div className="bg-info-subtle text-info-text px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] text-footnote">
+            已選取本頁全部 50 個。點此選取全部 5370 個項目
+          </div>
+          <div className="border-t border-divider">
+            <BulkActionBar
+              selection={Array.from({ length: 50 }, (_, i) => `f-${i}`)}
+              actions={<Button variant="tertiary" size="md">下載</Button>}
+              onClearSelection={() => {}}
+            />
+          </div>
+        </div>
+        <Label warn>↑ 手刻 div 當 banner:無 role=&quot;status&quot; / aria-live,SR 不會朗讀狀態變化;底色跟其他 Alert 不一致;「點此選取」是純文字非可操作連結</Label>
       </Rule>
 
       <Rule
@@ -233,7 +245,7 @@ export const HintBannerRule: Story = {
           selection={['a', 'b', 'c']}
           hiddenByFilter={2}
           actions={<Button variant="tertiary" size="md" startIcon={Archive}>封存</Button>}
-          onClear={() => {}}
+          onClearSelection={() => {}}
         />
         <Label>↑ count 文字 inline:「已選 3 項 · 2 個被 filter 隱藏」</Label>
       </Rule>

package/src/components/BulkActionBar/bulk-action-bar.spec.md

@@ -81,9 +81,9 @@ benchmark:
 
 ### Slot
 
-- **`actions`**:consumer 提供 **md** Buttons(size rationale 見「Size canonical」);`variant=tertiary`(主)/ `tertiary danger`(destructive)— **不用 primary**(留 dialog 確認最終 action)
+- **`actions`**:consumer 提供 **md** Buttons(size rationale 見「Size canonical」);**一律 `variant=tertiary`**(含 destructive — `Trash` 等 icon + label 已辨識危險)— **不用 primary、destructive 不上 danger 紅填色**(2026-07-17 user 拍板:批次刪除鈕點下去是**開確認 dialog**非直接刪,紅色強調留給 dialog 內確認最終不可逆 action;對齊 UX Movement / GitLab Pajamas「紅留給不可逆最終確認」+ button.spec.md「Inline destructive 不用高強調」)
 - **count 區**:`已選 {N} 項`(內建)+ inline filter hidden status `· {M} 個被 filter 隱藏`(`hiddenByFilter` prop 傳入時)
-- **clear**:`<Button iconOnly size=md variant=text dismiss />`(內建,觸發 `onClear`)
+- **clear**:`<Button iconOnly size=md variant=text dismiss />`(內建,觸發 `onClearSelection`)
 
 #### Size canonical(2026-05-04 升 SSOT)
 
@@ -143,7 +143,7 @@ interface BulkActionBarProps extends React.HTMLAttributes<HTMLDivElement> {
   /** 已選 ID;length === 0 且無 totalSelected 時自動隱藏(回 null,完整判準見「Extend dataset pattern」) */
   selection: readonly string[]
   /** Clear 觸發,user 點 X icon(consumer 在 page-level 監聽 Esc 觸發) */
-  onClear?: () => void
+  onClearSelection?: () => void
   /** 批次 actions(consumer 提供 md Button,variant=tertiary 或 tertiary+danger,不用 primary) */
   actions?: React.ReactNode
   /** Filter 模式:hidden 數量,顯示在 count 區 inline 「已選 {N} 項 · {M} 個被 filter 隱藏」 */
@@ -169,6 +169,16 @@ interface BulkActionBarLabels {
 
 **Hint banner(擴 dataset 提示)不在本 API**:由 consumer 用 `<Alert variant="info" placement="fixed">` 配 ReactNode title 帶 inline link 自組,黏在 BulkActionBar 上方。Alert / Notice 的 `title` + `description` 已支援 ReactNode(2026-04-28)。
 
+### 批次操作進行中(loading / 防重複提交 / 選取保留)
+
+`actions` 由 consumer 注入 ReactNode,**批次操作的非同步生命週期由 consumer 擁有**(BulkActionBar 是 stateless 呈現層,不介入 action 執行):
+
+- **Loading**:非同步 action(批次刪除 / 匯出)進行中,對應 action Button 傳 `loading`(既有 API,spinner + 自動 disabled)——不在 bar 內另加全域 spinner
+- **防重複提交**:同一批次操作進行中,consumer 對該 action Button 設 `loading` / `disabled` 阻止連點觸發多次(語義同 `../Field/form-validation.spec.md` double-submit 防護,但 owner 在 consumer 而非 bar)
+- **選取保留**:操作進行中 `selection` 維持不變、bar 持續可見;**成功**後才由 consumer 清空 `selection`(觸發 bar 自動隱藏),**失敗**則保留選取讓 user 重試
+
+對齊 Polaris BulkActions(action `loading` 由 consumer 提供)/ Material DataGrid batch action 慣例。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
 ### Extend dataset pattern(totalSelected)
 
 「本頁全選 → hint 點擊 → 擴選整個 dataset」2-step 後,consumer 把 `totalSelected` 設為 dataset 真總數,count 區改顯示該值(否則 fallback `selection.length`)——避免 Alert 顯「已選 5370」但 bar 仍顯「已選 50」的不同步(2026-05-13 ship)。對齊 Gmail / Linear / Notion 全選 dataset hint pattern。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
@@ -183,7 +193,7 @@ interface BulkActionBarLabels {
 - count 文字用 `aria-live="polite"` + `aria-atomic="true"`(selection 變更時 SR 整句重讀「已選 3 項」)
 - Clear button:`aria-label="清除選取"`
 - Hint banner 用 `role="status"` + `aria-live="polite"`(state 切換時通知)
-- 鍵盤:Esc → `onClear()`(consumer 應監聽 page-level keydown 觸發);Tab 序按 DOM 順序 = clear(X)→ actions(count 是純文字 span,非互動元素 → 不參與 Tab)
+- 鍵盤:Esc → `onClearSelection()`(consumer 應監聽 page-level keydown 觸發);Tab 序按 DOM 順序 = clear(X)→ actions(count 是純文字 span,非互動元素 → 不參與 Tab)
 - Disabled action(無權限等)用 Button `disabled` + tooltip 解釋,**不藏 action**(避免 user 困惑)
 
 ---
@@ -194,7 +204,7 @@ interface BulkActionBarLabels {
 - **底色**:**無底色 contrast**,跟 page 同色(`bg-canvas` / `bg-surface` 視 placement 繼承)。對齊 Notion / Linear minimalist — 用文字內容切換呈現「mode」,**不**用底色 highlight。**不像 Polaris 那種顯著底色變化** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **邊界**:**無外框邊界**(融入 page chrome)— 恆 **`border-top` border-divider 切割 layout**(bar 是 page 結構,不是 floating overlay,不用 box-shadow 製造「浮層」誤導)。top-toolbar 變體為未來項(見「Size canonical」)
 - **與 table 的關係**:inline composition — bar 接在 DataTable 下方,toolbar 永遠保留(見「Placement」)
-- **Action variant**:`tertiary`(主)+ `tertiary danger`(destructive)— **不用 primary**(留給 dialog 確認最終 action)
+- **Action variant**:**一律 `tertiary`**(含 destructive,icon+label 辨識危險)— **不用 primary、不用 danger 紅填色**(紅色強調留給 dialog 內確認最終 action,見「Slot」rationale)
 
 ---
 

package/src/components/BulkActionBar/bulk-action-bar.stories.tsx

@@ -21,13 +21,13 @@ export const Default: Story = {
     return (
       <BulkActionBar
         selection={selection}
-        onClear={() => setSelection([])}
+        onClearSelection={() => setSelection([])}
         actions={
           <>
             <Button variant="tertiary" size="md" startIcon={Archive}>封存</Button>
             <Button variant="tertiary" size="md" startIcon={TagIcon}>加標籤</Button>
             <Button variant="tertiary" size="md" startIcon={MoveRight}>移動</Button>
-            <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
+            <Button variant="tertiary" size="md" startIcon={Trash2}>刪除</Button>
           </>
         }
       />
@@ -35,26 +35,10 @@ export const Default: Story = {
   },
 }
 
-// Filter 模式:hidden 數量顯示在 count 區 inline
-export const WithFilterHidden: Story = {
-  name: '部分項目被篩選隱藏',
-  render: () => {
-    const [selection, setSelection] = useState<string[]>(['issue-1', 'issue-2', 'issue-3'])
-    return (
-      <BulkActionBar
-        selection={selection}
-        onClear={() => setSelection([])}
-        hiddenByFilter={2}
-        actions={
-          <>
-            <Button variant="tertiary" size="md" startIcon={Archive}>封存</Button>
-            <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
-          </>
-        }
-      />
-    )
-  },
-}
+// @story-trait-rationale: WithFilterHidden(selection=3 + hiddenByFilter=2)retired 2026-07-17 per audit Dim 24 —
+//   principles.stories.tsx HintBannerRule 第三 Rule 已用同情境(selection 3 + hiddenByFilter=2)且多教「filter hidden
+//   inline 進 count 區、不開 hint banner」規則;展示版無新增約束(earn-existence 2-test 雙 NO)→ retire。
+//   hiddenByFilter inline 呈現 canonical home = principles HintBannerRule。
 
 // Hint banner via Alert primitive(擴 dataset 提示)— 對齊 ref 圖
 // hint banner 唯一 trigger condition:本頁全選 + 還有 dataset 沒選到
@@ -108,11 +92,11 @@ export const WithExtendDatasetHint: Story = {
         <BulkActionBar
           selection={selection}
           totalSelected={allSelected ? TOTAL : undefined}
-          onClear={() => { setSelection([]); setAllSelected(false) }}
+          onClearSelection={() => { setSelection([]); setAllSelected(false) }}
           actions={
             <>
               <Button variant="tertiary" size="md" startIcon={Download}>下載</Button>
-              <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
+              <Button variant="tertiary" size="md" startIcon={Trash2}>刪除</Button>
             </>
           }
         />

package/src/components/BulkActionBar/bulk-action-bar.tsx

@@ -41,7 +41,7 @@ export interface BulkActionBarProps extends React.HTMLAttributes<HTMLDivElement>
   /** 已選 ID,length === 0 時自動隱藏(回傳 null) */
   selection: readonly string[]
   /** Clear 觸發,user 點 X icon 或 Esc(consumer 在 page-level 監聽) */
-  onClear?: () => void
+  onClearSelection?: () => void
   /** 批次 actions(consumer 提供 md Button,variant=tertiary 或 tertiary+danger;不用 primary) */
   actions?: React.ReactNode
   /** Filter 模式:hidden 數量,顯示在 count 區 inline「已選 {N} 項 · {M} 個被 filter 隱藏」 */
@@ -77,7 +77,7 @@ export interface BulkActionBarProps extends React.HTMLAttributes<HTMLDivElement>
 
 const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
   function BulkActionBar(
-    { selection, onClear, actions, hiddenByFilter, totalSelected, labels: labelsOverride, className, ...props },
+    { selection, onClearSelection, actions, hiddenByFilter, totalSelected, labels: labelsOverride, className, ...props },
     ref
   ) {
     const labels: BulkActionBarLabels = React.useMemo(
@@ -109,7 +109,7 @@ const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
         {/* X close — md dismiss(2026-05-04 spec update:default placement = footer variant,
             visual weight 對齊 Dialog footer commitment buttons md;same-row consistency 維持)
             未來若有 top-toolbar variant(覆蓋 sm-density toolbar)→ 該 variant override sm */}
-        {onClear && (
+        {onClearSelection && (
           <Button
             variant="text"
             size="md"
@@ -117,7 +117,7 @@ const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
             dismiss
             startIcon={X}
             aria-label={labels.clear}
-            onClick={onClear}
+            onClick={onClearSelection}
           />
         )}
 

package/src/components/Button/button-group.tsx

@@ -23,14 +23,14 @@ import { ButtonGroupContext } from './button'
  * </ButtonGroup>
  *
  * // 垂直排列（fullWidth 自動套用）
- * <ButtonGroup direction="vertical">
+ * <ButtonGroup orientation="vertical">
  *   <Button variant="primary">確認</Button>
  *   <Button variant="tertiary">取消</Button>
  * </ButtonGroup>
  */
 interface ButtonGroupProps extends React.HTMLAttributes<HTMLDivElement> {
   /** 排列方向，預設 horizontal */
-  direction?: 'horizontal' | 'vertical'
+  orientation?: 'horizontal' | 'vertical'
   /** 水平對齊，預設 start */
   align?: 'start' | 'center' | 'end'
 }
@@ -40,8 +40,8 @@ const BUTTON_GROUP_CTX_VERTICAL = { fullWidth: true } as const
 const BUTTON_GROUP_CTX_HORIZONTAL = { fullWidth: false } as const
 
 const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
-  ({ direction = 'horizontal', align = 'start', className, children, ...props }, ref) => {
-    const isVertical = direction === 'vertical'
+  ({ orientation = 'horizontal', align = 'start', className, children, ...props }, ref) => {
+    const isVertical = orientation === 'vertical'
 
     return (
       <ButtonGroupContext.Provider value={isVertical ? BUTTON_GROUP_CTX_VERTICAL : BUTTON_GROUP_CTX_HORIZONTAL}>

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

@@ -102,6 +102,23 @@ const VARIANT_DESC: Record<VariantKey, string> = {
   link: '外觀像連結的按鈕，不用於操作列',
 }
 
+// variant 名稱只放在左側 mono 標籤欄；按鈕本體用真實動作文案（禁 variant 名當 label）
+const VARIANT_LABEL: Record<VariantKey, string> = {
+  primary: '新增任務',
+  secondary: '儲存變更',
+  tertiary: '取消',
+  text: '略過此步',
+  link: '查看說明',
+}
+
+const DANGER_LABEL: Record<VariantKey, string> = {
+  primary: '刪除專案',
+  secondary: '移除成員',
+  tertiary: '清除紀錄',
+  text: '撤銷授權',
+  link: '刪除',
+}
+
 /* ═══════════════════════════════════════════════════════════════════════════
    Shared UI Components
 
@@ -224,7 +241,8 @@ export const Overview = {
         <div className="flex flex-col gap-2">
           {VARIANTS.map((v) => (
             <div key={v} className="flex items-center gap-4">
-              <div className="w-28 shrink-0"><Button variant={v} size="sm" startIcon={Plus}>{v}</Button></div>
+              <span className="w-16 shrink-0 text-[11px] font-mono text-fg-muted">{v}</span>
+              <div className="w-28 shrink-0"><Button variant={v} size="sm" startIcon={Plus}>{VARIANT_LABEL[v]}</Button></div>
               <span className="text-caption text-fg-secondary">{VARIANT_DESC[v]}</span>
             </div>
           ))}
@@ -232,7 +250,8 @@ export const Overview = {
             <span className="text-[11px] text-fg-muted font-medium">+ danger prop</span>
             {DANGER_VARIANTS.map((v) => (
               <div key={v} className="flex items-center gap-4">
-                <div className="w-28 shrink-0"><Button variant={v} danger size="sm" startIcon={Trash2}>{v}</Button></div>
+                <span className="w-16 shrink-0 text-[11px] font-mono text-fg-muted">{v}</span>
+                <div className="w-28 shrink-0"><Button variant={v} danger size="sm" startIcon={Trash2}>{DANGER_LABEL[v]}</Button></div>
                 <span className="text-caption text-fg-secondary">
                   {v === 'primary' ? '立即不可逆——點下去就執行' : v === 'secondary' ? '有警示意圖，後面還有確認' : '低強調的危險操作'}
                 </span>
@@ -503,7 +522,7 @@ export const ColorMatrix = {
                 <td className="p-3 border-b border-divider font-mono text-caption font-medium align-top">{v}</td>
                 {STATES.map((st) => (
                   <td key={st} className="p-3 border-b border-divider align-top min-w-[160px]">
-                    <Button variant={v} size="sm" startIcon={Plus} disabled={st === 'disabled'}>{v}</Button>
+                    <Button variant={v} size="sm" startIcon={Plus} disabled={st === 'disabled'}>{VARIANT_LABEL[v]}</Button>
                     <TokenAnnotation colors={TOKEN_MAP[v][st]} />
                   </td>
                 ))}
@@ -523,7 +542,7 @@ export const ColorMatrix = {
                   <td className="p-3 border-b border-divider font-mono text-caption font-medium align-top">{v} + danger</td>
                   {STATES.map((st) => (
                     <td key={st} className="p-3 border-b border-divider align-top min-w-[160px]">
-                      <Button variant={v} danger size="sm" startIcon={Trash2} disabled={st === 'disabled'}>{v}</Button>
+                      <Button variant={v} danger size="sm" startIcon={Trash2} disabled={st === 'disabled'}>{DANGER_LABEL[v]}</Button>
                       <TokenAnnotation colors={DANGER_MAP[v]![st]} />
                     </td>
                   ))}
@@ -612,10 +631,10 @@ export const SizeMatrix = {
                 <tr key={v}>
                   <Td mono>{v}</Td>
                   {SIZES.map((sz) => (
-                    <Td key={sz}><Button variant={v} size={sz} startIcon={Plus}>{v}</Button></Td>
+                    <Td key={sz}><Button variant={v} size={sz} startIcon={Plus}>{VARIANT_LABEL[v]}</Button></Td>
                   ))}
                   {SIZES.map((sz) => (
-                    <Td key={`io-${sz}`}><Button variant={v} size={sz} iconOnly startIcon={Plus} aria-label={v} /></Td>
+                    <Td key={`io-${sz}`}><Button variant={v} size={sz} iconOnly startIcon={Plus} aria-label={VARIANT_LABEL[v]} /></Td>
                   ))}
                 </tr>
               ))}
@@ -661,7 +680,7 @@ export const StateBehavior = {
         <div className="flex flex-wrap gap-3">
           {VARIANTS.map((v) => (
             <div key={v} className="flex flex-col items-center gap-1">
-              <Button variant={v} disabled startIcon={Plus}>{v}</Button>
+              <Button variant={v} disabled startIcon={Plus}>{VARIANT_LABEL[v]}</Button>
               <span className="text-[10px] text-fg-muted">{v}</span>
             </div>
           ))}

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

@@ -351,7 +351,7 @@ export const OrderRule: Story = {
         note="使用者眼睛最先掃到最上方，最希望被點擊的動作放第一個。所有按鈕撐滿容器寬度"
       >
         <div className="w-[200px]">
-          <ButtonGroup direction="vertical">
+          <ButtonGroup orientation="vertical">
             <Button variant="primary">確認送出</Button>
             <Button variant="tertiary">取消</Button>
           </ButtonGroup>

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

@@ -273,7 +273,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 是給所有人看的，兩者語意相同，由同一個值驅動。
 
@@ -434,7 +434,7 @@ N/A(action trigger,無資料層)。
 
 ## A11y 預設
 
-**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` 描述用途並自動包 Tooltip。`pressed` 定義時自動寫 `aria-pressed` + `data-state`。
+**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**:鍵盤聚焦時(`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 / 浮層的概念)。
 

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

@@ -24,7 +24,7 @@ const meta: Meta<typeof Button> = {
     },
     danger: {
       control: 'boolean',
-      description: '套用危險色（紅色）。僅 `primary` / `secondary` / `text` 支援（`tertiary` 視覺與 secondary+danger 重複、`link` 語義矛盾，見 spec 禁止事項）。',
+      description: '套用危險色（紅色）。僅 `primary` / `secondary` / `text` 支援（`tertiary` 無 danger compound——會靜默渲染成一般 tertiary、並非等同 secondary+danger；`link` 語義矛盾。見 spec 禁止事項）。',
     },
     size: {
       control: 'select',
@@ -76,11 +76,11 @@ export const Default: Story = {
   name: '預設',
   render: () => (
     <div className="flex flex-wrap items-center gap-3">
-      <Button variant="primary">主要動作</Button>
-      <Button variant="secondary">次要動作</Button>
-      <Button variant="tertiary">第三動作</Button>
-      <Button variant="text">純文字</Button>
-      <Button variant="link">連結樣式</Button>
+      <Button variant="primary">送出申請</Button>
+      <Button variant="secondary">儲存草稿</Button>
+      <Button variant="tertiary">取消</Button>
+      <Button variant="text">重設表單</Button>
+      <Button variant="link">查看填寫說明</Button>
     </div>
   ),
 }
@@ -240,26 +240,20 @@ export const Loading: Story = {
     <div className="flex flex-col gap-6">
       {/* 行為對照 */}
       <div>
-        <p className="mb-2 text-caption text-fg-muted">行為對照：原始 → loading</p>
-        <div className="flex flex-col gap-3">
-          <div className="flex items-center gap-3">
-            <Button variant="primary" startIcon={Download}>匯出</Button>
-            <span className="text-caption text-fg-muted">→</span>
-            <Button variant="primary" startIcon={Download} loading>匯出中</Button>
-            <span className="text-caption text-fg-muted">startIcon 被 spinner 替換，位置不變</span>
-          </div>
-          <div className="flex items-center gap-3">
-            <Button variant="primary">儲存</Button>
-            <span className="text-caption text-fg-muted">→</span>
-            <Button variant="primary" loading>儲存中</Button>
-            <span className="text-caption text-fg-muted">spinner 出現在文字左側，按鈕略寬</span>
-          </div>
-          <div className="flex items-center gap-3">
-            <Button size="sm" iconOnly startIcon={Download} aria-label="下載" />
-            <span className="text-caption text-fg-muted">→</span>
-            <Button size="sm" iconOnly startIcon={Download} loading aria-label="下載中" />
-            <span className="text-caption text-fg-muted">icon-only：spinner 替換 icon</span>
-          </div>
+        <p className="mb-2 text-caption text-fg-muted">行為對照：操作前與載入中</p>
+        <div className="grid grid-cols-[auto_auto_1fr] items-center gap-x-6 gap-y-3">
+          <span className="text-caption text-fg-muted">操作前</span>
+          <span className="text-caption text-fg-muted">載入中</span>
+          <span />
+          <Button variant="primary" startIcon={Download}>匯出</Button>
+          <Button variant="primary" startIcon={Download} loading>匯出中</Button>
+          <span className="text-caption text-fg-muted">startIcon 被 spinner 替換，位置不變</span>
+          <Button variant="primary">儲存</Button>
+          <Button variant="primary" loading>儲存中</Button>
+          <span className="text-caption text-fg-muted">spinner 出現在文字左側，按鈕略寬</span>
+          <Button size="sm" iconOnly startIcon={Download} aria-label="下載" />
+          <Button size="sm" iconOnly startIcon={Download} loading aria-label="下載中" />
+          <span className="text-caption text-fg-muted">icon-only：spinner 替換 icon</span>
         </div>
       </div>
 
@@ -325,8 +319,8 @@ export const HoverFocusState: Story = {
   tags: ['!autodocs'],
   render: () => (
     <div className="flex gap-4">
-      <Button variant="primary" data-testid="hover-target">Hover 我</Button>
-      <Button variant="primary" data-testid="focus-target">Focus 我</Button>
+      <Button variant="primary" data-testid="hover-target">查看帳單</Button>
+      <Button variant="primary" data-testid="focus-target">下載明細</Button>
     </div>
   ),
   play: async ({ canvasElement }) => {