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

package/ds-canonical/skills/product-ui-audit/SKILL.md

@@ -87,13 +87,13 @@ Purpose: design-system-audit audits the **DS itself**(spec / cva / SSOT 三方
 
 ### Dim 4 — Mindset adherence
 
-對齊 CLAUDE.md 5 條 mindset:
+對齊 CLAUDE.md 6 條 mindset(逐條檢查 #1-#5;#6「大原則吸收瑣碎」屬 governance meta 層,不在 consumer code audit scope。編號用 mindset #N,避免撞 meta-patterns M-rules 編號):
 
-- **M1 對標世界級**:新 pattern 有對標備註? 或找得到對應既有元件?
-- **M2 不憑直覺發明**:新數值(gap / padding / font-size)前有 grep 既有?
-- **M3 改一處看三處**:若改 DS 的 cva defaultVariants,spec / docblock / anatomy 三方同步?
-- **M4 真實業務場景**:stories / examples 用真實場景 (Jira / Stripe / Notion...)?無 `Option A/B/C` / `按鈕一` / `Rule A`?
-- **M5 猶豫就問**:code 裡有 TODO-未確認留白?
+- **mindset #1 對標世界級**:新 pattern 有對標備註? 或找得到對應既有元件?
+- **mindset #2 不憑直覺發明**:新數值(gap / padding / font-size)前有 grep 既有?
+- **mindset #3 改一處看三處**:若改 DS 的 cva defaultVariants,spec / docblock / anatomy 三方同步?
+- **mindset #4 真實業務場景**:stories / examples 用真實場景 (Jira / Stripe / Notion...)?無 `Option A/B/C` / `按鈕一` / `Rule A`?
+- **mindset #5 猶豫就問**:code 裡有 TODO-未確認留白?
 
 ### Dim 5 — 視覺幾何(Mindset #1 視覺擴充 + .claude/references/ui-dev-rules.md「同 flex 列互動 slot 幾何鐵律」)
 
@@ -131,7 +131,7 @@ chain `.claude/skills/design-system-audit/references/principle-audit-protocol.md
 
 確認 audit target:file / folder / feature area。提問 user 若模糊。禁止掃整個 repo(失焦)。
 
-### Phase 1 — Parallel 6-dim audit
+### Phase 1 — Parallel 7-Dimension audit
 
 7 個維度各自獨立 grep + code review。可 parallelize。
 

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.87。
 
 # 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.87。
 
 本檔由 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.87",
   "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>
   ),