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

package/ds-canonical/skills/ux-audit/SKILL.md

@@ -71,7 +71,7 @@ description: UX behavior audit for design-system components and product UI. Chec
 1. **Animation duration**:< 200ms(micro)或 200-400ms(macro);超過 400ms 主畫面 → 可能 block 輸入
 2. **Reduce-motion respect**:`@media (prefers-reduced-motion: reduce)` 下動畫減到 0 或極短
 3. **Wheel zoom step 細緻**:> 10% 離散 = 非世界級(對齊 Figma / Preview.app ~3-5%)
-4. **Hover delay**:tooltip / hover-card 的 open delay(700ms for tooltip, 500ms for hover-card per DS canonical)
+4. **Hover delay**:tooltip / hover-card 的 open delay(500ms for tooltip, 700ms for hover-card,per `tokens/motion/motion.spec.md` 三層 tier SSOT)
 5. **Drag / pan**:pointer capture 正確;release on blur
 
 ### Phase 5 — Data / state coverage 五態(2026-04-24 擴充,補 24-checklist #23 edge case gap)

package/ds-canonical/skills/visual-audit/SKILL.md

@@ -250,4 +250,3 @@ FAIL 項摘要:
 - `.claude/skills/component-quality-gate/SKILL.md` — 元件合入 DS 前的 35 項 checklist;Ship phase 可 chain 本 skill
 - .claude/references/ui-dev-rules.md `# 同 flex 列的互動 slot 幾何鐵律` — 本 skill checklist #3 的主要 canonical 來源
 - `.claude/rules/ui-development.md`「建立 UI 前必讀」 → layout primitive / token spec 清單 — 本 skill「合格標準」的對照錨
-- `memory/project_pending_tasks`「視覺 regression 基建」條目 — 長期 tech debt(Chromatic / screenshot-diff)

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-14T14:23:30.051Z"
+    "generatedAt": "2026-07-18T09:25:13.585Z"
   },
   "components": {
     "accordion": {
@@ -190,7 +190,6 @@
       "tiers": {
         "展示": [
           "design-system-components-bulkactionbar-展示--default",
-          "design-system-components-bulkactionbar-展示--with-filter-hidden",
           "design-system-components-bulkactionbar-展示--with-extend-dataset-hint",
           "design-system-components-bulkactionbar-展示--empty-selection-hidden"
         ],
@@ -419,7 +418,6 @@
         "展示": [
           "design-system-components-combobox-展示--modes",
           "design-system-components-combobox-展示--size-alignment",
-          "design-system-components-combobox-展示--wrap-modes",
           "design-system-components-combobox-展示--searchable",
           "design-system-components-combobox-展示--in-data-table"
         ],
@@ -561,7 +559,7 @@
           "design-system-components-datepicker-展示--show-time-range-popover-open",
           "design-system-components-datepicker-展示--range-middle-hover-state",
           "design-system-components-datepicker-展示--show-time-range",
-          "design-system-components-datepicker-展示--display"
+          "design-system-components-datepicker-展示--view"
         ],
         "設計規格": [
           "design-system-components-datepicker-設計規格--overview",
@@ -731,7 +729,6 @@
         ],
         "設計原則": [
           "design-system-components-field-設計原則--usage-guidance",
-          "design-system-components-field-設計原則--responsibility-rule",
           "design-system-components-field-設計原則--orientation-rule",
           "design-system-components-field-設計原則--not-for-form-actions-rule"
         ]
@@ -885,8 +882,19 @@
           "design-system-components-inlineedit-展示--multiline-description",
           "design-system-components-inlineedit-展示--vertical-field-form"
         ],
-        "設計規格": [],
-        "設計原則": []
+        "設計規格": [
+          "design-system-components-inlineedit-設計規格--overview",
+          "design-system-components-inlineedit-設計規格--inspector",
+          "design-system-components-inlineedit-設計規格--state-behavior",
+          "design-system-components-inlineedit-設計規格--in-field-cascade",
+          "design-system-components-inlineedit-設計規格--accessibility"
+        ],
+        "設計原則": [
+          "design-system-components-inlineedit-設計原則--when-to-use",
+          "design-system-components-inlineedit-設計原則--when-not-to-use",
+          "design-system-components-inlineedit-設計原則--vs-control-view",
+          "design-system-components-inlineedit-設計原則--content-guidelines"
+        ]
       },
       "openSnapshotIds": [],
       "exception": null
