@qijenchen/design-system 0.1.0-beta.61 → 0.1.0-beta.63

package/llms-full.txt

@@ -1,6 +1,6 @@
 # @qijenchen/design-system — 完整設計參考(llms-full)
 
-> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.61。
+> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.63。
 
 # Components
 
@@ -36,7 +36,7 @@ Source(AI 讀此看官方範例): src/components/AspectRatio/
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/Avatar/
 
-## Badge(family 3)
+## Badge(family self-contained)
 
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/Badge/
@@ -180,6 +180,10 @@ Source(AI 讀此看官方範例): src/components/FileItem/
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/FileUpload/
 
+### Variants
+- **dropzone**: 預設 — 大型 dashed 拖放區;「拖放有價值」+ 主要上傳區(drag + click)
+- **button**: form 內單欄 / 空間省 / 與其他 field 並列 — 緊湊 Button 觸發(click-only)
+
 ## FileViewer(family composite)
 
 Storybook: https://ajenchen-design-system.netlify.app
@@ -280,7 +284,7 @@ Source(AI 讀此看官方範例): src/components/Sidebar/
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/Skeleton/
 
-## Slider(family 4)
+## Slider(family self-contained)
 
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/Slider/
@@ -316,9 +320,9 @@ Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/Tabs/
 
 ### Sizes
-- **sm**: ★ cva default — 所有 header 內 tabs(overlay / chrome header / Dialog / Sidebar / dense toolbar);tab-height 32/40
+- **sm**: ★ cva default — 所有 header 內 tabs(overlay / chrome header / Dialog / Sidebar / dense toolbar)
 - **md**: future tier — 目前無 recommended use case,新 consumer 須先諮詢 DS owner
-- **lg**: 獨立 tabs 直接取代 chrome header — page-level workspace 主導覽(tab-height 48/56 = chrome-header-height)
+- **lg**: 獨立 tabs 直接取代 chrome header — page-level workspace 主導覽(tab 高度 = chrome-header-height)
 
 ## Tag(family 3)
 

package/llms.txt

@@ -1,7 +1,7 @@
 # @qijenchen/design-system
 
 > World-class React design system(Radix/shadcn + Tailwind v4 + 自訂 design token)。
-> 54 components + 4 public patterns + design tokens。v0.1.0-beta.61。
+> 54 components + 4 public patterns + design tokens。v0.1.0-beta.63。
 
 本檔由 source(spec.md frontmatter + Storybook index)build-time 自動生成,**禁手改**(CI --check drift gate 守)。
 每元件 / pattern 的完整 variants / sizes / 禁止事項 全文見 [llms-full.txt](./llms-full.txt)。
