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

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

@@ -1,4 +1,4 @@
-// @benchmark-cited: Polaris / Material / Ant 共識 principles canonical(UsageGuidance integrated)
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — 產品架構參照(Linear / Notion / Figma / GitHub / Slack / Gmail 等)為 usage 觀察,非逐句 URL-cited;視為 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'
 
@@ -62,11 +62,11 @@ export const UsageGuidance: Story = {
       <section>
         <h2 className="text-h4 mb-2">Consumer 紀律</h2>
         <ul className="text-body space-y-1">
-          <li>❌ 禁:`&lt;AppShell&gt;` 內塞另一個 `&lt;AppShell&gt;`(整頁框架單例)</li>
-          <li>❌ 禁:`sidebar={'{'}&lt;div&gt;...&lt;/div&gt;{'}'}` → 應傳 `&lt;Sidebar&gt;` primitive(型別收 ReactNode 不機械強制,2026-06-10 拍板)</li>
-          <li>❌ 禁:`header={'{'}&lt;header&gt;raw&lt;/header&gt;{'}'}` → 應傳 `&lt;ChromeHeader&gt;` 或 header-canonical 派生(同上,不機械強制)</li>
-          <li>❌ 禁:`&lt;AppShell.Main&gt;` 強制 padding(違 layoutSpace 規則 1B)</li>
-          <li>✅ 必:Main 內容遵循既有 `layoutSpace.spec.md` 6 條規則(Page header / Card / DataTable / naked list 各按規則)</li>
+          <li>❌ 禁:`&lt;AppShell&gt;` 內塞另一個 `&lt;AppShell&gt;`(整頁框架只能有一個)</li>
+          <li>❌ 禁:`sidebar` 傳裸 `&lt;div&gt;` → 必傳 `&lt;Sidebar&gt;`,才能維持一致的展開／收合、行動裝置抽屜、鍵盤操作與視覺;傳其他容器雖然型別過得了,卻會失去這些導覽行為</li>
+          <li>❌ 禁:`header` 傳裸 `&lt;header&gt;` → 應傳 `&lt;ChromeHeader&gt;`(或沿用同一套標準標頭結構自訂),才能得到一致的標頭高度、內距與對齊</li>
+          <li>❌ 禁:硬性撐開 Main 區域的內距 → Main 本身不加留白,由內容自己決定(自帶邊框的卡片、資料表各自帶內距)</li>
+          <li>✅ 必:Main 內容的間距沿用既有版面間距原則——頁面標頭、卡片、資料表、純列表各按對應規則處理</li>
         </ul>
       </section>
     </div>
@@ -81,37 +81,37 @@ export const LayoutModeRule: Story = {
   render: () => (
     <div className="prose max-w-2xl space-y-6 px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]">
       <section>
-        <h2 className="text-h4 mb-2">唯一判準:Header scope</h2>
+        <h2 className="text-h4 mb-2">唯一判準:頂部標頭服務的範圍</h2>
         <p className="text-body mb-2">
-          唯一 distinguisher = <strong>Header scope 是 local 還是 global</strong>,
-          <em>不是</em> workspace 多寡(Notion / Gmail 都支援 multi-workspace,卻分屬不同派)。
-          問自己:頂部那條 bar 服務的是「當前這一頁」還是「整個 app」?
+          唯一的區分標準 = <strong>頂部標頭服務的是「目前這一頁」還是「整個產品」</strong>,
+          <em>不是</em>工作區(workspace)的數量多寡(Notion / Gmail 都支援多工作區,卻分屬不同派)。
+          問自己:頂部那條標頭列服務的是當前頁面,還是整個產品?
         </p>
         <ul className="text-body space-y-1">
           <li>
-            <strong>primary-sidebar</strong>:頂部是 <strong>local toolbar</strong> —
-            服務當前頁(breadcrumb / page-level actions / filter)。Sidebar 頂天立地,WorkspaceBrand 在 sidebar 頂。
+            <strong>primary-sidebar</strong>:頂部是<strong>服務當前頁的工具列</strong> —
+            放麵包屑、頁面層級操作、篩選。Sidebar 頂天立地,工作區品牌(`WorkspaceBrand`)放在 sidebar 頂。
             參考 Linear / Notion / Figma。
           </li>
           <li>
-            <strong>primary-header</strong>:多一條 <strong>global bar</strong> 橫跨頂部 —
-            服務整個 app(account / workspace switcher / 跨頁 search / notifications);local toolbar
-            <em>仍在</em> main col 頂,只是上面多了 global header。WorkspaceBrand 改放 globalHeader 左側。
+            <strong>primary-header</strong>:多一條<strong>橫跨頂部、服務整個產品的全域標頭</strong> —
+            放帳號、工作區切換、跨頁搜尋、通知;服務當前頁的工具列
+            <em>仍在</em>主欄頂部,只是上面多了這條全域標頭。工作區品牌改放全域標頭(`globalHeader`)左側。
             參考 GitHub / Slack / Gmail。完整組合見{' '}
             <LinkTo kind="Design System/Components/AppShell/展示" name="主標頭佈局 — 全域+本地兩層(GitHub/Gmail/Slack 派)"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">展示 → 主標頭佈局 — 全域+本地兩層</span></LinkTo>
           </li>
         </ul>
         <p className="text-caption text-fg-secondary mt-2">
-          兩 mode 是 product 角色表態——啟動時固定,不該在 runtime 切換。視覺對照圖見{' '}
+          兩種模式是產品的角色定位——啟動時就固定,不該在執行期切換。視覺對照圖見{' '}
           <LinkTo kind="Design System/Components/AppShell/設計規格" name="兩種布局模式對照圖"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">設計規格 → 兩種布局模式對照圖</span></LinkTo>
         </p>
       </section>
 
       <section>
-        <h2 className="text-h4 mb-2">常見誤解:global header 取代 local toolbar</h2>
+        <h2 className="text-h4 mb-2">常見誤解:全域標頭會取代當前頁工具列</h2>
         <p className="text-body">
-          錯。primary-header = primary-sidebar 的所有東西 + <strong>額外一條</strong> global header 在頂;
-          `header` slot(local toolbar)<strong>仍然存在</strong>。GitHub / Slack / Gmail 全部同時保有兩層,
+          錯。primary-header = primary-sidebar 的所有東西 + <strong>額外一條</strong>全域標頭在頂;
+          當前頁工具列(`header` slot)<strong>仍然存在</strong>。GitHub / Slack / Gmail 全部同時保有兩層,
           不是二選一。
         </p>
       </section>
@@ -129,9 +129,9 @@ export const LayoutModeRule: Story = {
         <h2 className="text-h4 mb-2">帳號入口(個人設定)跟著 mode 走(只能出現一次)</h2>
         <ul className="text-body space-y-1">
           <li>• <strong>primary-sidebar</strong>:帳號 / 個人設定放 Sidebar 底部(`&lt;SidebarFooter&gt;`)— Linear / Notion / Figma</li>
-          <li>• <strong>primary-header</strong>:帳號入口改放 globalHeader 右側 avatar(品牌左、帳號右,左右對稱),sidebar 不放 user footer — GitHub / Gmail / Slack 帳號一律在 global bar 右上</li>
+          <li>• <strong>primary-header</strong>:帳號入口改放 globalHeader 右側 avatar(品牌左、帳號右,左右對稱),sidebar 不放帳號頁尾 — GitHub / Gmail / Slack 帳號一律在全域標頭右上</li>
           <li>• 開「個人資料 / 設定 / 登出」帳號選單(`&lt;DropdownMenu&gt;`),<strong>不用 ProfileCard</strong>(ProfileCard 是看別人的人員卡,預設動作 Chat/通話用在自己身上不對)</li>
-          <li>• 帳號 avatar = 24px,跟左側品牌 avatar 同尺寸(header-canonical 4.5 chrome header avatar);右側邊距與品牌距分割線對稱</li>
+          <li>• 帳號 avatar = 24px,跟左側品牌 avatar 同尺寸(沿用標準標頭的頭像尺寸規範);右側邊距與品牌距分割線對稱</li>
           <li>❌ 禁:`primary-header` mode 同時在 globalHeader + sidebar footer 各放一份 = 入口混淆(帳號入口視覺 SSOT,只能出現一次)</li>
         </ul>
       </section>

package/src/components/AppShell/app-shell.spec.md

@@ -67,6 +67,10 @@ benchmark:
 
 Sub-component:`<AppShellAside title={...} width={400}>`(width consumer 自決 — `number` 或 `{ md, xl }` breakpoint-keyed,clamp `min-width: 240` / `max-width: 640`;**title prop required**,modal mode 走 Sheet → `aria-labelledby` 強制,per `sheet.spec.md`「禁止事項」(無 title → aria-labelledby 強制))。
 
+**Aside body padding(內容自帶,刻意 Pattern B)**:`<AppShellAside>` 的 body(ScrollArea 內)**不自帶 px/py**,由 consumer 塞入的 children 自行負責留白(對齊 `layoutSpace.spec.md` 規則 1B「父層/內容管 padding」的裸結構路線,同 Table / DataTable)。**理由**:aside 內容異質(清單需 hover 貼邊滿版、表格需 flush、表單才需 padding),框架統一加 padding 反而破壞清單/表格。與 Dialog / Sheet body 自帶 `px-loose py-tight` 的差異是**刻意**的(那兩者內容較單一)。consumer 放需留白的內容時,自帶 `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`(範例 `app-shell.stories.tsx` 即如此)。
+
+**Aside 開關控制(刻意單向,2026-07-17 user 拍板)**:`asideOpen` / `onAsideOpenChange` 提供完整 **controlled** 路徑;uncontrolled fallback 初值**刻意固定關閉**(`useState(false)`),**不提供 `defaultAsideOpen`**。理由:側邊詳情面板實務上幾乎一定由 app 的 route / 選取狀態驅動(modal mode 更明文要求 controlled),初值固定關閉是合理預設,額外加 `defaultAsideOpen` 偏 YAGNI。對齊 Dim 26 dual-mode canonical 的「刻意單一模式 → 補 rationale」例外機制。未來真有 uncontrolled 初值需求再加(additive,不破壞)。
+
 ### Hook export:`useAppShell()`(2026-05-21 D2 codify per Phase B codex catch)
 
 Public compound API hook,讓 consumer 自拼 custom aside / 自管 modal layout(對齊 Radix `useDialogContext` / MUI `useFormControl` / Mantine `useAppShellContext` 慣例)。

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>
           ))}