@@ -926,7 +934,7 @@
           "design-system-components-linkinput-展示--validation",
           "design-system-components-linkinput-展示--size-alignment",
           "design-system-components-linkinput-展示--modes",
-          "design-system-components-linkinput-展示--display"
+          "design-system-components-linkinput-展示--view"
         ],
         "設計規格": [
           "design-system-components-linkinput-設計規格--overview",
@@ -1028,7 +1036,6 @@
         "展示": [
           "design-system-internal-overflowindicator-展示--combobox-tag-overflow",
           "design-system-internal-overflowindicator-展示--avatar-stack-overflow",
-          "design-system-internal-overflowindicator-展示--breadcrumb-collapse",
           "design-system-internal-overflowindicator-展示--table-row-assignees"
         ],
         "設計規格": [
@@ -1196,8 +1203,7 @@
         "展示": [
           "design-system-components-rating-展示--read-only-product-rating",
           "design-system-components-rating-展示--interactive-review",
-          "design-system-components-rating-展示--in-field",
-          "design-system-components-rating-展示--disabled"
+          "design-system-components-rating-展示--in-field"
         ],
         "設計規格": [
           "design-system-components-rating-設計規格--overview",
@@ -1271,10 +1277,10 @@
         "展示": [
           "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",
           "design-system-components-select-展示--searchable",
+          "design-system-components-select-展示--creatable",
           "design-system-components-select-展示--in-data-table"
         ],
         "設計規格": [
@@ -1302,7 +1308,6 @@
           "design-system-internal-selectmenu-展示--searchable",
           "design-system-internal-selectmenu-展示--multi-select",
           "design-system-internal-selectmenu-展示--multi-searchable",
-          "design-system-internal-selectmenu-展示--clearable",
           "design-system-internal-selectmenu-展示--option-states"
         ],
         "設計規格": [
@@ -1476,7 +1481,6 @@
       "tiers": {
         "展示": [
           "design-system-components-steps-展示--default",
-          "design-system-components-steps-展示--focus-ring-combinations",
           "design-system-components-steps-展示--non-linear",
           "design-system-components-steps-展示--horizontal",
           "design-system-components-steps-展示--multiple-expansion"
@@ -1531,10 +1535,8 @@
         "展示": [
           "design-system-components-tabs-展示--default",
           "design-system-components-tabs-展示--with-suffix",
-          "design-system-components-tabs-展示--all-with-start-icon",
           "design-system-components-tabs-展示--overflow-scroll",
-          "design-system-components-tabs-展示--overflow-menu",
-          "design-system-components-tabs-展示--disabled"
+          "design-system-components-tabs-展示--overflow-menu"
         ],
         "設計規格": [
           "design-system-components-tabs-設計規格--overview",
@@ -1629,7 +1631,6 @@
         "設計原則": [
           "design-system-components-timepicker-設計原則--usage-guidance",
           "design-system-components-timepicker-設計原則--rule-minute-step-for-meetings",
-          "design-system-components-timepicker-設計原則--rule-range-composition",
           "design-system-components-timepicker-設計原則--rule-clear-no-label-button"
         ]
       },
@@ -1688,8 +1689,7 @@
           "design-system-components-treeview-展示--stepper",
           "design-system-components-treeview-展示--with-checkbox",
           "design-system-components-treeview-展示--long-label",
-          "design-system-components-treeview-展示--drag-and-drop",
-          "design-system-components-treeview-展示--indent-alignment"
+          "design-system-components-treeview-展示--drag-and-drop"
         ],
         "設計規格": [
           "design-system-components-treeview-設計規格--overview",
@@ -1712,5 +1712,5 @@
     }
   },
   "totalComponents": 64,
-  "totalStories": 919
+  "totalStories": 917
 }

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.85。
+> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.86。
 
 # Components
 
@@ -418,9 +418,9 @@ Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/TreeView/
 
 ### Sizes
-- **sm**: 緊湊清單(與 md 同視覺:text-body、indent 24;保留供密度語意)
+- **sm**: 緊湊清單(與 md 同視覺,保留供密度語意)
 - **md**: default 一般導覽樹
-- **lg**: touch / 大字級(text-body-lg、px-4 py-2、indent 28)
+- **lg**: touch / 大字級
 
 # Patterns
 

package/llms.txt

@@ -1,7 +1,7 @@
 # @qijenchen/design-system
 
 > World-class React design system(Radix/shadcn + Tailwind v4 + 自訂 design token)。
-> 57 components + 4 public patterns + design tokens。v0.1.0-beta.85。
+> 57 components + 4 public patterns + design tokens。v0.1.0-beta.86。
 
 本檔由 source(spec.md frontmatter + Storybook index)build-time 自動生成,**禁手改**(CI --check drift gate 守)。
 每元件 / pattern 的完整 variants / sizes / 禁止事項 全文見 [llms-full.txt](./llms-full.txt)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qijenchen/design-system",
-  "version": "0.1.0-beta.85",
+  "version": "0.1.0-beta.86",
   "private": false,
   "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
   "type": "module",
@@ -14,6 +14,7 @@
     "!src/**/*.test.ts",
     "README.md",
     "CLAUDE.md",
+    "AGENTS.md",
     "ds-canonical",
     "!ds-canonical/.claude",
     "!**/__pycache__",

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

@@ -33,19 +33,19 @@ export const Overview: Story = {
         <div className="border border-border rounded-lg p-4 max-w-[640px]">
           <Accordion type="single" collapsible defaultValue="anatomy">
             <AccordionItem value="anatomy">
-              <AccordionTrigger>AccordionTrigger(可點擊 header + chevron)</AccordionTrigger>
+              <AccordionTrigger>退款要多久才會入帳?</AccordionTrigger>
               <AccordionContent>
-                AccordionContent 區域——展開時顯示,收合時隱藏(animate-accordion-down / up)。
+                信用卡退款於 5–10 個工作天內退回原付款帳戶,實際入帳時間依發卡銀行作業而定。
               </AccordionContent>
             </AccordionItem>
             <AccordionItem value="item-2">
-              <AccordionTrigger>下一個 AccordionItem</AccordionTrigger>
-              <AccordionContent>每個 Item 之間由 border-b border-divider 分隔。</AccordionContent>
+              <AccordionTrigger>退款會扣手續費嗎?</AccordionTrigger>
+              <AccordionContent>標準訂單退款不收手續費;跨境訂單的匯率價差由發卡機構認列,本平台不另收費。</AccordionContent>
             </AccordionItem>
           </Accordion>
         </div>
         <p className="text-footnote text-fg-muted mt-3">
-          結構:<span className="font-mono">[trigger: label + chevron(16px, rotate 180deg when open)] / [content: pb-4 + text-fg-secondary]</span>
+          結構:<span className="font-mono">[trigger: label + chevron(16px, rotate 180deg when open)] / [content: pb-4 + text-fg-secondary]</span>。每個 AccordionItem(含最後一個)底緣皆有 <span className="font-mono">border-b border-divider</span>——divider 在 item 底緣而非僅 item 之間(shadcn 同款)。
         </p>
       </div>
 
@@ -440,16 +440,16 @@ export const StateBehavior: Story = {
         <div className="border border-border rounded-lg p-4 max-w-[640px]">
           <Accordion type="single" collapsible>
             <AccordionItem value="a">
-              <AccordionTrigger>可用區塊</AccordionTrigger>
-              <AccordionContent>正常展開。</AccordionContent>
+              <AccordionTrigger>個人資料</AccordionTrigger>
+              <AccordionContent>姓名、聯絡方式與頭像設定。</AccordionContent>
             </AccordionItem>
             <AccordionItem value="b" disabled>
-              <AccordionTrigger>已停用區塊(尚未開放)</AccordionTrigger>
-              <AccordionContent>點不開。</AccordionContent>
+              <AccordionTrigger>進階分析(升級 Pro 解鎖)</AccordionTrigger>
+              <AccordionContent>此區塊需 Pro 方案才可使用。</AccordionContent>
             </AccordionItem>
             <AccordionItem value="c">
-              <AccordionTrigger>另一個可用區塊</AccordionTrigger>
-              <AccordionContent>正常展開。</AccordionContent>
+              <AccordionTrigger>通知偏好</AccordionTrigger>
+              <AccordionContent>Email 每日摘要、@提及立即通知。</AccordionContent>
             </AccordionItem>
           </Accordion>
         </div>

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

@@ -269,23 +269,25 @@ export const ContentRule: Story = {
     <div>
       <Rule
         title='✅ 可放 — 文字說明、簡單表單欄位'
-        note='Accordion 適合承載閱讀性內容或輕量輸入(e.g. 進階選項的文字欄位)。'
+        note='Accordion 適合承載閱讀性內容或輕量輸入(e.g. 進階選項的文字欄位)。多段獨立設定各自收合(type="multiple"),不是單一 item——單一區塊該用 details(見「單一項目不用 Accordion」)。'
       >
-        <Accordion type='single' collapsible>
-          <AccordionItem value='form'>
-            <AccordionTrigger>進階選項</AccordionTrigger>
+        <Accordion type='multiple'>
+          <AccordionItem value='deploy'>
+            <AccordionTrigger>進階部署設定</AccordionTrigger>
             <AccordionContent>
               <div className='flex flex-col gap-3'>
                 <div className='flex flex-col gap-1'>
-                  <label className='text-body text-foreground'>專案識別碼</label>
+                  <label htmlFor='adv-project-id' className='text-body text-foreground'>專案識別碼</label>
                   <input
+                    id='adv-project-id'
                     className='h-field-md border border-border rounded-md px-3 text-body'
                     placeholder='例:Q2-RELEASE'
                   />
                 </div>
                 <div className='flex flex-col gap-1'>
-                  <label className='text-body text-foreground'>自訂網域</label>
+                  <label htmlFor='adv-custom-domain' className='text-body text-foreground'>自訂網域</label>
                   <input
+                    id='adv-custom-domain'
                     className='h-field-md border border-border rounded-md px-3 text-body'
                     placeholder='your-team.example.com'
                   />
@@ -293,6 +295,19 @@ export const ContentRule: Story = {
               </div>
             </AccordionContent>
           </AccordionItem>
+          <AccordionItem value='seo'>
+            <AccordionTrigger>SEO 與中繼資料</AccordionTrigger>
+            <AccordionContent>
+              <div className='flex flex-col gap-1'>
+                <label htmlFor='adv-page-title' className='text-body text-foreground'>頁面標題</label>
+                <input
+                  id='adv-page-title'
+                  className='h-field-md border border-border rounded-md px-3 text-body'
+                  placeholder='顯示於瀏覽器分頁與搜尋結果'
+                />
+              </div>
+            </AccordionContent>
+          </AccordionItem>
         </Accordion>
       </Rule>
 

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

@@ -112,7 +112,16 @@ Consumer 無需額外處理,保留 Radix `data-state` 屬性即可。
 
 ## 邊界狀態
 
-Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consumer 用 `<Skeleton />` 包;disabled state 詳 `../Field/field-controls.spec.md`;本元件無 density 概念,padding 固定為 `py-4 / pb-4`(不隨 density token 變動)。**垂直留白世界級對照(2026-06-12 source-verified)**:shadcn trigger `py-4`=16px(本 DS 基底,一字不差)/ Ant Collapse header 垂直 = paddingSM 12px / MUI Accordion = minHeight 48 + content margin 12px(expanded 64/20 漸進式)/ Carbon = min-height token 模型——業界垂直節奏值域 12-16px,16px 為舒適端上緣;item 數量無內建上限與虛擬捲動(全數 render),極長清單的收納(拆頁 / 搜尋)由 consumer 內容層處理。
+Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consumer 用 `<Skeleton />` 包;本元件無 density 概念,padding 固定為 `py-4 / pb-4`(不隨 density token 變動)。
+
+**Disabled**(Accordion 是 composite 家族,**非 Field 家族**——disabled 行為由 Radix Accordion 提供,不走 field-controls SSOT):
+
+- **Root `disabled`**:停用整個 accordion,所有 trigger 皆不可展開 / 聚焦。
+- **AccordionItem `disabled`**:停用單一 item——Radix 將 `disabled` 設在原生 `<button>` trigger 上,故該 trigger 鍵盤 Tab / ArrowUp/Down 會**略過**(原生 disabled 不可聚焦),點擊亦無反應;視覺上 trigger 文字 + chevron 切語義 `text-fg-disabled`(非降透明度,對齊 Button variant=text)。live 展示見 anatomy `StateBehavior` 的「disabled item」段。
+
+**固定 anatomy(不支援 `asChild`)**:`AccordionTrigger` 恆渲染 `children + ChevronDown` 兩個子節點,`AccordionContent` 恆以內層 `<div className="pb-4">` 包住 children——兩者的型別皆已 `Omit<..., 'asChild'>`,**不對外開放 `asChild`**。理由:傳入會讓 Radix Slot 觸發 `React.Children.only` runtime 錯(Trigger 多子節點),或 consumer 元素無法成為 Content host(只 clone 內層 div)。需替換 host 結構時改自組 Radix Accordion。
+
+**垂直留白世界級對照(2026-06-12 source-verified)**:shadcn trigger `py-4`=16px(本 DS 基底,一字不差;[ui.shadcn.com/docs/components/accordion](https://ui.shadcn.com/docs/components/accordion))/ Ant Collapse header 垂直 = paddingSM 12px([github.com/ant-design/ant-design](https://github.com/ant-design/ant-design/tree/master/components/collapse))/ MUI Accordion = minHeight 48 + content margin 12px(expanded 64/20 漸進式;[github.com/mui/material-ui](https://github.com/mui/material-ui/tree/master/packages/mui-material/src/Accordion))/ Carbon = min-height token 模型([github.com/carbon-design-system/carbon](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Accordion))——業界垂直節奏值域 12-16px,16px 為舒適端上緣;item 數量無內建上限與虛擬捲動(全數 render),極長清單的收納(拆頁 / 搜尋)由 consumer 內容層處理。
 
 ---
 

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

@@ -149,15 +149,17 @@ export const AdvancedOptions: Story = {
   render: () => (
     <div className="max-w-[640px] flex flex-col gap-4">
       <div className="flex flex-col gap-1">
-        <label className="text-body font-medium text-foreground">專案名稱</label>
+        <label htmlFor="adv-project-name" className="text-body font-medium text-foreground">專案名稱</label>
         <input
+          id="adv-project-name"
           className="h-field-md border border-border rounded-md px-3 text-body"
           defaultValue="Q2 發布計畫"
         />
       </div>
       <div className="flex flex-col gap-1">
-        <label className="text-body font-medium text-foreground">專案描述</label>
+        <label htmlFor="adv-project-desc" className="text-body font-medium text-foreground">專案描述</label>
         <input
+          id="adv-project-desc"
           className="h-field-md border border-border rounded-md px-3 text-body"
           placeholder="一句話描述此專案"
         />
@@ -171,15 +173,17 @@ export const AdvancedOptions: Story = {
           <AccordionContent>
             <div className="flex flex-col gap-3">
               <div className="flex flex-col gap-1">
-                <label className="text-body text-foreground">專案識別碼(選填)</label>
+                <label htmlFor="adv-opt-project-id" className="text-body text-foreground">專案識別碼(選填)</label>
                 <input
+                  id="adv-opt-project-id"
                   className="h-field-md border border-border rounded-md px-3 text-body font-mono"
                   placeholder="例:Q2-RELEASE"
                 />
               </div>
               <div className="flex flex-col gap-1">
-                <label className="text-body text-foreground">預設檢視模式</label>
+                <label htmlFor="adv-view-mode" className="text-body text-foreground">預設檢視模式</label>
                 <input
+                  id="adv-view-mode"
                   className="h-field-md border border-border rounded-md px-3 text-body"
                   defaultValue="看板"
                 />
@@ -191,8 +195,9 @@ export const AdvancedOptions: Story = {
           <AccordionTrigger>通知設定</AccordionTrigger>
           <AccordionContent>
             <div className="flex flex-col gap-1">
-              <label className="text-body text-foreground">狀態變更通知對象</label>
+              <label htmlFor="adv-notify-target" className="text-body text-foreground">狀態變更通知對象</label>
               <input
+                id="adv-notify-target"
                 className="h-field-md border border-border rounded-md px-3 text-body"
                 placeholder="例:專案成員 + 關注者"
               />

package/src/components/Accordion/accordion.tsx

@@ -37,7 +37,10 @@ AccordionItem.displayName = 'AccordionItem'
 
 const AccordionTrigger = React.forwardRef<
   React.ElementRef<typeof AccordionPrimitive.Trigger>,
-  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>
+  // asChild 不對外開放:Trigger 固定渲染 children + ChevronDown 兩個子節點,傳 asChild
+  // 會讓 Radix Slot 觸發 React.Children.only runtime 錯(見 CLAUDE.md 失敗記憶索引
+  // 「asChild 分支內部仍渲染多 children」)。固定 anatomy 見 accordion.spec.md「邊界狀態」。
+  Omit<React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>, 'asChild'>
 >(({ className, children, ...props }, ref) => (
   <AccordionPrimitive.Header className="flex">
     <AccordionPrimitive.Trigger
@@ -70,7 +73,9 @@ AccordionTrigger.displayName = 'AccordionTrigger'
 
 const AccordionContent = React.forwardRef<
   React.ElementRef<typeof AccordionPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Content>
+  // asChild 不對外開放:Content 固定以內層 <div className="pb-4"> 包住 children,傳 asChild
+  // 只會讓 Slot clone 該內層 div,consumer 元素無法成為 Content host(等同無效 API)。
+  Omit<React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Content>, 'asChild'>
 >(({ className, children, ...props }, ref) => (
   <AccordionPrimitive.Content
     ref={ref}

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

@@ -41,16 +41,10 @@ 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:text-primary-hover font-medium cursor-pointer">低調單行</span></LinkTo>
+          <LinkTo kind="Design System/Components/Alert/展示" name="單行（低調 vs 實心對照）"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">單行(低調 vs 實心對照)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Alert/展示" name="實心單行"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">實心單行</span></LinkTo>
-        </li>
-        <li>
-          <LinkTo kind="Design System/Components/Alert/展示" name="低調含說明文字"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">低調含說明文字</span></LinkTo>
-        </li>
-        <li>
-          <LinkTo kind="Design System/Components/Alert/展示" name="實心含說明文字"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">實心含說明文字</span></LinkTo>
+          <LinkTo kind="Design System/Components/Alert/展示" name="含說明文字（低調 vs 實心對照）"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">含說明文字(低調 vs 實心對照)</span></LinkTo>
         </li>
         <li>
           <LinkTo kind="Design System/Components/Alert/展示" name="右上角操作群組"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">右上角操作群組</span></LinkTo>

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

@@ -34,9 +34,13 @@ export const Overview: Story = {
           sidebar={<AcmeSidebar />}
           header={<PageHeader title="Dashboard" />}
           aside={
-            <AppShellAside title="Detail panel" width={320}>
-              <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]">
-                <p className="text-body">Aside 內容(留白由使用此面板的內容自行管理)</p>
+            <AppShellAside title="訂單詳情" width={320}>
+              {/* 面板內容自帶留白(px/py),示範 aside slot 不強制內距、由內容自管 */}
+              <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] space-y-3 text-body">
+                <div className="flex justify-between"><span className="text-fg-muted">訂單編號</span><span className="font-medium">#SO-20481</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">客戶</span><span className="font-medium">陳怡君</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">付款狀態</span><span className="font-medium">已付款</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">金額</span><span className="font-medium">NT$ 12,800</span></div>
               </div>
             </AppShellAside>
           }
@@ -107,26 +111,28 @@ export const StateBehavior: Story = {
           header={
             <ChromeHeader className="bg-surface">
               <SidebarTrigger />
-              <h1 className="text-body-lg font-medium flex-1 truncate">Toggle Aside demo</h1>
+              <h1 className="text-body-lg font-medium flex-1 truncate">訂單 #SO-20481</h1>
               <Button size="sm" variant="primary" onClick={() => setOpen(!open)}>
-                {open ? 'Close' : 'Open'} Aside (cmd+.)
+                {open ? '隱藏訂單詳情' : '顯示訂單詳情'}
               </Button>
             </ChromeHeader>
           }
           aside={
-            <AppShellAside title="Detail panel" width={320}>
-              <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]">
-                <p className="text-body">Aside 內容</p>
+            <AppShellAside title="訂單詳情" width={320}>
+              <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] space-y-3 text-body">
+                <div className="flex justify-between"><span className="text-fg-muted">訂單編號</span><span className="font-medium">#SO-20481</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">客戶</span><span className="font-medium">陳怡君</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">付款狀態</span><span className="font-medium">已付款</span></div>
               </div>
             </AppShellAside>
           }
           asideOpen={open}
           onAsideOpenChange={setOpen}
         >
-          <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] text-body">
-            <p>Aside open:{String(open)}</p>
-            <p>Desktop ≥ 768px → inline standard mode(右側 panel,不蓋 mask)</p>
-            <p>Mobile &lt; 768px → modal mode(Sheet from right,蓋 mask)</p>
+          <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] text-body space-y-1">
+            <p>訂單詳情面板目前:{open ? '已展開' : '已收合'}(⌘. / Ctrl+. 可切換)</p>
+            <p className="text-fg-secondary">桌面 ≥ 768px:面板從右側並排展開,不蓋遮罩</p>
+            <p className="text-fg-secondary">行動裝置 &lt; 768px:面板以 Sheet 從右側滑出,蓋半透明遮罩</p>
           </div>
         </AppShell>
       </SidebarProvider>
@@ -154,7 +160,7 @@ export const Accessibility: Story = {
         <li><strong>Skip to main</strong>:`Tab` 第一站 focus skip-link → jump 到 `#app-shell-main`(WCAG 2.4.1)</li>
         <li><strong>Keyboard shortcuts</strong>:`⌘B` / `Ctrl+B` toggle sidebar(消費 Sidebar SSOT)/ `⌘.` / `Ctrl+.` toggle aside</li>
         <li><strong>Modal Aside title</strong>:title 是必填 prop → 行動裝置上以 Sheet 形式開啟時,自動連結 `aria-labelledby`,讓螢幕報讀器讀得到面板名稱</li>
-        <li><strong>Focus trap</strong>:Sheet open 時 focus 在 Aside 內,Esc 關回 trigger(Radix Dialog 內建)</li>
+        <li><strong>Focus trap</strong>:Sheet open 時 focus 在 Aside 內;Esc 關閉後回焦 opener——controlled Sheet 無 SheetTrigger,Radix 內建回焦失效,由 AppShellAside 自建 opener snapshot + onCloseAutoFocus 手動還原(app-shell.tsx,2026-07-14)</li>
       </ul>
     </div>
   ),

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` 慣例)。