@@ -35,7 +35,7 @@
 - [FieldControlGroup](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/FieldControlGroup
 - [FieldControls](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Field
 - [FileItem](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/FileItem
-- [FileUpload](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/FileUpload
+- [FileUpload](https://ajenchen-design-system.netlify.app): variants:dropzone/button — src:components/FileUpload
 - [FileViewer](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/FileViewer
 - [Input](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Input
 - [LinkInput](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/LinkInput

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qijenchen/design-system",
-  "version": "0.1.0-beta.61",
+  "version": "0.1.0-beta.63",
   "private": false,
   "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
   "type": "module",

package/src/components/Accordion/accordion.principles.stories.tsx

@@ -69,7 +69,7 @@ export const UsageGuidance: Story = {
       >
         <ul className="space-y-1">
           <li>
-            <LinkTo kind="Design System/Components/Accordion/展示" name="FAQ"><span className="text-primary hover:underline font-medium cursor-pointer">FAQ</span></LinkTo>
+            <LinkTo kind="Design System/Components/Accordion/展示" name="FAQ 常見問題"><span className="text-primary hover:underline font-medium cursor-pointer">FAQ 常見問題</span></LinkTo>
           </li>
           <li>
             <LinkTo kind="Design System/Components/Accordion/展示" name="設定分組"><span className="text-primary hover:underline font-medium cursor-pointer">設定分組</span></LinkTo>

package/src/components/Accordion/accordion.spec.md

@@ -19,7 +19,7 @@ benchmark:
 
 Accordion 是**垂直堆疊、可收合的多區塊容器**——每個 item 由 header（含 chevron）點擊切換展開 / 收合狀態。適合「多段內容,多數時間只想看其中一段」的情境。
 
-**實作基礎**：shadcn/ui 結構 + Radix Accordion primitive。本 DS 保留 shadcn 的 `Accordion / AccordionItem / AccordionTrigger / AccordionContent` API,視覺全改本 DS token,移除 shadcn 預設的 hover underline(web 早期 link style,與現代 SaaS 質感不符)。
+**實作基礎**：shadcn/ui 結構 + Radix Accordion primitive。本 DS 保留 shadcn 的 `Accordion / AccordionItem / AccordionTrigger / AccordionContent` API,視覺全改本 DS token(與 shadcn 預設的差異見「視覺規則」)。
 
 **Layout Family**：非上述 family — composite / multi-section（多個 AccordionItem 垂直堆疊，自 own layout）。
 
@@ -30,7 +30,8 @@ Accordion 是**垂直堆疊、可收合的多區塊容器**——每個 item 由
 - **FAQ / 說明**：常見問題、使用教學（預設全收合，使用者展開有興趣的）
 - **設定分組**：一般 / 通知 / 安全 / 付款等多節 settings 頁（長 form 拆段）
 - **進階選項可隱藏**：預設展示主要欄位，「進階選項」收合起來避免壓力
-- **單邊 sidebar 多分類**：檔案樹、notion-style 工作區 sidebar
+- **單邊 sidebar 多分類(淺層分組)**:notion-style 工作區 sidebar 的 section 收合;檔案樹 / 深度 tree 改用 `TreeView`(見「何時不用」)
+- **多段獨立收合（非互斥切換）**：各段內容垂直堆疊、可各自展開收合——若是「同一塊空間互斥切換視圖」改用 Tabs（見「何時不用」）
 
 ## 何時不用
 
@@ -72,7 +73,10 @@ Accordion 是**垂直堆疊、可收合的多區塊容器**——每個 item 由
 - **Content 文字**:次要閱讀色—— 主資訊在 trigger,展開內容是補充
 - **焦點環**:鍵盤 focus 用 ring token(非自訂 outline)
 
-**為什麼 hover 不用底線**:shadcn 預設 `hover:underline` 是 web 早期 link convention,現代 SaaS(Notion / Linear / Stripe / Vercel)皆不使用。改用文字色 tint 弱化維持統一質感,同時保留可點擊提示——不變色會讓使用者不確定是否能點擊,比起「被誤以為是 link」的風險,「失去可點擊提示」的風險更高。
+**為什麼 hover 不用底線**:
+- shadcn 預設 `hover:underline` 是 web 早期 link convention,現代 SaaS(Notion / Linear / Stripe / Vercel)皆不使用
+- 改用文字色 tint 弱化,維持 DS 統一質感
+- 仍保留可點擊提示——完全不變色會讓使用者不確定能否點擊;「失去可點擊提示」的風險大於「被誤以為是 link」
 
 完整 class / token 對照見 anatomy story(`ColorMatrix` + `SizeMatrix`)。
 
@@ -84,7 +88,7 @@ Accordion 是**垂直堆疊、可收合的多區塊容器**——每個 item 由
 - ❌ **不寫「全部展開 / 全部收合」按鈕**（違反 accordion 節省空間的設計意圖;若需要此功能,改用 TreeView 或 DescriptionList）
 - ❌ **單一 item 不用 Accordion**（用 `<details>` 或自組 toggle;見「何時不用」）
 - ❌ **不用 Accordion 做主要導航**（主導航用 Tabs / Sidebar,Accordion 是 content-level 收合）
-- ❌ **AccordionContent 不放互動重焦點元素**（例:complex form / Dialog trigger;收合後焦點消失,但如果只是輸入欄位可以）
+- ❌ **AccordionContent 不放重焦點互動元素**（例:complex form / Dialog trigger）——a11y 硬限制:item 被收合時(尤其 `single` 模式展開他段會自動收合本段)內部焦點隨 content 隱藏而消失,鍵盤使用者失去落點。少量輸入欄位可以(UX 建議層級:使用者通常完成填寫才切換)
 
 ---
 
@@ -99,9 +103,16 @@ Consumer 無需額外處理,保留 Radix `data-state` 屬性即可。
 
 ---
 
+## 常見誤解
+
+**誤解**:「Accordion 該提供全部展開 / 全部收合按鈕」。
+**事實**:期待「全展開一次讀完 / 全收合做導航」代表內容是參照型結構——那是 TreeView / DescriptionList 的場景。Accordion 的設計意圖是節省空間、一次聚焦一段(見「禁止事項」)。
+
+---
+
 ## 邊界狀態
 
-Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consumer 用 `<Skeleton />` 包;disabled state 詳 `../Field/field-controls.spec.md`;本元件無 density 概念,padding 固定為 `py-4 / pb-4`(不隨 density token 變動)。
+Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consumer 用 `<Skeleton />` 包;disabled state 詳 `../Field/field-controls.spec.md`;本元件無 density 概念,padding 固定為 `py-4 / pb-4`(不隨 density token 變動);item 數量無內建上限與虛擬捲動(全數 render),極長清單的收納(拆頁 / 搜尋)由 consumer 內容層處理。
 
 ---
 
@@ -112,3 +123,9 @@ Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consum
 - `../Sheet/sheet.spec.md` — 側邊抽屜
 - `../TreeView/tree-view.spec.md` — 具層級結構的收合（Accordion 的巢狀延伸）
 - Radix Accordion primitive — `@radix-ui/react-accordion`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `tabs.spec.md`

package/src/components/Accordion/accordion.tsx

@@ -96,7 +96,7 @@ export const accordionMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: [],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],

package/src/components/Alert/alert.anatomy.stories.tsx

@@ -1,7 +1,7 @@
 // @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
 // @anatomy-rationale:
 //   SizeMatrix N/A — Alert 固定 md tier(由消費的 Notice primitive 決定),
-//     不隨 density 縮放。Placement(inline / fixed)取代 size 作為佈局決策,
+//     不隨 density 縮放(僅 placement="fixed" 的水平 px 走 --layout-space-loose,density-aware)。Placement(inline / fixed)取代 size 作為佈局決策,
 //     已由 PlacementMatrix 涵蓋。
 import type { Meta, StoryObj } from '@storybook/react'
 import { Alert, type AlertProps } from './alert'
@@ -127,7 +127,7 @@ export const ColorMatrix: Story = {
           <table className="text-caption border-collapse">
             <thead><tr><Th>Variant</Th><Th>Subtle</Th><Th>Solid</Th></tr></thead>
             <tbody>
-              <tr><Td mono>neutral</Td><Td mono>bg-muted + border-border + text-fg-muted icon</Td><Td>bg-surface-raised + data-theme inverse(跟頁面反)</Td></tr>
+              <tr><Td mono>neutral</Td><Td mono>bg-muted + border-border;無 status icon(VARIANT_ICON.neutral = null)</Td><Td>bg-surface-raised + data-theme inverse(跟頁面反)</Td></tr>
               <tr><Td mono>info</Td><Td mono>bg-info-subtle + border-info-hover + text-info-text</Td><Td mono>bg-info + data-theme="dark"(藍底白字)</Td></tr>
               <tr><Td mono>success</Td><Td mono>bg-success-subtle + border-success-hover + text-success-text</Td><Td mono>bg-success + data-theme="dark"(綠底白字)</Td></tr>
               <tr><Td mono>warning</Td><Td mono>bg-warning-subtle + border-warning-hover + text-warning-text</Td><Td mono>bg-warning + data-theme="light"(黃底深字)</Td></tr>
@@ -200,7 +200,7 @@ export const StateBehavior: Story = {
       <div>
         <H3>Close button 互動狀態</H3>
         <Desc>
-          Chrome corner close 用 **Button iconOnly `dismiss` size="xs"**(notification banner family 設計準則,見 `overlay-surface.spec.md`「Chrome dismiss size canonical」)。現行 canonical 為兩分:notification banner family(Notice / Alert / Toast,px-4 py-3 固定)dismiss 用 `xs`;overlay surface(Dialog / Sheet / Popover)另走 `sm` + unbounded 負 margin trick。corner 屬 action group region,實務上可與 refresh / share 等 Button 並排(用 Separator 分群),必須統一 Button primitive + 同 family 全 xs。`dismiss` prop 自動套 `variant="text"` + icon `fg-muted` 弱化,hover 時恢復 foreground。
+          Chrome corner close 用 **Button iconOnly `dismiss` size="xs"**(notification banner family 設計準則,見 `overlay-surface.spec.md`「Chrome dismiss size canonical」)。現行 canonical 為兩分:notification banner family(Notice / Alert / Toast,px-4 py-3 固定)dismiss 用 `xs`;overlay surface(Dialog / Sheet / Popover)另走 `sm` + unbounded 負 margin trick。corner 屬 action group region,實務上可與 refresh / share 等 Button 並排(用 ButtonDivider 分群),必須統一 Button primitive + 同 family 全 xs。`dismiss` prop 自動套 `variant="text"` + icon `fg-muted` 弱化,hover 時恢復 foreground。
         </Desc>
         <div className="overflow-x-auto">
           <table className="text-caption border-collapse">
@@ -209,7 +209,7 @@ export const StateBehavior: Story = {
               <tr><Td>default</Td><Td>Button xs iconOnly(24×24),X icon 16,fg-muted</Td><Td mono>text-fg-muted(`dismiss` override)</Td></tr>
               <tr><Td>hover</Td><Td>Button bg 套 neutral-hover,icon 升 foreground</Td><Td mono>bg-neutral-hover / text-foreground</Td></tr>
               <tr><Td>focus</Td><Td>2px ring(鍵盤導航)</Td><Td mono>ring-ring ring-offset-1</Td></tr>
-              <tr><Td>solid appearance</Td><Td>icon 隨 variant 的 data-theme:info / success / error(dark theme)白字,warning(light theme)深字</Td><Td mono>text-foreground(隨 data-theme 翻轉)</Td></tr>
+              <tr><Td>solid appearance</Td><Td>icon 隨 variant 的 data-theme:info / success / error(dark theme)白字,warning(light theme)深字</Td><Td mono>text-fg-muted → hover text-foreground(隨 data-theme 翻轉)</Td></tr>
             </tbody>
           </table>
         </div>

package/src/components/Alert/alert.principles.stories.tsx

@@ -41,19 +41,19 @@ export const UsageGuidance: Story = {
       <p>適合 Alert 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/Alert/展示" name="低調 單行"><span className="text-primary hover:underline font-medium cursor-pointer">Subtle 單行</span></LinkTo>
+          <LinkTo kind="Design System/Components/Alert/展示" name="低調單行"><span className="text-primary hover:underline font-medium cursor-pointer">低調單行</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Alert/展示" name="實心 單行"><span className="text-primary hover:underline font-medium cursor-pointer">Solid 單行</span></LinkTo>
+          <LinkTo kind="Design System/Components/Alert/展示" name="實心單行"><span className="text-primary hover:underline font-medium cursor-pointer">實心單行</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Alert/展示" name="低調 + 說明文字"><span className="text-primary hover:underline font-medium cursor-pointer">低調 + 說明文字</span></LinkTo>
+          <LinkTo kind="Design System/Components/Alert/展示" name="低調含說明文字"><span className="text-primary hover:underline font-medium cursor-pointer">低調含說明文字</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Alert/展示" name="實心 + 說明文字"><span className="text-primary hover:underline font-medium cursor-pointer">實心 + 說明文字</span></LinkTo>
+          <LinkTo kind="Design System/Components/Alert/展示" name="實心含說明文字"><span className="text-primary hover:underline font-medium cursor-pointer">實心含說明文字</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Alert/展示" name="框架角落操作群組"><span className="text-primary hover:underline font-medium cursor-pointer">框架角落操作群組</span></LinkTo>
+          <LinkTo kind="Design System/Components/Alert/展示" name="右上角操作群組"><span className="text-primary hover:underline font-medium cursor-pointer">右上角操作群組</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>

package/src/components/Alert/alert.spec.md

@@ -38,7 +38,7 @@ Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、
 
 **實作基礎**：消費 Notice primitive（共享 Toast 的 layout + icon + theme 策略）。
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。Alert 透過 Notice 繼承 Family 2 結構。
+**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）**——由 Notice primitive own（Notice 消費 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」reading-mode 規格），Alert 透過 Notice 間接繼承,不直接消費 item-anatomy。
 
 ---
 
@@ -73,6 +73,8 @@ Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、
 - 是（方案到期、帳戶未驗證、系統維護中、錯誤需要處理）→ **Alert**
 - 否（儲存成功、已複製、上傳完成）→ **Toast**
 
+頂部全域警告同理走 Alert（`placement="fixed"`）：fixed 是**頁面流內**的持久 bar（非 position fixed 浮層），與 Toast 浮層分屬不同層，不互相取代、不衝突。
+
 ---
 
 ## 禁止事項
@@ -81,15 +83,14 @@ Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、
 - ❌ **不把 error form validation 做成 Alert**：欄位級錯誤必須貼近發生位置（FieldError）,使用者才能快速定位；頁面級 Alert 只放非欄位的整體錯誤（如提交失敗、權限不足）
 - ❌ **Alert 不疊 Alert**：同區出現多個 Alert 視覺雜訊重,整理成一組 messages 或合併為單一 Alert with list
 - ❌ **destructive 操作確認不用 Alert**：刪除 / 離開等需要明確確認的動作用 Dialog,Alert 無法承載 confirm / cancel 雙按鈕的阻斷流程
-- ❌ **body action row 不得混入 close X**:close X 必在 chrome corner action group,不可跟 CTA 擺在同一 row(違反 same-row consistency — CTA 是 labeled Button xs tertiary,close X 是 Button iconOnly xs dismiss,box size 與視覺分量不同,同 row 會造成 gap / 對齊錯亂)。完整規則見 `patterns/element-anatomy/inline-action.spec.md`「Same-row consistency rule(防混用)」節
-- ❌ **close X 不用 Inline Action 或自刻 `<button><X /></button>`**:corner 屬 action group region,必用 `<Button iconOnly dismiss size="xs" />`(見上方 Chrome corner close X canonical)
+- ❌ **兩個 action 區域不混用**:chrome corner 只放 close X(必用 `<Button iconOnly dismiss size="xs" />`,不是 Inline Action、不是自刻 `<button><X /></button>`,見下方 Chrome corner close X canonical);body action row 只放 CTA(Button xs tertiary)。close X 混入 body action row 違反 same-row consistency(box size 與視覺分量不同,造成 gap / 對齊錯亂),完整規則見 `patterns/element-anatomy/inline-action.spec.md`「Same-row consistency rule(防混用)」節
 
 ---
 
 ## A11y 預設
 
 - **一般提示（neutral / info / success）**：`role="status"` + `aria-live="polite"`——screen reader 在空閒時讀出 Alert 內容，不中斷使用者目前動作
-- **緊急提示（warning / error）**：`role="alert"` + `aria-live="assertive"`——立即中斷 screen reader 目前朗讀讀出內容（依 variant 自動套用，無需手動設定）
+- **緊急提示（warning / error）**：`role="alert"` + `aria-live="assertive"`——立即中斷 screen reader 目前朗讀讀出內容。「緊急與否」的界線即 variant 選擇本身：選 warning / error 即 assertive,依 variant 自動套用，無 per-instance 切換 API
 - **Close X 按鈕**：必須有 `aria-label`(如「關閉通知」),實作見下方「Chrome corner close X canonical」
 - **CTA 按鈕**：放在 Alert body action row 時 size 固定為 `xs` tertiary,文字描述動作(「前往設定」「立即更新」)
 
@@ -100,7 +101,7 @@ Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、
 Alert 右上角的 close X **必須用 `<Button iconOnly dismiss size="xs" />`**,不是 Inline Action、不是自刻 button。
 
 **為什麼是 Button(Cat 3 Action group region)而非 Inline Action**:
-- Alert 的 chrome corner 屬 **action group region**(toolbar / chrome corner / standalone 類),實務上 close 左側可並排 refresh / share / minimize 等額外 action + `<Separator orientation="vertical" />`——一旦成為 action group,所有成員必同類(same-row consistency),統一 Button iconOnly
+- Alert 的 chrome corner 屬 **action group region**(toolbar / chrome corner / standalone 類),實務上 close 左側可並排 refresh / share / minimize 等額外 action + `<ButtonDivider />`——一旦成為 action group,所有成員必同類(same-row consistency),統一 Button iconOnly
 - Inline Action 是「embedded 在 host 內部的 tap target」(Cat 1,如 Input clear X / Tag dismiss X),不參與 action group 規則,兩者不可混用
 - `dismiss` prop 自動套 `variant="text"` + `fg-muted → hover foreground` 弱化,視覺輕量不壓過內容
 
@@ -114,7 +115,7 @@ Alert chrome corner 可承載多個 action(close 左側並排):
 
 ```
 ┌─ Alert ────────────────── [⟲] │ [X] ┐   ← chrome corner action group(Button xs)
-│ [icon] Title                         │     refresh / share / minimize 等 + Separator + close X
+│ [icon] Title                         │     refresh / share / minimize 等 + ButtonDivider + close X
 │ Description                          │
 │                      [CTA1] [CTA2]   │   ← body action row(Button xs tertiary)
 └──────────────────────────────────────┘
@@ -122,14 +123,14 @@ Alert chrome corner 可承載多個 action(close 左側並排):
 
 **規則**:
 - 同一 action group 所有 Button 同 `size="xs"`(跟 close X 對齊)
-- 多 action 之間用 `<Separator orientation="vertical" />` 分群(`refresh / share` 一群,`close` 一群)
-- 若只有 close X 則不需要 Separator(單一 action 即 group)
+- 多 action 之間用 `<ButtonDivider />` 分群(`refresh / share` 一群,`close` 一群)——Button 家族 action group 專用 divider(`button-group.tsx`,`role="separator"` 自帶 mx-1),canonical story 同此
+- 若只有 close X 則不需要 ButtonDivider(單一 action 即 group)
 
 **世界級對照**:
 - **Material Banner**(`<Banner actions={[...]}/>` 右上 close + 可加 refresh)
 - **Polaris Banner**(`onDismiss` 走 IconButton,右上 action group)
 - **VS Code editor tab** window corner(close + pin + split,全部同 size IconButton)
-- **Figma panel corner**(close + collapse 同 group,Separator 分隔)
+- **Figma panel corner**(close + collapse 同 group,divider 分隔)
 
 ### Multi corner action 場景
 
@@ -161,7 +162,7 @@ Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix`
 ## 為何無 Inspector / SizeMatrix
 
 - **無 Inspector**:Alert 的關鍵決策維度是 `variant`(5 色)× `appearance`(subtle / solid)× `placement`(inline / fixed),已在 `ColorMatrix` 完整呈現 variant × appearance 矩陣,再加 `PlacementMatrix` 呈現 placement——互動切換式 Inspector 不會比這兩張矩陣更能傳達 Alert 的設計規格。
-- **無 SizeMatrix**:Alert 無 `size` prop,其視覺尺寸繼承自 Notice primitive(14px body / 16px icon / fixed padding),不隨 density 變動。尺寸規格由 `Notice` spec own。改 Notice 時 Alert 自動跟進,不需要 Alert 有獨立 SizeMatrix。
+- **無 SizeMatrix**:Alert 無 `size` prop,其視覺尺寸繼承自 Notice primitive(14px body / 16px icon / 固定 py),字級與垂直 padding 不隨 density 變動;僅 `placement="fixed"` 的水平 px 走 `--layout-space-loose`(density-aware,跟周圍 loose-padding 佈局對齊,見 alert.tsx)。尺寸規格由 `Notice` spec own。改 Notice 時 Alert 自動跟進,不需要 Alert 有獨立 SizeMatrix。
 
 對應 anatomy story:保留 `Overview` + `ColorMatrix` + `StateBehavior` + 元件特有 `PlacementMatrix`。
 
@@ -179,9 +180,10 @@ Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix`
 
 ## 邊界案例
 
-- **Disabled(dismiss button)**:Alert **不提供 dismiss 停用 API**——banner dismiss 恆可用(對齊 Polaris / Material Banner:通知關閉鈕應永遠可按)。Alert 本身亦無 `disabled` prop(持久通知不該被禁用)。若需防止 close action(API in-flight)被雙擊,consumer 在 `onDismiss` 內自行 debounce / 加上層鎖,不在 UI 層加 disable(`<Button dismiss>` 不暴露 disabled 透傳)。
+- **Disabled(dismiss button)**:Alert **不提供 dismiss 停用 API**——banner dismiss 恆可用(對齊 Polaris / Material Banner:通知關閉鈕應永遠可按)。Alert 本身亦無 `disabled` prop(持久通知不該被禁用)。若需防止 close action(API in-flight)被雙擊,consumer 在 `onDismiss` 內自行 debounce / 加上層鎖,不在 UI 層加 disable(Alert 不提供 dismiss 停用 API、也不把 disabled 轉傳給內部 dismiss Button;Button primitive 本身支援 disabled,但 Alert 刻意不開洞)。
 - **Loading**:Alert 本身不需 loading state(非 async surface);若 Alert body action row 內 CTA 在 async 動作中,該 Button 自己處理 `loading` prop。
 - **Empty / icon-only**:Alert 必有 `title`(API contract),無 empty 場景;若無 description 則僅顯示 title + icon,layout 自動收斂。
+- **極長字串**:title 單行 truncate、description 自由換行不截斷(皆繼承 ItemContent 預設);description 超過 2–3 行屬誤用,改 Dialog(見禁止事項)。
 
 ## 相關
 
@@ -193,5 +195,8 @@ Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix`
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `dialog.spec.md`
 - `empty.spec.md`
+- `notice.spec.md`
 - `skeleton.spec.md`
+- `toast.spec.md`

package/src/components/Alert/alert.stories.tsx

@@ -35,7 +35,7 @@ const D: Record<string, string> = {
 const actionBtn = <Button variant="tertiary" size="xs">查看詳情</Button>
 
 export const SubtleSingleLine = {
-  name: '低調 單行',
+  name: '低調單行',
   render: () => (
     <div className="flex flex-col gap-3 max-w-lg">
       {ALL.map((v) => <Alert key={v} variant={v} appearance="subtle" title={L[v]} endContent={actionBtn} />)}
@@ -44,7 +44,7 @@ export const SubtleSingleLine = {
 }
 
 export const SolidSingleLine = {
-  name: '實心 單行',
+  name: '實心單行',
   render: () => (
     <div className="flex flex-col gap-3 max-w-lg">
       {ALL.map((v) => <Alert key={v} variant={v} appearance="solid" title={L[v]} endContent={actionBtn} />)}
@@ -53,7 +53,7 @@ export const SolidSingleLine = {
 }
 
 export const SubtleWithDescription = {
-  name: '低調 + 說明文字',
+  name: '低調含說明文字',
   render: () => (
     <div className="flex flex-col gap-3 max-w-lg">
       {ALL.map((v) => <Alert key={v} variant={v} appearance="subtle" title={L[v]} description={D[v]} endContent={actionBtn} />)}
@@ -62,7 +62,7 @@ export const SubtleWithDescription = {
 }
 
 export const SolidWithDescription = {
-  name: '實心 + 說明文字',
+  name: '實心含說明文字',
   render: () => (
     <div className="flex flex-col gap-3 max-w-lg">
       {ALL.map((v) => <Alert key={v} variant={v} appearance="solid" title={L[v]} description={D[v]} endContent={actionBtn} />)}
@@ -71,7 +71,7 @@ export const SolidWithDescription = {
 }
 
 export const CornerActionGroup = {
-  name: '框架角落操作群組',
+  name: '右上角操作群組',
   render: () => (
     <div className="flex flex-col gap-4 max-w-lg">
       <span className="text-caption text-fg-muted">

package/src/components/Alert/alert.tsx

@@ -167,7 +167,7 @@ Alert.displayName = 'Alert'
 // Sizes = none(Alert 視覺尺寸繼承 Notice primitive,不隨 size 變;見 spec「為何無 SizeMatrix」)
 export const alertMeta = {
   component: 'Alert',
-  family: null, // non-family composite / overlay / layout
+  family: 2, // List item(對齊 alert.spec.md frontmatter family: 2)
   variants: {
     neutral: { purpose: '中性提示(系統公告、非緊急說明);無情緒色' },
     info: { purpose: '資訊性提示(版本更新、流程說明);藍色 hue' },
@@ -176,7 +176,7 @@ export const alertMeta = {
     error: { purpose: '錯誤但非阻斷(系統錯誤可重試、API 失敗摘要);aria-live=assertive' },
   },
   sizes: {},
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default'], // 2026-06-11 R2:Alert 本體無互動 state(spec L183 明文無 disabled;dismiss 互動屬內部 Button),
   tokens: {
     bg: ['bg-error', 'bg-error-subtle', 'bg-info', 'bg-info-subtle', 'bg-muted', 'bg-success', 'bg-success-subtle', 'bg-surface-raised', 'bg-warning', 'bg-warning-subtle'],
     fg: ['text-foreground'],

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

@@ -1,5 +1,6 @@
 // @benchmark-cited: Polaris / Material / Ant 共識 principles canonical(UsageGuidance integrated)
 import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
 
 const meta: Meta = {
   title: 'Design System/Components/AppShell/設計原則',
@@ -14,25 +15,72 @@ export const UsageGuidance: Story = {
     <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">何時用 AppShell</h2>
-        <ul className="text-body space-y-1">
-          <li>• 多頁 web service 主結構(Linear / Notion / Slack / GitHub / Asana 類)</li>
-          <li>• 需要 sidebar + main 持續共存,跨頁切換時 sidebar 不重渲染</li>
-          <li>• 需要 right panel(info / inspector / detail pane)跟 main 並存</li>
+        <ul className="text-body space-y-2">
+          <li>
+            • 多頁 web service 的主結構——Linear / Notion / Slack / GitHub / Asana 這類「左側導覽 + 中央工作區」產品。完整組合見{' '}
+            <LinkTo kind="Design System/Components/AppShell/展示" name="主側欄佈局 — Linear 式議題追蹤"><span className="text-primary hover:underline font-medium cursor-pointer">展示 → 主側欄佈局 — Linear 式議題追蹤</span></LinkTo>
+          </li>
+          <li>
+            • 需要 sidebar + main 持續共存——在議題列表、看板、報表等頁面間切換時,左側導覽不重渲染、捲動位置不丟失。見{' '}
+            <LinkTo kind="Design System/Components/AppShell/展示" name="主側欄佈局 + 頁面分頁"><span className="text-primary hover:underline font-medium cursor-pointer">展示 → 主側欄佈局 + 頁面分頁</span></LinkTo>
+          </li>
+          <li>
+            • 需要右側詳情面板(議題詳情 / inspector / 成員資料)跟 main 並存——如 Linear 點選議題後右側展開詳情。開合行為見{' '}
+            <LinkTo kind="Design System/Components/AppShell/設計規格" name="右側面板開合行為(兩種模式)"><span className="text-primary hover:underline font-medium cursor-pointer">設計規格 → 右側面板開合行為</span></LinkTo>
+          </li>
         </ul>
       </section>
 
       <section>
         <h2 className="text-h4 mb-2">何時不用</h2>
         <ul className="text-body space-y-1">
-          <li>• 單頁 landing / marketing site → `&lt;main&gt;` 直接展開</li>
-          <li>• Auth 頁(login / signup)→ 自寫 centered layout,不被 sidebar 佔位</li>
-          <li>• Embedded widget / iframe → 已被 host shell 包住</li>
+          <li>• 單頁 landing / marketing site(產品官網、定價頁)→ `&lt;main&gt;` 直接展開,沒導覽不需要 shell</li>
+          <li>• Auth 頁(login / signup)→ 自寫置中 layout,不被 sidebar 佔位</li>
+          <li>• Embedded widget / iframe(嵌進別人頁面的客服小視窗類)→ 已被 host shell 包住</li>
           <li>• 文件 reader(全螢幕閱讀)→ shell chrome 干擾閱讀</li>
         </ul>
       </section>
 
       <section>
         <h2 className="text-h4 mb-2">Layout mode 怎麼選</h2>
+        <p className="text-body">
+          兩種佈局模式(primary-sidebar / primary-header)的選型決策樹獨立成「佈局模式怎麼選」story(含
+          WorkspaceBrand 放置規則),見本頁側欄或{' '}
+          <LinkTo kind="Design System/Components/AppShell/設計原則" name="佈局模式怎麼選"><span className="text-primary hover:underline font-medium cursor-pointer">設計原則 → 佈局模式怎麼選</span></LinkTo>
+        </p>
+      </section>
+
+      <section>
+        <h2 className="text-h4 mb-2">vs Sidebar 規則</h2>
+        <p className="text-body">
+          AppShell 只負責整體組合、版面模式、以及右側面板的響應式開合。Sidebar 的外觀、行為、行動裝置上的
+          抽屜形式都由 Sidebar 元件自己定義,<strong>AppShell 不會去改 Sidebar 的樣式</strong>。
+          多個 sidebar 的情境要等 Sidebar 元件本身支援後才提供。
+        </p>
+      </section>
+
+      <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>
+        </ul>
+      </section>
+    </div>
+  ),
+}
+
+// 佈局模式選型 deep-dive — 內容錨定 app-shell.spec.md「兩 mode 差異」(L93-94 / L105 常見誤解)
+// +「WorkspaceBrand 放置 SSOT」(L112-119);category-templates.md component-specific `{Topic}Rule` idiom
+export const LayoutModeRule: Story = {
+  name: '佈局模式怎麼選',
+  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>
         <p className="text-body mb-2">
           唯一 distinguisher = <strong>Header scope 是 local 還是 global</strong>,
           <em>不是</em> workspace 多寡(Notion / Gmail 都支援 multi-workspace,卻分屬不同派)。
@@ -48,32 +96,31 @@ export const UsageGuidance: Story = {
             <strong>primary-header</strong>:多一條 <strong>global bar</strong> 橫跨頂部 —
             服務整個 app(account / workspace switcher / 跨頁 search / notifications);local toolbar
             <em>仍在</em> main col 頂,只是上面多了 global header。WorkspaceBrand 改放 globalHeader 左側。
-            參考 GitHub / Slack / Gmail。
+            參考 GitHub / Slack / Gmail。完整組合見{' '}
+            <LinkTo kind="Design System/Components/AppShell/展示" name="主標頭佈局 — 全域+本地兩層(GitHub/Gmail/Slack 派)"><span className="text-primary hover:underline font-medium cursor-pointer">展示 → 主標頭佈局 — 全域+本地兩層</span></LinkTo>
           </li>
         </ul>
-        <p className="text-caption text-fg-muted mt-2">
-          兩 mode 是 product 角色表態 — 啟動時固定,不該在 runtime 切換。
-          視覺對照圖見「設計規格 → 兩種布局模式對照圖」。
+        <p className="text-caption text-fg-secondary mt-2">
+          兩 mode 是 product 角色表態——啟動時固定,不該在 runtime 切換。視覺對照圖見{' '}
+          <LinkTo kind="Design System/Components/AppShell/設計規格" name="兩種布局模式對照圖"><span className="text-primary hover:underline font-medium cursor-pointer">設計規格 → 兩種布局模式對照圖</span></LinkTo>
         </p>
       </section>
 
       <section>
-        <h2 className="text-h4 mb-2">vs Sidebar 規則</h2>
+        <h2 className="text-h4 mb-2">常見誤解:global header 取代 local toolbar</h2>
         <p className="text-body">
-          AppShell 只負責整體組合、版面模式、以及右側面板的響應式開合。Sidebar 的外觀、行為、行動裝置上的
-          抽屜形式都由 Sidebar 元件自己定義,<strong>AppShell 不會去改 Sidebar 的樣式</strong>。
-          多個 sidebar 的情境要等 Sidebar 元件本身支援後才提供。
+          錯。primary-header = primary-sidebar 的所有東西 + <strong>額外一條</strong> global header 在頂;
+          `header` slot(local toolbar)<strong>仍然存在</strong>。GitHub / Slack / Gmail 全部同時保有兩層,
+          不是二選一。
         </p>
       </section>
 
       <section>
-        <h2 className="text-h4 mb-2">Consumer 紀律</h2>
+        <h2 className="text-h4 mb-2">WorkspaceBrand 跟著 mode 走(只能出現一次)</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</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>• <strong>primary-sidebar</strong>:WorkspaceBrand 放 Sidebar 頂部(`&lt;SidebarHeader&gt;` 內)— Linear / Notion / Figma file panel</li>
+          <li>• <strong>primary-header</strong>:WorkspaceBrand 改放 globalHeader 左側(搭配 SidebarTrigger),SidebarHeader 留空 — GitHub / Gmail / Figma file editor</li>
+          <li>❌ 禁:`primary-header` mode 同時在 globalHeader + SidebarHeader 各放一份 = 視覺冗餘 + 跨產品識別混淆(WorkspaceBrand 視覺 SSOT,只能出現一次)</li>
         </ul>
       </section>
     </div>