@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.84

package/ds-story-manifest.json

@@ -7,7 +7,7 @@
       "scripts/composition-fidelity-visual-diff.mjs",
       "product-workspace apps/template/src/AllDsComponents.stories.tsx (ImportSmoke portal → DS Storybook link)"
     ],
-    "generatedAt": "2026-07-06T11:37:10.794Z"
+    "generatedAt": "2026-07-14T14:23:30.051Z"
   },
   "components": {
     "accordion": {
@@ -40,10 +40,8 @@
     "alert": {
       "tiers": {
         "展示": [
-          "design-system-components-alert-展示--subtle-single-line",
-          "design-system-components-alert-展示--solid-single-line",
-          "design-system-components-alert-展示--subtle-with-description",
-          "design-system-components-alert-展示--solid-with-description",
+          "design-system-components-alert-展示--single-line",
+          "design-system-components-alert-展示--with-description",
           "design-system-components-alert-展示--corner-action-group",
           "design-system-components-alert-展示--fixed"
         ],
@@ -90,11 +88,8 @@
     "aspectratio": {
       "tiers": {
         "展示": [
-          "design-system-components-aspectratio-展示--hero-banner-16-x-9",
           "design-system-components-aspectratio-展示--product-photo-4-x-3",
-          "design-system-components-aspectratio-展示--square-avatar-1-x-1",
-          "design-system-components-aspectratio-展示--ultrawide-21-x-9",
-          "design-system-components-aspectratio-展示--common-ratios"
+          "design-system-components-aspectratio-展示--ultrawide-21-x-9"
         ],
         "設計規格": [
           "design-system-components-aspectratio-設計規格--overview",
@@ -265,7 +260,7 @@
         "設計原則": [
           "design-system-components-calendar-設計原則--usage-guidance",
           "design-system-components-calendar-設計原則--color-semantic",
-          "design-system-components-calendar-設計原則--mvp-scope"
+          "design-system-components-calendar-設計原則--month-view-only-rule"
         ]
       },
       "openSnapshotIds": [],
@@ -388,7 +383,7 @@
         "設計原則": [
           "design-system-components-circularprogress-設計原則--usage-guidance",
           "design-system-components-circularprogress-設計原則--indeterminate-vs-determinate-rule",
-          "design-system-components-circularprogress-設計原則--usage-scenario-rule",
+          "design-system-components-circularprogress-設計原則--consumption-scenario-rule",
           "design-system-components-circularprogress-設計原則--size-match-context-rule"
         ]
       },
@@ -451,7 +446,7 @@
         "展示": [
           "design-system-internal-command-展示--command-palette",
           "design-system-internal-command-展示--inline-command",
-          "design-system-internal-command-展示--theme-switcher",
+          "design-system-internal-command-展示--action-command",
           "design-system-internal-command-展示--empty-state"
         ],
         "設計規格": [
@@ -469,7 +464,6 @@
     "datatable": {
       "tiers": {
         "展示": [
-          "design-system-components-datatable-展示--number-alignment",
           "design-system-components-datatable-展示--column-resize",
           "design-system-components-datatable-展示--column-reorder",
           "design-system-components-datatable-展示--row-auto-height-inline-edit",
@@ -627,6 +621,7 @@
           "design-system-components-dialog-展示--long-content",
           "design-system-components-dialog-展示--destructive",
           "design-system-components-dialog-展示--list-body",
+          "design-system-components-dialog-展示--header-actions",
           "design-system-components-dialog-展示--with-tabs-in-header",
           "design-system-components-dialog-展示--open-snapshot"
         ],
@@ -880,6 +875,22 @@
       "openSnapshotIds": [],
       "exception": null
     },
+    "inlineedit": {
+      "tiers": {
+        "展示": [
+          "design-system-components-inlineedit-展示--task-title",
+          "design-system-components-inlineedit-展示--metadata-fields",
+          "design-system-components-inlineedit-展示--states",
+          "design-system-components-inlineedit-展示--select-tag-field",
+          "design-system-components-inlineedit-展示--multiline-description",
+          "design-system-components-inlineedit-展示--vertical-field-form"
+        ],
+        "設計規格": [],
+        "設計原則": []
+      },
+      "openSnapshotIds": [],
+      "exception": null
+    },
     "input": {
       "tiers": {
         "展示": [
@@ -941,6 +952,7 @@
           "design-system-internal-menu-展示--with-description",
           "design-system-internal-menu-展示--avatar-inline",
           "design-system-internal-menu-展示--avatar-block",
+          "design-system-internal-menu-展示--with-start-content",
           "design-system-internal-menu-展示--states",
           "design-system-internal-menu-展示--multi-select",
           "design-system-internal-menu-展示--groups",
@@ -1160,8 +1172,7 @@
         "展示": [
           "design-system-components-radiogroup-展示--modes",
           "design-system-components-radiogroup-展示--vertical-group",
-          "design-system-components-radiogroup-展示--horizontal",
-          "design-system-components-radiogroup-展示--disabled"
+          "design-system-components-radiogroup-展示--horizontal"
         ],
         "設計規格": [
           "design-system-components-radiogroup-設計規格--overview",
@@ -1259,6 +1270,7 @@
       "tiers": {
         "展示": [
           "design-system-components-select-展示--modes",
+          "design-system-components-select-展示--hug-width",
           "design-system-components-select-展示--display-mode",
           "design-system-components-select-展示--size-alignment",
           "design-system-components-select-展示--clearable",
@@ -1337,7 +1349,6 @@
         "展示": [
           "design-system-components-separator-展示--horizontal",
           "design-system-components-separator-展示--vertical",
-          "design-system-components-separator-展示--in-dropdown-menu",
           "design-system-components-separator-展示--between-sections"
         ],
         "設計規格": [
@@ -1413,7 +1424,6 @@
     "skeleton": {
       "tiers": {
         "展示": [
-          "design-system-components-skeleton-展示--default",
           "design-system-components-skeleton-展示--user-profile-card",
           "design-system-components-skeleton-展示--task-list-loading",
           "design-system-components-skeleton-展示--table-row-loading",
@@ -1655,7 +1665,6 @@
         "展示": [
           "design-system-components-tooltip-展示--default",
           "design-system-components-tooltip-展示--non-button-trigger",
-          "design-system-components-tooltip-展示--placement",
           "design-system-components-tooltip-展示--long-text"
         ],
         "設計規格": [
@@ -1702,6 +1711,6 @@
       "exception": null
     }
   },
-  "totalComponents": 63,
-  "totalStories": 920
+  "totalComponents": 64,
+  "totalStories": 919
 }

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.83。
+> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.84。
 
 # Components
 
@@ -115,6 +115,9 @@ Source(AI 讀此看官方範例): src/components/Checkbox/
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/Chip/
 
+### Sizes
+- **sm**: 單一尺寸(h-field-sm 28/32 依 density、icon 16、text-body)— 對齊 chip.tsx componentMeta
+
 ## CircularProgress(family self-contained)
 
 Storybook: https://ajenchen-design-system.netlify.app
@@ -194,11 +197,24 @@ Source(AI 讀此看官方範例): src/components/FileUpload/
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/FileViewer/
 
+## InlineEdit(family composite)
+
+Storybook: https://ajenchen-design-system.netlify.app
+Source(AI 讀此看官方範例): src/components/InlineEdit/
+
 ## Input(family 4)
 
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/Input/
 
+### Variants
+- **default**: Field wrapper 完整 chrome(bg-surface + border + hover/focus 回饋)— 表單 / Field 內嵌
+
+### Sizes
+- **sm**: field-height 28、icon 16、text-body
+- **md**: default 一般表單(field-height 32、icon 16)
+- **lg**: touch / 大字級(field-height 36、icon 20、text-body-lg)
+
 ## LinkInput(family 4)
 
 Storybook: https://ajenchen-design-system.netlify.app
@@ -401,6 +417,11 @@ Source(AI 讀此看官方範例): src/components/Tooltip/
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/TreeView/
 
+### Sizes
+- **sm**: 緊湊清單(與 md 同視覺:text-body、indent 24;保留供密度語意)
+- **md**: default 一般導覽樹
+- **lg**: touch / 大字級(text-body-lg、px-4 py-2、indent 28)
+
 # Patterns
 
 ## action-bar

package/llms.txt

@@ -1,7 +1,7 @@
 # @qijenchen/design-system
 
 > World-class React design system(Radix/shadcn + Tailwind v4 + 自訂 design token)。
-> 56 components + 4 public patterns + design tokens。v0.1.0-beta.83。
+> 57 components + 4 public patterns + design tokens。v0.1.0-beta.84。
 
 本檔由 source(spec.md frontmatter + Storybook index)build-time 自動生成,**禁手改**(CI --check drift gate 守)。
 每元件 / pattern 的完整 variants / sizes / 禁止事項 全文見 [llms-full.txt](./llms-full.txt)。
@@ -21,7 +21,7 @@
 - [Carousel](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Carousel
 - [Chart](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Chart
 - [Checkbox](https://ajenchen-design-system.netlify.app): sizes:sm/md/lg — src:components/Checkbox
-- [Chip](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Chip
+- [Chip](https://ajenchen-design-system.netlify.app): sizes:sm — src:components/Chip
 - [CircularProgress](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/CircularProgress
 - [Coachmark](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Coachmark
 - [Combobox](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Combobox
@@ -37,7 +37,8 @@
 - [FileItem](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/FileItem
 - [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
+- [InlineEdit](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/InlineEdit
+- [Input](https://ajenchen-design-system.netlify.app): variants:default;sizes:sm/md/lg — src:components/Input
 - [LinkInput](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/LinkInput
 - [NumberInput](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/NumberInput
 - [Pagination](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Pagination
@@ -63,7 +64,7 @@
 - [TimePicker](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/TimePicker
 - [Toast](https://ajenchen-design-system.netlify.app): variants:neutral/info/success/warning/error — src:components/Toast
 - [Tooltip](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Tooltip
-- [TreeView](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/TreeView
+- [TreeView](https://ajenchen-design-system.netlify.app): sizes:sm/md/lg — src:components/TreeView
 
 ## Patterns
 - [action-bar](https://ajenchen-design-system.netlify.app): 跨元件 anatomy / 設計參照 pattern — src:patterns/action-bar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qijenchen/design-system",
-  "version": "0.1.0-beta.83",
+  "version": "0.1.0-beta.84",
   "private": false,
   "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
   "type": "module",
@@ -36,7 +36,10 @@
       "types": "./dist/patterns/*/index.d.ts",
       "import": "./dist/patterns/*/index.js"
     },
-    "./tokens/*": "./src/tokens/*",
+    "./tokens/*": {
+      "types": "./dist/tokens/*.d.ts",
+      "import": "./dist/tokens/*.js"
+    },
     "./hooks/*": {
       "types": "./dist/hooks/*.d.ts",
       "import": "./dist/hooks/*.js"
@@ -100,7 +103,8 @@
     "react-zoom-pan-pinch": "^4.0.3",
     "recharts": "^3.8.1",
     "sonner": "^2.0.7",
-    "tailwind-merge": "^3.5.0"
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0",

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

@@ -109,7 +109,7 @@ export const UsageGuidance: Story = {
         title='Accordion — 獨立收合多段(每段各自是否展開)'
         note='每個 item 是獨立主題,使用者依興趣選擇展開。不是互斥,而是「多段內容,多數時間只想看其中一段」。'
       >
-        <Accordion type='single' collapsible>
+        <Accordion type='multiple'>
           <AccordionItem value='pricing'>
             <AccordionTrigger>付款週期與折扣</AccordionTrigger>
             <AccordionContent>年付享 20% 折扣。</AccordionContent>

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

@@ -162,7 +162,10 @@ export const AdvancedOptions: Story = {
           placeholder="一句話描述此專案"
         />
       </div>
-      <Accordion type="single" collapsible>
+      {/* 2026-07-14 Dim 68 修:原單一 AccordionItem 違反 accordion.spec.md「❌ 單一 item 不用
+          Accordion」(單區塊該用 <details>,見 principles「單一項目不用 Accordion」)。補第二個
+          可獨立收合的低頻設定段(type="multiple" 非互斥),成為合法多段收合場景。 */}
+      <Accordion type="multiple">
         <AccordionItem value="advanced">
           <AccordionTrigger>進階選項</AccordionTrigger>
           <AccordionContent>
@@ -184,6 +187,18 @@ export const AdvancedOptions: Story = {
             </div>
           </AccordionContent>
         </AccordionItem>
+        <AccordionItem value="notifications">
+          <AccordionTrigger>通知設定</AccordionTrigger>
+          <AccordionContent>
+            <div className="flex flex-col gap-1">
+              <label className="text-body text-foreground">狀態變更通知對象</label>
+              <input
+                className="h-field-md border border-border rounded-md px-3 text-body"
+                placeholder="例:專案成員 + 關注者"
+              />
+            </div>
+          </AccordionContent>
+        </AccordionItem>
       </Accordion>
     </div>
   ),

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

@@ -56,7 +56,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Components/Alert/展示" name="右上角操作群組"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">右上角操作群組</span></LinkTo>
         </li>
       </ul>
-      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見本頁下方「vs 近親」段)。</p>
     </div>
 
       {/* vs 近親 — VsToastVsDialogRule — 原 VsToastVsDialogRule */}

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

@@ -83,7 +83,7 @@ Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、
 - ❌ **不把 error form validation 做成 Alert**：欄位級錯誤必須貼近發生位置（FieldError）,使用者才能快速定位；頁面級 Alert 只放非欄位的整體錯誤（如提交失敗、權限不足）
 - ❌ **Alert 不疊 Alert**：同區出現多個 Alert 視覺雜訊重,整理成一組 messages 或合併為單一 Alert with list
 - ❌ **destructive 操作確認不用 Alert**：刪除 / 離開等需要明確確認的動作用 Dialog,Alert 無法承載 confirm / cancel 雙按鈕的阻斷流程
-- ❌ **兩個 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(防混用)」節
+- ❌ **右側操作區(endContent + close X)內不混不同分量的 action**:endContent(CTA / refresh 等)與 close X 同渲染進單一右上 suffix(對齊第一行、靠右);close X 必用 `<Button iconOnly dismiss size="xs" />`(不是 Inline Action、不是自刻 `<button><X /></button>`,見下方 Chrome corner close X canonical);同一 suffix 內所有 action 必同分量(統一 Button iconOnly xs),不可混 Inline Action + Button iconOnly,否則違反 same-row consistency(box size 與視覺分量不同,造成 gap / 對齊錯亂),完整規則見 `patterns/element-anatomy/inline-action.spec.md`「Same-row consistency rule(防混用)」節
 
 ---
 
@@ -92,7 +92,7 @@ Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、
 - **一般提示（neutral / info / success）**：`role="status"` + `aria-live="polite"`——screen reader 在空閒時讀出 Alert 內容，不中斷使用者目前動作
 - **緊急提示（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,文字描述動作(「前往設定」「立即更新」)
+- **CTA 按鈕**：透過 `endContent` 放進右側操作區(與 close X 同列,靠右上)size 固定為 `xs` tertiary,文字描述動作(「前往設定」「立即更新」)
 
 ---
 
@@ -111,13 +111,12 @@ SSOT 詳見 `patterns/element-anatomy/inline-action.spec.md`「Predicate:Inline
 
 ### Corner action group 佈局 canonical
 
-Alert chrome corner 可承載多個 action(close 左側並排):
+Alert 右側操作區(單一 suffix,對齊第一行靠右)可承載多個 action —— endContent 內容 + close X 並排:
 
 ```
-┌─ Alert ────────────────── [⟲] │ [X] ┐   ← chrome corner action group(Button xs)
-│ [icon] Title                         │     refresh / share / minimize 等 + ButtonDivider + close X
+┌─ Alert ────────────────── [⟲] │ [X] ┐   ← 右側操作區 action group(endContent + close X,Button xs)
+│ [icon] Title                         │     endContent(CTA / refresh / share 等)+ ButtonDivider + close X
 │ Description                          │
-│                      [CTA1] [CTA2]   │   ← body action row(Button xs tertiary)
 └──────────────────────────────────────┘
 ```
 
@@ -159,12 +158,11 @@ Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix`
 
 完整 placement 對照見 anatomy `PlacementMatrix` story。
 
-## 為何無 Inspector / SizeMatrix
+## 為何無 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 / 固定 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`。
+對應 anatomy story:`Overview` + `Inspector` + `ColorMatrix` + `PlacementMatrix` + `StateBehavior` + `Accessibility`(6-canonical;Alert 的 `Inspector` 互動切換 variant × appearance × placement × dismissible,SizeMatrix N/A 見上)。
 
 ---
 
@@ -181,7 +179,7 @@ Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix`
 ## 邊界案例
 
 - **Disabled(dismiss button)**:Alert **不提供 dismiss 停用 API**——banner dismiss 恆可用(對齊 Polaris / Material Banner:通知關閉鈕應永遠可按)。「恆可用」指**已渲染的 X 永遠可按**;X 本身僅在傳 `onDismiss` 時渲染(否則是死按鈕假 affordance,2026-07-05 D4,見「Multi corner action 場景」段 + `../Notice/notice.spec.md`「邊界案例」)。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。
+- **Loading**:Alert 本身不需 loading state(非 async surface);若 `endContent` 內的 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(見禁止事項)。
 

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

@@ -34,38 +34,38 @@ const D: Record<string, string> = {
 
 const actionBtn = <Button variant="tertiary" size="xs">查看詳情</Button>
 
-export const SubtleSingleLine = {
-  name: '低調單行',
+// 2026-07-14 audit Dim 28(story 拆分原則):原 Subtle/Solid × SingleLine/WithDescription
+// 四 story 依 appearance variant 拆細 = 「≥2 variants 拆細」反 pattern(該合對照 grid);
+// 合併為單行 / 含說明兩 story,各以 subtle vs solid 並排對照(appearance trait grid 本體
+// 由 anatomy ColorMatrix owns)。
+export const SingleLine = {
+  name: '單行（低調 vs 實心對照）',
   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} />)}
-    </div>
-  ),
-}
-
-export const SolidSingleLine = {
-  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} />)}
-    </div>
-  ),
-}
-
-export const SubtleWithDescription = {
-  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} />)}
+    <div className="grid grid-cols-2 gap-6 max-w-5xl">
+      {(['subtle', 'solid'] as const).map((appearance) => (
+        <div key={appearance} className="flex flex-col gap-3">
+          <span className="text-caption text-fg-muted font-medium">
+            {appearance === 'subtle' ? 'Subtle — 頁面內嵌預設(淺底 + 邊框)' : 'Solid — 高強調(飽和底色)'}
+          </span>
+          {ALL.map((v) => <Alert key={v} variant={v} appearance={appearance} title={L[v]} endContent={actionBtn} />)}
+        </div>
+      ))}
     </div>
   ),
 }
 
-export const SolidWithDescription = {
-  name: '實心含說明文字',
+export const WithDescription = {
+  name: '含說明文字（低調 vs 實心對照）',
   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} />)}
+    <div className="grid grid-cols-2 gap-6 max-w-5xl">
+      {(['subtle', 'solid'] as const).map((appearance) => (
+        <div key={appearance} className="flex flex-col gap-3">
+          <span className="text-caption text-fg-muted font-medium">
+            {appearance === 'subtle' ? 'Subtle — 頁面內嵌預設(淺底 + 邊框)' : 'Solid — 高強調(飽和底色)'}
+          </span>
+          {ALL.map((v) => <Alert key={v} variant={v} appearance={appearance} title={L[v]} description={D[v]} endContent={actionBtn} />)}
+        </div>
+      ))}
     </div>
   ),
 }
@@ -99,8 +99,8 @@ export const CornerActionGroup = {
       </div>
 
       <span className="text-caption text-fg-muted">
-        ✅ Close X 跟 refresh / share 同 Button iconOnly xs(chrome 輕量 action,chrome-header-height 幾何),Separator 分群。
-        ❌ 禁止混 Inline Action + Button iconOnly(違反 same-row consistency)。
+        ✅ 右上角這排(重新整理、分享、關閉)全用同一種最小尺寸的純圖示按鈕,並用分隔線分成兩群,保持同一列視覺一致。
+        ❌ 不要一群用純圖示按鈕、另一群用列內動作,會不整齊。
       </span>
     </div>
   ),

package/src/components/Alert/alert.tsx

@@ -12,7 +12,7 @@ import { Notice, useInverseTheme, SUBTLE_ICON_COLOR, type NoticeVariant } from '
  * 在 theme boundary 設 text-foreground 強制 re-resolve。
  *
  * ── Appearance ──
- * subtle: 淺底色 + 四邊 1px border(色相 hover 色)。不設 data-theme,跟隨頁面。
+ * subtle: 淺底色 + 四邊 1px border(色相 text 色 = icon 同色,見下方 SUBTLE_CONTAINER 註)。不設 data-theme,跟隨頁面。
  * solid: 跟 Toast 對齊:
  *   neutral → data-theme={inverse} + bg-surface-raised（同層翻轉）
  *   info/success/error → bg on outer, data-theme="dark" on inner

package/src/components/AppShell/_demo-helpers.tsx

@@ -80,6 +80,8 @@ export const MAIN_NAV = [
 export const WorkspaceBrand = () => (
   <div className="flex items-center gap-2 min-w-0">
     {/* 24 per header-canonical.spec.md 4.5 chrome header avatar canonical; sync with `--chrome-header-avatar-size` */}
+    {/* Workspace brand = 組織識別(非人)→ 首字 letter mark;2026-07-08 人像真實化 sweep 刻意保留,
+        真實人像僅套用於 person avatar(組織用人臉照片會誤導身份) */}
     <Avatar size={24} shape="square" color="blue" solid alt="Acme Inc" />
     <span className="text-body-lg font-medium truncate group-data-[collapsible=icon]:hidden">Acme Inc</span>
   </div>
@@ -93,13 +95,14 @@ export const UserFooter = () => (
       <SidebarMenuButton asChild>
         <div role="group" aria-label="當前使用者">
           <ItemAvatar
+            src="https://i.pravatar.cc/48?u=EMP-1001"
             alt="Alan Chen"
             color="blue"
             hoverCard={
               <ProfileCard
                 name="Alan Chen"
                 subtitle="Design｜D-0042"
-                avatar={{ alt: 'Alan Chen', color: 'blue' }}
+                avatar={{ src: 'https://i.pravatar.cc/80?u=EMP-1001', alt: 'Alan Chen', color: 'blue' }}
                 status="online"
                 actions={<ProfileCardDefaultActions />}
               />
@@ -190,7 +193,7 @@ export function AcmeSidebar({
 // (非 ProfileCard——ProfileCard 是看「別人」的人員卡,預設動作 Chat/通話用在自己身上不對)。
 // 消費 SSOT:
 //   - <Avatar size={24}>(header-canonical.spec.md 4.5 chrome header avatar:brand + account 同 24px;
-//     sync with --chrome-header-avatar-size)。互動感由 focus ring + hover 提供,不放大到 field height。
+//     sync with --chrome-header-avatar-size)。互動感由 focus-visible ring 提供(無 hover bg,chrome 輕量 entry),不放大到 field height。
 //   - <DropdownMenu>(個人資料 / 設定 / 登出;baseline = dropdown-menu.stories.tsx Groups)
 //   - 放置 / 邊距對稱 canonical → app-shell.spec.md「帳號入口(Account entry)放置 SSOT」段
 export function AccountMenu() {
@@ -203,7 +206,7 @@ export function AccountMenu() {
           className="flex items-center justify-center rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1"
         >
           {/* 24 per header-canonical.spec.md 4.5 chrome header avatar canonical(brand + account 同尺寸); sync with --chrome-header-avatar-size */}
-          <Avatar size={24} alt="Alan Chen" color="blue" />
+          <Avatar size={24} src="https://i.pravatar.cc/48?u=EMP-1001" alt="Alan Chen" color="blue" />
         </button>
       </DropdownMenuTrigger>
       <DropdownMenuContent align="end">

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

@@ -205,7 +205,7 @@ function CustomAside() {
 - **Scroll ownership**:Aside 自帶 scroll(body 包 `<ScrollArea>` primitive + `min-h-0`,per Atlassian Layout 慣例),main 自帶 scroll,**禁止** body-level scroll
 
 **Modal overlay** 行為:
-- 消費既有 `sheet.spec.md` canonical(從右滑出 + Esc 關 + click-outside 關 + focus trap + restore focus)
+- 消費既有 `sheet.spec.md` canonical(從右滑出 + Esc 關 + click-outside 關 + focus trap);**restore focus 由 AppShellAside 自建**(controlled Sheet 無 SheetTrigger → Radix 內建回焦失效;開啟時 snapshot opener、關閉還原、opener 已卸載 fallback `#app-shell-main`,WCAG 2.4.3,2026-07-14)
 - **title prop required**(per `sheet.spec.md`「禁止事項」禁無 title — `aria-labelledby` 強制)
 - 跟 Sidebar mobile fallback 同 SSOT
 
@@ -263,7 +263,7 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 | **`⌘.`(macOS)/ `Ctrl+.`(Windows)** | Toggle aside | Linear convention(新加) |
 | **Skip-to-main link** | `Tab` 第一站 focus 「Skip to content」link → `main` | A11y WCAG 2.4.1 bypass blocks;對齊 Atlassian Layout skip-link |
 
-兩者消費既有 Sidebar keyboard shortcut 機制(`useEffect` + `window.addEventListener('keydown')`),AppShell 不發明新機制。
+**`⌘B`** 消費既有 Sidebar SSOT 機制(Sidebar 內建 `useEffect` + `window.addEventListener('keydown')`,AppShell **不重複 register**)。**`⌘.`** 為 AppShell **自有** `window` keydown listener(`app-shell.tsx:179-188`,沿用相同 pattern 形態,但屬**新註冊**、非消費 Sidebar — 對齊上表「新加」標記)。此 AppShell 自有 listener 目前**未含** Sidebar handler 的 IME composition / input-textarea guard(打字時 `⌘.` 仍會觸發 — 已知 gap)。
 
 ---
 
@@ -321,8 +321,8 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 ## Consumer 紀律
 
 - ❌ 禁:`<AppShell>` 內 wrap 第二個 `<AppShell>`(nested shell 違反「整頁框架」單例性)
-- ❌ 禁:`sidebar={<div>...</div>}`(應傳 `<Sidebar>` primitive,確保視覺 SSOT。型別上收 ReactNode、不做機械強制 — React 型別強制易被 wrapper 包一層繞過,世界級 shell 元件皆收 ReactNode;本約定靠 story 示範 + audit 把關。2026-06-10 user 拍板 2a:措辭「必」→「應」對齊 code 真實)
-- ❌ 禁:`header={<header>...</header>}`(應傳 `<ChromeHeader>` 或消費 `header-canonical` 派生 header;同上,型別不機械強制)
+- ❌ 禁:`sidebar={<div>...</div>}`(應傳 `<Sidebar>` primitive,確保視覺 SSOT。raw-element slot 簽名(`sidebar={<div>}` / `header={<header>}` 等)由 `check_consumer_app_invariants.sh` Pattern 9 機械攔(P0,2026-06-12 加);TS 型別層仍收 ReactNode 不強制 — React 型別強制易被 wrapper 包一層繞過,世界級 shell 元件皆收 ReactNode;wrapper 包一層繞過的殘餘 case 靠 story 示範 + audit 把關。2026-06-10 user 拍板 2a:措辭「必」→「應」對齊 code 真實)
+- ❌ 禁:`header={<header>...</header>}`(應傳 `<ChromeHeader>` 或消費 `header-canonical` 派生 header;同上 — Pattern 9 同攔 header raw-element,TS 型別層不強制)
 - ❌ 禁:AppShell.Main 自加 padding(違反 layoutSpace 規則 1B)
 - ❌ 禁:AppShellAside header 加第二行 / actions(header = 單行 title + close X,API typed `title: string` 結構鎖;說明文字歸 aside body — 2026-06-12 fork-drift 防線)
 - ✅ 必:`layout` mode 在 product 啟動時固定,**不在 runtime 切換**(切換 = product 角色變動 = 應該重 mount app)

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

@@ -18,6 +18,7 @@ import {
   Sheet,
   SheetContent,
   SheetTitle,
+  handleSheetOpenAutoFocus,
 } from '@/design-system/components/Sheet/sheet'
 import { Button } from '@/design-system/components/Button/button'
 import { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'
@@ -32,7 +33,7 @@ type AppShellLayout = 'primary-sidebar' | 'primary-header'
 export interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
   /** primary-sidebar (Linear/Notion 派) | primary-header (GitHub/Slack 派);預設 primary-sidebar */
   layout?: AppShellLayout
-  /** Sidebar 元素(必傳 Sidebar primitive,per Consumer 紀律)*/
+  /** Sidebar 元素(應傳 Sidebar primitive,per Consumer 紀律;型別 optional 不機械強制,對齊 spec「應」措辭)*/
   sidebar?: React.ReactNode
   /**
    * Local page header(永遠 render 在 main column 頂部,當前頁 actions / breadcrumb / page-level filter)。
@@ -307,6 +308,9 @@ const AppShellAside = React.forwardRef<HTMLElement, AppShellAsideProps>(
     // SheetContent 的 aria-labelledby 指向不存在的 id → SR 念「unnamed dialog」+ Radix
     // TitleWarning console.error(違 sheet.spec.md:98「Sheet content 必有可見 title」)。
     // inline(aside)用純 <h2>:aside 自身已 aria-label={title},且無 Dialog context 不可用 SheetTitle。
+    // R1:mobile Sheet 關閉後焦點還原目標(open 時 snapshot)
+    const asideOpenerRef = React.useRef<HTMLElement | null>(null)
+
     const renderFrame = (titleNode: React.ReactNode) => (
       <>
         <ChromeHeader>
@@ -327,12 +331,34 @@ const AppShellAside = React.forwardRef<HTMLElement, AppShellAsideProps>(
     )
 
     // Modal mode(mobile)— Sheet from right
+    // 2026-07-14 dim-9 修:同步轉交 forwarded ref + 合併 consumer className —— 原 mobile 分支
+    // 兩者皆遺失,同一 API(ref / className)隨 breakpoint 靜默失效(desktop 有效、mobile 無效)。
     if (isMobile) {
       return (
         <Sheet open={asideOpen} onOpenChange={setAsideOpen}>
           <SheetContent
+            ref={ref as React.Ref<HTMLDivElement>}
             side="right"
-            className="w-[min(90vw,var(--app-shell-aside-modal-width))] flex flex-col p-0 [&>button]:hidden"
+            // R1 WCAG 2.4.3(2026-07-14,Claude+codex A′ 共識):controlled Sheet 無 SheetTrigger →
+            // Radix onCloseAutoFocus triggerRef=null + preventDefault 吃掉 fallback → 焦點掉 <body>。
+            // 解:開啟時 snapshot opener(事件 dispatch 時 Radix 尚未移焦;MUI/React Aria/Ant snapshot
+            // 共識 + DatePicker Range 先例 date-picker.tsx:1061),關閉手動還原;opener 已 unmount →
+            // fallback skip-link main(#app-shell-main tabIndex=-1)。
+            onOpenAutoFocus={(e) => {
+              asideOpenerRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null
+              handleSheetOpenAutoFocus(e) // 接力 DS 預設 body-focus(自訂 handler 覆寫預設,故顯式呼叫)
+            }}
+            onCloseAutoFocus={(e) => {
+              e.preventDefault()
+              const opener = asideOpenerRef.current
+              asideOpenerRef.current = null
+              if (opener?.isConnected) { opener.focus({ preventScroll: true }); return }
+              document.getElementById('app-shell-main')?.focus({ preventScroll: true })
+            }}
+            className={cn(
+              'w-[min(90vw,var(--app-shell-aside-modal-width))] flex flex-col p-0 [&>button]:hidden',
+              className
+            )}
             style={{ ['--app-shell-aside-modal-width' as string]: `${resolvedWidth}px` }}
           >
             {renderFrame(<SheetTitle className="flex-1">{title}</SheetTitle>)}

package/src/components/AspectRatio/aspect-ratio.spec.md

@@ -93,7 +93,7 @@ children 通常要 `className="w-full h-full object-cover"` 讓圖填滿容器;
 
 ## 邊界案例
 
-- **極端 ratio**:`ratio` 接受任意正數,元件不驗證、不設上下限(`1/10` 極扁 / `10/1` 極窄高都照算);是否合理由 consumer 把關
+- **極端 ratio**:`ratio` 接受任意正數,元件不驗證、不設上下限(`1/10` 極窄高 / `10/1` 極扁都照算);是否合理由 consumer 把關
 - **容器 resize**:高度恆 = 寬度 ÷ ratio(padding-bottom 百分比機制),父層寬度變化時高度自動跟隨,無需 JS
 - **children 超出**:元件不自動裁切 — 超出 ratio 容器的內容會溢出;裁切由 consumer 加 `overflow-hidden`(見 Consumer 範例)
 - **媒體原始比例 ≠ 容器 ratio**:呈現由 children 的 `object-cover`(裁滿)/ `object-contain`(留白)決定,元件不介入