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

package/src/components/Sheet/sheet.spec.md

@@ -48,11 +48,11 @@ Sheet 是**從畫面邊緣滑入的浮層面板**。**消費者 API = 右側滑
 
 | | Sheet | Dialog |
 |---|---|---|
-| 位置 | 畫面邊緣滑入（上/下/左/右） | 畫面居中 |
+| 位置 | 畫面右側滑入（消費者 API 僅 `side="right"`;top/bottom/left 為 DS 內部基建） | 畫面居中 |
 | 視覺重量 | 較輕（單邊） | 較重（四周 overlay） |
 | 典型用途 | 側邊工作流程、detail panel | 確認流程、複雜表單 |
 | 阻斷感 | 較弱（使用者視線可繼續掃主頁） | 強（完全聚焦 modal） |
-| 手機體驗 | 自然（從底部 / 全螢幕滑入符合 mobile pattern） | 桌機導向（中央 modal 不符 mobile sheet pattern，浮層遮住主流向） |
+| 手機體驗 | 沿用同一右側 Sheet（mobile 預設占 75% 寬;不借 `side="bottom"`，見「何時用」） | 桌機導向（中央 modal 不符 mobile sheet pattern，浮層遮住主流向） |
 
 **判準**：
 - **需要聚焦決策（刪除、確認、複雜表單）→ Dialog**
@@ -70,7 +70,7 @@ Sheet 是**從畫面邊緣滑入的浮層面板**。**消費者 API = 右側滑
 
 ## Padding SSOT
 
-Sheet 的 `SheetHeader` / `SheetBody` / `SheetFooter` 對應 `SurfaceHeader` / `SurfaceBody` / `SurfaceFooter` primitive——padding + 分隔線由 `patterns/overlay-surface/overlay-surface.spec.md` own,Sheet 與 Dialog / Popover 共用同一套 primitive,避免 token 漂移。Sheet 特有行為:side variant(`top` / `right` / `bottom` / `left`)決定滑入方向 + height/width 響應式策略,padding 本身對齊 overlay-surface canonical。
+Sheet 的 `SheetHeader` / `SheetFooter` 消費 `SurfaceHeader` / `SurfaceFooter` primitive;`SheetBody` 用 `<ScrollArea>` wrap + 同一套 overlay-surface padding token(對齊 DialogBody canonical,SSOT 見 `patterns/overlay-surface/overlay-surface.spec.md`「Body overflow canonical」)——padding + 分隔線由 overlay-surface own,Sheet 與 Dialog / Popover 共用,避免 token 漂移。Sheet 特有行為:side variant(`top` / `right` / `bottom` / `left`)決定滑入方向 + height/width 響應式策略,padding 本身對齊 overlay-surface canonical。
 
 ---
 
@@ -104,8 +104,11 @@ Sheet 為容器,內容由 consumer 決定;focus trap + Escape close + `aria-labe
 ## 邊界案例
 
 - **Disabled**:Sheet 本身無 disabled state(非互動 control,是 surface container);trigger Button 由 consumer 控 disabled。
-- **Loading(panel content loading)**:Sheet 為純容器,不獨立 own loading state。Async body 場景由 consumer 在 body slot 渲 `<Empty icon={<CircularProgress size={48}/>}/>`(對齊 `empty.spec.md:182` 全頁 loading SSOT)或 `<Skeleton>` line-stack 取代 content,不開 / 不關 Sheet 即可。
+- **Loading(panel content loading)**:Sheet 為純容器,不獨立 own loading state。Async body 場景由 consumer 在 body slot 渲 `<Empty icon={<CircularProgress size={48}/>}/>`(對齊 `empty.spec.md:168` loading compose SSOT)或 `<Skeleton>` line-stack 取代 content,不開 / 不關 Sheet 即可。
 - **Empty(no content)**:Sheet 必含 title(`aria-labelledby` 強制要求);body 為空時 consumer 應渲 `<Empty>` placeholder,不渲空白 panel。
+- **Scroll(body 內容超過視口高度)**:`SheetBody` = `<ScrollArea>`(`flex-1 min-h-0`),超高內容在 body 內部捲動,header / footer 固定不動;consumer 不需自寫 `overflow-y-auto`。
+- **誤嵌套降級(nested Sheet)**:禁止事項已禁 nested;若 consumer 不慎嵌套,Radix 的 Esc 與 focus trap 只作用於**最上層** layer(DismissableLayer 只 dismiss highest layer;FocusScope stack 最新 scope active),關閉由上而下逐層。
+- **RTL**:`side` 為物理方向(`right-0` 物理定位),不隨 `dir="rtl"` 自動鏡像。
 - **Dark mode**:overlay-surface SSOT 自動 adapt(`overlay-surface.spec.md`);Sheet 不獨立 own dark token。
 - **Density**:Sheet body density 由 consumer 控(若內含 form / DataTable / Menu 各自有 density 規則);Sheet container 自身不持 density。
 
@@ -137,12 +140,7 @@ Sheet 為容器,內容由 consumer 決定;focus trap + Escape close + `aria-labe
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
-- `app-shell.spec.md`
-- `density.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `accordion.spec.md`
+- `app-shell.spec.md`
+- `dialog.spec.md`
 - `scroll-area.spec.md`

package/src/components/Sheet/sheet.stories.tsx

@@ -25,7 +25,7 @@ export default meta
 type Story = StoryObj
 
 export const CreateProjectRight: Story = {
-  name: '右側建立 專案',
+  name: '建立新專案（右側滑入）',
   render: () => (
     <Sheet>
       <SheetTrigger asChild>
@@ -73,7 +73,7 @@ export const CreateProjectRight: Story = {
 }
 
 export const EditUserRight: Story = {
-  name: '右側編輯 使用者 詳情',
+  name: '編輯成員詳情（右側滑入）',
   render: () => (
     <Sheet>
       <SheetTrigger asChild>

package/src/components/Sheet/sheet.tsx

@@ -18,9 +18,9 @@ import { ScrollArea } from "@/design-system/components/ScrollArea/scroll-area"
  *
  * ── 定位(2026-04-21 canonical)──
  * Sheet 給**消費者**用的唯一合法形式 = **右側開啟的 modal**(side="right"),
- * 內部結構跟 `Dialog` 一致:`SheetHeader` / `SheetBody` / `SheetFooter`(各自消費
- * `SurfaceHeader` / `SurfaceBody` / `SurfaceFooter` primitive,padding token SSOT
- * 在 `patterns/overlay-surface/`)。side="right" 是 defaultVariants,消費者不傳 side。
+ * 內部結構跟 `Dialog` 一致:`SheetHeader` / `SheetBody` / `SheetFooter`(Header / Footer 消費
+ * `SurfaceHeader` / `SurfaceFooter` primitive;Body = `ScrollArea` + 內層 padding div,
+ * padding token SSOT 在 `patterns/overlay-surface/`)。side="right" 是 defaultVariants,消費者不傳 side。
  *
  * ── 其他 side(top / bottom / left)——**非消費者 API**,內部基建用 ──
  * top / bottom / left 變體保留給 DS 內部基建(例:Sidebar 在小尺寸視口時從 left 滑入)。
@@ -31,9 +31,10 @@ import { ScrollArea } from "@/design-system/components/ScrollArea/scroll-area"
  * - Sheet(side="right")= 側滑 modal,用於「補充資訊 / 多欄位表單 / 編輯 flow」
  * - 兩者 API 結構 1:1 對應,差異只在 side / 動畫 / 初始寬度
  *
- * ── Header / Body / Footer 消費 SurfaceXxx SSOT ──
+ * ── Header / Footer 消費 SurfaceXxx SSOT;Body 走 ScrollArea canonical ──
  * 避免 padding 漂移 — Dialog / Popover / Sheet / Coachmark 共用同一套 overlay-surface
- * padding token(px-loose / py-tight),改 overlay-surface.tsx 四者自動跟進。
+ * padding token(px-loose / py-tight),改 overlay-surface.tsx 四者自動跟進;
+ * SheetBody 同 DialogBody:ScrollArea + 內層 px-loose / pt-tight / pb-bottom(詳 SheetBody comment)。
  */
 
 const Sheet = SheetPrimitive.Root

package/src/components/Sidebar/sidebar.anatomy.stories.tsx

@@ -1,7 +1,7 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 import * as React from 'react'
 import type { Meta, StoryObj } from '@storybook/react'
-import { LayoutDashboard, Inbox, Users, Settings, Bell } from 'lucide-react'
+import { LayoutDashboard, Inbox, Users, Settings, Bell, Folder, Plus } from 'lucide-react'
 import {
   SidebarProvider,
   SidebarHeader,
@@ -155,7 +155,7 @@ export const Overview: Story = {
           <pre className="text-caption font-mono text-fg-secondary bg-canvas p-4 rounded-md border border-divider leading-relaxed">{`SidebarProvider
   Sidebar
     SidebarHeader          ← h-[var(--chrome-header-height)]
-    SidebarContent         ← flex-1 overflow-auto
+    SidebarContent         ← flex-1 + ScrollArea 捲動
       SidebarGroup         ← py-2 + ::before divider
         SidebarGroupLabel  ← item-layout row (header mode)
         SidebarGroupContent
@@ -535,44 +535,53 @@ const CollapsedFrame = ({
 // SidebarMenuButton cva 有 variant: { default, meta } 兩個值,本 story 展示 default vs meta 區別
 export const VariantMatrix: Story = {
   name: '變體對照（預設 vs 次要）',
+  // 2026-06-11:改用真 SidebarMenuButton 渲染(原為手繪灰塊 mock row,違 production-grade composition fidelity)
   render: () => (
     <div className="flex flex-col gap-6 max-w-md">
       <div className="flex flex-col gap-2">
         <H3>variant=&quot;default&quot;(導覽 item)</H3>
-        <Desc>正常導覽目的地。文字 `text-fg-secondary` + `font-medium`,參與 single-selection,可 active。</Desc>
-        <div className="border border-border rounded-md p-3 bg-surface flex flex-col gap-1">
-          <div className="flex items-center h-8 px-2 gap-2 rounded-md" style={{ color: 'var(--fg-secondary)' }}>
-            <div className="w-4 h-4 rounded bg-current opacity-40 shrink-0" />
-            <span className="text-caption font-medium">Mobile App</span>
-          </div>
-          <div className="flex items-center h-8 px-2 gap-2 rounded-md" style={{ color: 'var(--fg-secondary)' }}>
-            <div className="w-4 h-4 rounded bg-current opacity-40 shrink-0" />
-            <span className="text-caption font-medium">Design System</span>
-          </div>
+        <Desc>正常導覽目的地。文字 <code>text-fg-secondary</code> + <code>font-medium</code>,參與 single-selection,可 active。</Desc>
+        <div className="border border-border rounded-md p-3 bg-surface">
+          <SidebarProvider defaultActiveId="dashboard" style={{ minHeight: 'auto' }}>
+            <div className="flex flex-col w-full">
+              <SidebarMenu>
+                <SidebarMenuItem>
+                  <SidebarMenuButton id="dashboard" startIcon={LayoutDashboard}>Dashboard</SidebarMenuButton>
+                </SidebarMenuItem>
+                <SidebarMenuItem>
+                  <SidebarMenuButton id="inbox" startIcon={Inbox}>Inbox</SidebarMenuButton>
+                </SidebarMenuItem>
+              </SidebarMenu>
+            </div>
+          </SidebarProvider>
         </div>
       </div>
 
       <div className="flex flex-col gap-2">
         <H3>variant=&quot;meta&quot;(命令 row,非導覽目的地)</H3>
         <Desc>
-          section 底部的命令(「查看更多 / 載入更多 / + 新增專案」)。文字退到 `text-fg-muted` + `font-normal`,
-          視覺重量下沉。**不參與 single-selection**(誤傳 isActive 也不啟動)。對齊 Linear「Show N more」/ Notion「Show more」/ Slack「Show more」/ Gmail Labels「More」共識。
+          section 底部的命令(「查看更多 / 載入更多 / + 新增專案」)。文字退到 <code>text-fg-muted</code> + <code>font-normal</code>,
+          視覺重量下沉。<strong>不參與 single-selection</strong>(誤傳 isActive 也不啟動)。對齊 Linear「Show N more」/ Notion「Show more」/ Slack「Show more」/ Gmail Labels「More」共識。
         </Desc>
-        <div className="border border-border rounded-md p-3 bg-surface flex flex-col gap-1">
-          <div className="flex items-center h-8 px-2 gap-2 rounded-md" style={{ color: 'var(--fg-secondary)' }}>
-            <div className="w-4 h-4 rounded bg-current opacity-40 shrink-0" />
-            <span className="text-caption font-medium">Checkout Revamp</span>
-          </div>
-          <div className="flex items-center h-8 px-2 gap-2 rounded-md" style={{ color: 'var(--fg-secondary)' }}>
-            <div className="w-4 h-4 rounded bg-current opacity-40 shrink-0" />
-            <span className="text-caption font-medium">Billing Migration</span>
-          </div>
-          <div className="flex items-center h-8 px-2 gap-2 rounded-md" style={{ color: 'var(--fg-muted)' }}>
-            <span className="text-caption font-normal">+ 新增專案</span>
-          </div>
-          <div className="flex items-center h-8 px-2 gap-2 rounded-md" style={{ color: 'var(--fg-muted)' }}>
-            <span className="text-caption font-normal">查看更多</span>
-          </div>
+        <div className="border border-border rounded-md p-3 bg-surface">
+          <SidebarProvider style={{ minHeight: 'auto' }}>
+            <div className="flex flex-col w-full">
+              <SidebarMenu>
+                <SidebarMenuItem>
+                  <SidebarMenuButton id="checkout" startIcon={Folder}>Checkout Revamp</SidebarMenuButton>
+                </SidebarMenuItem>
+                <SidebarMenuItem>
+                  <SidebarMenuButton id="billing" startIcon={Folder}>Billing Migration</SidebarMenuButton>
+                </SidebarMenuItem>
+                <SidebarMenuItem>
+                  <SidebarMenuButton variant="meta" startIcon={Plus}>新增專案</SidebarMenuButton>
+                </SidebarMenuItem>
+                <SidebarMenuItem>
+                  <SidebarMenuButton variant="meta">查看更多</SidebarMenuButton>
+                </SidebarMenuItem>
+              </SidebarMenu>
+            </div>
+          </SidebarProvider>
         </div>
       </div>
     </div>
@@ -586,7 +595,7 @@ export const StateBehavior: Story = {
       <div className="flex flex-col gap-1">
         <H3>狀態行為</H3>
         <Desc>
-          Sidebar 層級特有的狀態:collapse / expand 三種模式、mobile offcanvas、active item 跨 session 還原。
+          Sidebar 層級特有的狀態:collapse / expand 三種模式、mobile offcanvas、active item single-selection、open state cookie 持久化。
           Item-level default / hover / active / selected / disabled **色彩**由 `ColorMatrix` 作為 state-driven 矩陣完整呈現(共用 item-anatomy row primitive 主檔);本 story 展示 container 層的結構狀態切換。
         </Desc>
       </div>
@@ -608,7 +617,7 @@ export const StateBehavior: Story = {
       <div className="flex flex-col gap-3">
         <span className="text-caption font-medium text-fg-secondary">行為 2:Cmd+B / SidebarTrigger 切換 open state</span>
         <Desc>
-          SidebarProvider 內建 Cmd+B (Mac) / Ctrl+B (Win) 全域快捷鍵,同時 SidebarTrigger iconOnly Button 作為視覺 toggle。open state 寫入 cookie(7 天),跨 session 還原。
+          SidebarProvider 內建 Cmd+B (Mac) / Ctrl+B (Win) 全域快捷鍵,同時 SidebarTrigger iconOnly Button 作為視覺 toggle。open state 寫入 cookie(7 天);跨 session 還原需 consumer 讀 cookie 後傳 defaultOpen(詳 spec「持久化與快捷鍵」)。
         </Desc>
         <div className="border border-divider rounded-lg overflow-hidden bg-surface" style={{ width: 480, height: 280 }}>
           <SidebarProvider style={{ minHeight: 'auto', height: '100%' }}>
@@ -668,7 +677,7 @@ export const StateBehavior: Story = {
         <span className="text-caption font-medium text-fg-secondary">行為規則</span>
         <ul className="text-caption text-fg-secondary space-y-1.5 ml-4 list-disc">
           <li>`collapsible="offcanvas"` 用於主內容為主的 app(sidebar 是啟動器,使用者常關);`collapsible="icon"` 用於深度導覽 app(sidebar 是常駐工作區)。</li>
-          <li>open state 寫 cookie `sidebar_state`(7 天 max-age),跨 session 還原——使用者上次關 = 下次也關。</li>
+          <li>open state 寫 cookie `sidebar_state`(7 天 max-age);Provider 只寫不讀,還原由 consumer 讀 cookie 傳 `defaultOpen`(避免 SSR hydration flash)。</li>
           <li>Mobile(&lt;768px)一律走 Sheet overlay,不受 `collapsible` prop 影響——小螢幕 sidebar 永遠不佔固定空間。</li>
           <li>Icon mode 下 active item 的 `bg-neutral-selected` 仍然顯示,但 label 不可見——提供最小視覺指引讓使用者知道「當前在哪」。</li>
           <li>Cmd+B / Ctrl+B 全域快捷鍵由 SidebarProvider 監聽,任何 focus 位置都可觸發——目前未排除文字輸入框,在 input / textarea 內按下仍會 toggle 並攔掉預設行為(無 disableShortcut opt-out)。</li>
@@ -757,7 +766,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"-   收合切換鍵：Cmd+B(Mac)/ Ctrl+B(Windows)是業界慣例(VS Code / Linear / shadcn 都用),Sidebar 內建並會攔下這組鍵,避免穿透到瀏覽器書籤列。任何焦點位置都能觸發;目前未排除文字輸入框——在 input / textarea 內按下仍會 toggle(無 disableShortcut opt-out)。\n\n-   收合按鈕:SidebarTrigger 帶 aria-label「展開或收合」,讓螢幕報讀使用者知道按鈕用途;consumer 可用 toggleAriaLabel 自訂文字。\n\n-   當前項目:選中的 menu item 帶 data-active,呈現選取底色(bg-neutral-selected)作為視覺指引;即使收合成 icon-only 模式,選取底色仍然保留,使用者一眼知道現在在哪一頁。\n\n-   手機尺寸:768px 以下自動切換成從旁滑出的抽屜(Sheet),內建焦點鎖定、Esc 關閉、關閉後焦點回到觸發按鈕。"}</p>
+      <p className="whitespace-pre-line">{"-   收合切換鍵：Cmd+B(Mac)/ Ctrl+B(Windows)是業界慣例(VS Code / Linear / shadcn 都用),Sidebar 內建並會攔下這組鍵,避免穿透到瀏覽器書籤列。任何焦點位置都能觸發;目前未排除文字輸入框——在 input / textarea 內按下仍會 toggle(無 disableShortcut opt-out)。\n\n-   收合按鈕:SidebarTrigger 內建 aria-label「Toggle Sidebar」,讓螢幕報讀使用者知道按鈕用途;consumer 可傳 aria-label 覆寫(i18n)。SidebarGroupLabel 的收合 chevron 另有 toggleAriaLabel prop(預設「展開或收合」)。\n\n-   當前項目:選中的 menu item 帶 data-active,呈現選取底色(bg-neutral-selected)作為視覺指引;即使收合成 icon-only 模式,選取底色仍然保留,使用者一眼知道現在在哪一頁。\n\n-   手機尺寸:768px 以下自動切換成從旁滑出的抽屜(Sheet),內建焦點鎖定、Esc 關閉、關閉後焦點回到觸發按鈕。"}</p>
     </div>
   ),
 }

package/src/components/Sidebar/sidebar.principles.stories.tsx

@@ -144,16 +144,16 @@ export const UsageGuidance: Story = {
       <p>適合 Sidebar 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/Sidebar/展示" name="完整佈局"><span className="text-primary hover:underline font-medium cursor-pointer">完整佈局</span></LinkTo>
+          <LinkTo kind="Design System/Components/Sidebar/展示" name="完整佈局"><span className="text-primary hover:underline font-medium cursor-pointer">Linear 式議題追蹤主導覽(完整佈局)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Sidebar/展示" name="混合內容"><span className="text-primary hover:underline font-medium cursor-pointer">混合內容</span></LinkTo>
+          <LinkTo kind="Design System/Components/Sidebar/展示" name="混合內容"><span className="text-primary hover:underline font-medium cursor-pointer">專案導覽混排群組、徽章與操作(混合內容)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Sidebar/展示" name="抽屜收合（離畫面外）"><span className="text-primary hover:underline font-medium cursor-pointer">抽屜收合（離畫面外）</span></LinkTo>
+          <LinkTo kind="Design System/Components/Sidebar/展示" name="抽屜收合（離畫面外）"><span className="text-primary hover:underline font-medium cursor-pointer">側欄整條滑出畫面外的內容優先工作區（抽屜收合）</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Sidebar/展示" name="混合前綴"><span className="text-primary hover:underline font-medium cursor-pointer">混合前綴</span></LinkTo>
+          <LinkTo kind="Design System/Components/Sidebar/展示" name="混合前綴"><span className="text-primary hover:underline font-medium cursor-pointer">icon 導覽與 GitHub / Slack / Figma 整合並列對齊（混合前綴）</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:對照下方「何時不用 / 替代元件」清單;若情境不屬於垂直持久導覽,改用對應的近親元件。</p>

package/src/components/Sidebar/sidebar.spec.md

@@ -37,7 +37,7 @@ benchmark:
 # Sidebar 設計原則
 
 > **Foundational SSOT rationale**(2026-04-24 approved,cap 800):
-> Sidebar 有獨立 `sidebarMenuButtonVariants` cva(對齊 MenuItem 但獨立實作,同步風險見 item-anatomy.spec「SidebarMenuButton 獨立實作風險」)+ 20+ Sidebar-specific features SSOT(Chrome header/footer 高度 / Collapsible / Icon 模式 / SidebarTrigger 位置 / Mobile 行為 / 持久化 / 快捷鍵 / Group 收合 / Single selection / Inline actions / Keyboard shortcuts),scope > 單一 MenuItem consumer。Long-term 考慮 refactor 消費 menuItemVariants base(詳 `.claude/planning/row-primitive-consolidation.md`)— 若 refactor 成功,本 spec 可縮到 ~300。
+> Sidebar 有獨立 `sidebarMenuButtonVariants` cva(對齊 MenuItem 但獨立實作,同步風險見 item-anatomy.spec「SidebarMenuButton 獨立實作風險」)+ 20+ Sidebar-specific features SSOT(Chrome header/footer 高度 / Collapsible / Icon 模式 / SidebarTrigger 位置 / Mobile 行為 / 持久化 / 快捷鍵 / Group 收合 / Single selection / Inline actions / Keyboard shortcuts),scope > 單一 MenuItem consumer。Full cva consume 提案經二次評估 declined(2026-04-24,詳 `.claude/planning/row-primitive-consolidation.md.rejected.20260424.md`)— ROW_PADDING_BY_SIZE token SSOT 已是 practical best。
 
 ## 定位
 
@@ -89,7 +89,7 @@ SidebarProvider              ← 全域 context（open 狀態、cookie、快捷
           │
           └─ TreeView              階層樹（user data、任意深度）
     SidebarFooter            ← 底部：user menu、settings 觸發器
-  SidebarTrigger             ← 展開 / 收合按鈕（可放 sidebar 內或外）
+  SidebarTrigger             ← 展開 / 收合按鈕（放 sidebar 外，詳「SidebarTrigger 位置」段）
 ```
 
 **不使用 shadcn 原版的 `SidebarMenuSub` / `SidebarMenuSubItem`**——見下方內容形態規則。
@@ -239,7 +239,7 @@ Gmail / Linear 的標準版型：上方 SidebarGroup 放扁平主導覽（Sideba
 
 放在 SidebarHeader / SidebarFooter 裡的元件必須能容納在這個高度內：
 
-- Avatar: `size={24}` —— **chrome header avatar canonical（density-fixed / row-size-fixed）**。consumer 用 **raw `<Avatar size={24}>`**（chrome header 不是 row context → 不該用 `<ItemAvatar>`）。對應 CSS local token `--chrome-header-avatar-size: 1.5rem`（`header-canonical.css`），sidebar 收合對齊公式消費此 token。詳 `header-canonical.spec.md`「4.5 Chrome header avatar SSOT」段 + `item-anatomy.spec.md:535` scope 限定段。
+- Avatar: `size={24}` —— **chrome header avatar canonical（density-fixed / row-size-fixed）**。consumer 用 **raw `<Avatar size={24}>`**（chrome header 不是 row context → 不該用 `<ItemAvatar>`）。對應 CSS local token `--chrome-header-avatar-size: 1.5rem`（`header-canonical.css`），sidebar 收合對齊公式消費此 token。詳 `header-canonical.spec.md`「4.5 Chrome header avatar SSOT」段 + `item-anatomy.spec.md`「Scope 例外:Chrome header 不是 row context」段。
 - Button: `size="sm"` 或 `size="md"`
 - 單排 title 文字 + icon button
 
@@ -543,7 +543,7 @@ Consumer 不需要任何額外 code——只要加一個 prop:
 
 `<SidebarMenuButton inlineActions={[...]}>` 支援 suffix 放置 inline action button,搭配 `actionsReveal="hover"` 做 TreeView 風格的 hover-reveal。
 
-**宣告式 API**,完全對齊 `uiSize.spec.md`「Inline Action」節:
+**宣告式 API**,完全對齊 `patterns/element-anatomy/inline-action.spec.md`(Inline Action SSOT):
 
 ```tsx
 <SidebarMenuButton
@@ -565,20 +565,20 @@ Consumer 不需要任何額外 code——只要加一個 prop:
 - 處理 Tooltip / `aria-label` / `cursor-pointer`(宣告式 config 自動帶)
 - 計算 button 的 `paddingRight`(host 用 `N×icon + (N-1)×gap + loose + gap` 公式自動算)
 
-**規格**(完全繼承 uiSize.spec.md):
+**規格**(完全繼承 `inline-action.spec.md`):
 
 | 項目 | 值 |
 |---|---|
 | Icon 尺寸 | `ICON_SIZE[size]`(16/16/20) |
 | Hover bg 尺寸 | icon + 2(18/18/22) |
-| Hover bg 圓角 | `rounded-md` (sm/md) / `rounded-md` (lg) |
+| Hover bg 圓角 | `rounded-md`(全尺寸一致) |
 | Icon 顏色 | `fg-muted` → `foreground` on hover/active |
 | 多個 action 間距 | `gap-2`(8px) |
 | 出現時機 | 預設永遠顯示;`actionsReveal="hover"` → row hover/focus 才淡入 |
 | Icon 模式 | 整個 suffix 隱藏 |
 | Host disabled 時 | 不渲染(遵守宿主 disabled 規則) |
 
-**Canonical 實作**:`ItemInlineAction` + `ItemSuffix`(`item-layout.tsx`)。未來 DropdownMenuItem / TreeItem / Field / Tag 都應逐步遷移到這個共用元件,消除「每個 host 各自複製 18 行 JSX」的技術債——見 `item-anatomy.spec.md` 底部「Inline action 共用元件」節。
+**Canonical 實作**:`ItemInlineAction` + `ItemSuffix`(`item-anatomy.tsx`)。未來 DropdownMenuItem / TreeItem / Field / Tag 都應逐步遷移到這個共用元件,消除「每個 host 各自複製 18 行 JSX」的技術債——見 `inline-action.spec.md`(Inline Action SSOT)。
 
 **何時用**:
 - ✅ Favorites / Bookmarks 類 user data item 的 hover-reveal 「⋯」/「×」
@@ -618,6 +618,14 @@ Sheet 開啟狀態**不持久化**。
 
 ---
 
+## 常見誤解
+
+- 「SidebarMenuSub 可做第 2 層選單」——本 DS 不 export;深度 > 1 一律 TreeView(見「內容形態選擇」)
+- 「Settings 子頁要佔 sidebar 位置」——走 in-page secondary nav / user menu modal(見「Settings 這類有子頁的頁面」)
+- 「點 icon 可順便展開 sidebar」——行為不可預測;重新看階層資料的唯一路徑 = 展開 sidebar(見「Icon 模式的行為規則」)
+
+---
+
 ## 禁止事項
 
 - ❌ **使用 SidebarMenuSub / 讓 SidebarMenu 超過 1 層**——用 TreeView 或 in-page secondary nav
@@ -644,7 +652,7 @@ Sheet 開啟狀態**不持久化**。
 ## 判斷決策樹
 
 ```
-Variant：傳統工具型 → sidebar；現代 SaaS 卡片化 → inset；浮動面板 → floating
+Variant：目前僅 sidebar（floating 刻意不做 / inset 規劃中未實作，見「Variant」段）
 
 Collapsible：內容優先低頻導覽 → offcanvas；扁平高頻切換 → icon；超簡單 → none
 
@@ -681,11 +689,11 @@ Item-level default / hover / selected / disabled **色彩**完全共用 item-ana
 
 ## 邊界案例
 
-- **Disabled item**:SidebarMenuButton 走 MenuItem primitive SSOT(`disabled` prop → `text-fg-disabled` + `aria-disabled=true` + 不觸發 onClick + 鍵盤導覽自動 skip)。
+- **Disabled item**:SidebarMenuButton `disabled` prop 走 native button disabled(`text-fg-disabled` + 不觸發 onClick + 不可聚焦,鍵盤導覽自動 skip);**不自動設 `aria-disabled`**——cva 另備 `aria-disabled:` 樣式,consumer 自傳 `aria-disabled`(如 asChild 非 button host)時同樣式生效。
 - **Loading(nav data-fetch)**:async nav tree fetch 時 consumer 應在對應 group 內渲 `<Skeleton>` line-stack(常見 3-5 條 sidebar nav skeleton 行)而非 Empty + spinner — Sidebar 是 chrome 不是 panel,loading 用 skeleton 更符合 chrome 持續存在的 affordance。對齊 Atlassian Sidebar / VS Code activity-bar idiom。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **Empty(no nav items)**:罕見場景(用戶無權限 / 全空 workspace)。若整個 group 無 item,consumer 應 conditional 不渲該 group(不渲空 group label);若整個 sidebar 無 item,可能該 hide sidebar(走 layout context 不渲)。不渲空白 sidebar。
 - **Dark mode / density**:Sidebar 為 chrome surface,走 chrome-header token 自動 adapt;density 預設 lock 跟隨 app density chrome token,不獨立 own。
-- **Collapsed mode(icon-only)**:已 codify(見 Sidebar collapsed mode 段);此時 label / endAction 隱藏,只留 icon + tooltip。
+- **Collapsed mode(icon-only)**:label / inline actions suffix 隱藏,只留 icon + tooltip;TreeView 整區隱藏,重新看階層資料的唯一路徑 = 展開 sidebar(完整規則見「Icon 模式的行為規則」段)。
 
 ---
 
@@ -695,17 +703,14 @@ Item-level default / hover / selected / disabled **色彩**完全共用 item-ana
 - `../DropdownMenu/dropdown-menu.spec.md` — Header / Footer 常用的下拉選單
 - `../Tabs/tabs.spec.md` — in-page secondary nav（不塞 sidebar 的子頁切換）
 - `../Menu/menu-item.spec.md` — SidebarMenuButton 的 item-layout 共用規則
-- Command palette（`components/Command/`，shadcn passthrough 無 spec）— icon 模式下的跳轉逃生艙
-- Sheet（`components/Sheet/`，shadcn passthrough 無 spec）— 暫時性側邊面板的替代
+- `../Command/command.spec.md` — Command palette，icon 模式下的跳轉逃生艙
+- `../Sheet/sheet.spec.md` — Sheet，暫時性側邊面板的替代（mobile 模式實作基礎，詳「A11y 預設」）
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `app-shell.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `scroll-area.spec.md`
+- `sheet.spec.md`
+- `tree-view.spec.md`

package/src/components/Sidebar/sidebar.stories.tsx

@@ -324,6 +324,22 @@ export const MixedContent: Story = {
                       </SidebarMenuButton>
                     </SidebarMenuItem>
                   ))}
+                  {/* Disabled favorite(已封存專案):host disabled 時 inline actions
+                      整組不渲染——hover 也不出現 ⋯/＋,不可操作就不暗示可操作
+                      (sidebar.spec.md「Host disabled 時」+ inline-action.spec.md 宿主 disabled 規則)。 */}
+                  <SidebarMenuItem>
+                    <SidebarMenuButton
+                      startIcon={Folder}
+                      disabled
+                      actionsReveal="hover"
+                      inlineActions={[
+                        { icon: MoreVertical, label: '更多動作', onClick: () => {} },
+                        { icon: Plus, label: '新增', onClick: () => {} },
+                      ]}
+                    >
+                      delta（已封存）
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
                 </SidebarMenu>
               </SidebarGroupContent>
             </SidebarGroup>

package/src/components/Sidebar/sidebar.tsx

@@ -257,7 +257,7 @@ const SidebarProvider = React.forwardRef<
             style={wrapperStyle}
             className={cn(
               "group/sidebar-wrapper flex min-h-svh w-full",
-              // CSS :has() 偵測 — 只在 uniformPrefix=true(預設)時掛
+              // CSS :has() 偵測 — 只在 uniformPrefix=true(opt-in,預設 false;見 sidebar.spec.md「Sidebar 全域 prefix 對齊」)時掛
               // mixing detected → 同時把 --item-icon-size cascade 到 slot 寬(`!` important 蓋
               // 過 wrapperStyle inline,讓 collapsed pl 公式知道「ItemPrefix wrapper 被撐到
               // 24,effective prefix width = 24 非 16」)。
@@ -731,7 +731,7 @@ const SidebarGroupLabel = React.forwardRef<
 
   // Collapsible group:label 本身仍是 plain header(保留原本語意),
   // chevron 是 suffix slot 裡的 inline action button,用 Radix Collapsible.Trigger asChild
-  // 包住 `ItemInlineActionButton`——視覺規格完全對齊 uiSize.spec.md「Inline Action」,
+  // 包住 `ItemInlineActionButton`——視覺規格完全對齊 patterns/element-anatomy/inline-action.spec.md(Inline Action SSOT),
   // 跟 SidebarMenuButton 的 suffix inline action 同一套 canonical 實作。
   //
   // **為什麼 chevron 是 inline action 而非整個 label 是 trigger**:
@@ -814,9 +814,10 @@ SidebarGroupAction.displayName = "SidebarGroupAction"
 
 // SidebarMenu — items 容器
 //
-// Prefix 對齊由 `SidebarProvider` 全域 auto-detect 處理(school B,Notion/Linear 慣例):
-// 整個 sidebar 子樹同時存在 icon 和 avatar prefix 時,自動套用固定槽,跨 menu 跨 group 對齊。
-// 若要關閉,在 `<SidebarProvider uniformPrefix={false}>` 全域控制。SidebarMenu 沒有
+// Prefix 對齊由 `SidebarProvider` 的 `uniformPrefix`(opt-in,預設 false)全域處理(school B,
+// Notion/Linear 慣例):開啟後,整個 sidebar 子樹同時存在 icon 和 avatar prefix 時,自動套用
+// 固定槽,跨 menu 跨 group 對齊。要啟用,在 `<SidebarProvider uniformPrefix>` 全域 opt-in
+// (explicit > implicit,見 sidebar.spec.md「Sidebar 全域 prefix 對齊」段)。SidebarMenu 沒有
 // per-menu 覆寫——沒有真實 use case,YAGNI。
 const SidebarMenu = React.forwardRef<
   HTMLUListElement,
@@ -958,7 +959,7 @@ const SidebarMenuButton = React.forwardRef<
     startIcon?: LucideIcon
     tooltip?: string | React.ComponentProps<typeof TooltipContent>
     /**
-     * Suffix slot 的 inline actions(宣告式 API,對齊 uiSize.spec.md「Inline Action」)。
+     * Suffix slot 的 inline actions(宣告式 API,對齊 patterns/element-anatomy/inline-action.spec.md)。
      * Host 自動用 `<ItemInlineAction>` 渲染,consumer 只宣告 intent。
      * Icon 模式下自動隱藏。
      */
@@ -1046,7 +1047,14 @@ const SidebarMenuButton = React.forwardRef<
     )
 
     const hasSlot = !!inlineActionsSlot
-    const hasActions = hasSlot || (!!inlineActions && inlineActions.length > 0)
+    // Host disabled 時 inline actions(config + slot)整段不渲染,paddingRight 預留一併取消
+    // (inline-action.spec.md「宿主 disabled 時不渲染」+ sidebar.spec.md「Host disabled 時|不渲染」)。
+    // 必須 render 層 guard:suffix 跟 button 是 sibling(避免巢狀 button),
+    // native disabled 的 pointer-events-none 蓋不到 sibling,CSS 層無從繼承。
+    // aria-disabled 同步 guard——對齊 cva `aria-disabled:` 樣式支線(asChild 非 button host 自傳)。
+    const isDisabled =
+      !!props.disabled || props["aria-disabled"] === true || props["aria-disabled"] === "true"
+    const hasActions = !isDisabled && (hasSlot || (!!inlineActions && inlineActions.length > 0))
 
     // 計算 suffix 所佔寬度:N×icon + (N-1)×gap-2(8px),再加 gap-2 跟 label 之間的間隔
     // Slot mode 預設按 1 icon 預留(consumer 寬度自控)

package/src/components/Skeleton/skeleton.anatomy.stories.tsx

@@ -4,7 +4,7 @@
 //   variant prop。形狀 / 尺寸完全由 consumer 的 className 決定;色彩透過
 //   bg-muted 從 theme 繼承(2026-05-20 修 drift,實際 skeleton.tsx:10 用 bg-muted);
 //   loading 是唯一狀態(無 hover / focus / active)。
-//   本檔僅保留 Overview + CommonShapes + DesignPrinciple 三個 story。
+//   本檔保留 Overview + CommonShapes + DesignPrinciple + Accessibility 四個 story。
 import type { Meta, StoryObj } from '@storybook/react'
 import { Skeleton } from './skeleton'
 import { H3, Desc } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
@@ -14,7 +14,7 @@ import { H3, Desc } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
  * **刻意沒有 size / color / variant**。形狀 / 尺寸完全由 consumer 的 className
  * (Tailwind utilities)決定。底色固定用 `bg-muted`,深淺模式由主題色自動切換。
  *
- * 因此本 spec 只有 Overview + 常見形狀 + 設計原則三個 story,沒有 SizeMatrix /
+ * 因此本 spec 只有 Overview + 常見形狀 + 設計原則 + 無障礙四個 story,沒有 SizeMatrix /
  * ColorMatrix / StateMatrix——這些概念對 Skeleton 不適用。
  */
 

package/src/components/Skeleton/skeleton.principles.stories.tsx

@@ -48,7 +48,7 @@ export const UsageGuidance: Story = {
           <p>適合 Skeleton 的真實業務場景(點擊跳轉「展示」頁範例):</p>
           <ul className="space-y-1">
             <li><LinkTo kind="Design System/Components/Skeleton/展示" name="個人資料卡載入"><span className="text-primary hover:underline font-medium cursor-pointer">個人資料卡載入</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Components/Skeleton/展示" name="任務列表載入"><span className="text-primary hover:underline font-medium cursor-pointer">Task 列表載入</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Skeleton/展示" name="任務列表載入"><span className="text-primary hover:underline font-medium cursor-pointer">任務列表載入</span></LinkTo></li>
             <li><LinkTo kind="Design System/Components/Skeleton/展示" name="表格列載入"><span className="text-primary hover:underline font-medium cursor-pointer">表格列載入</span></LinkTo></li>
             <li><LinkTo kind="Design System/Components/Skeleton/展示" name="文件載入"><span className="text-primary hover:underline font-medium cursor-pointer">文件載入</span></LinkTo></li>
             <li><LinkTo kind="Design System/Components/Skeleton/展示" name="卡片網格載入"><span className="text-primary hover:underline font-medium cursor-pointer">卡片網格載入</span></LinkTo></li>
@@ -151,14 +151,27 @@ export const ShapeMatchRule: Story = {
         title="✅ 形狀模擬最終內容"
         note="avatar 圓形對應圓形頭像、text 行寬度對應真實文字長度、title 高度對應標題字級。資料回來後使用者不會感到「跳版」"
       >
-        <div className="flex items-center gap-3 border border-border rounded-lg p-3 w-72">
-          <Skeleton className="h-10 w-10 rounded-full" />
-          <div className="flex flex-col gap-2 flex-1">
-            <Skeleton className="h-4 w-32" />
-            <Skeleton className="h-3 w-48" />
+        {/* 2026-06-11:改為「載入中 vs 載入完成」對照(原單卡 demo 與使用指引「vs 近親元件」段重複)。 */}
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center gap-3 border border-border rounded-lg p-3 w-72">
+            <Skeleton className="h-10 w-10 rounded-full" />
+            <div className="flex flex-col gap-2 flex-1">
+              <Skeleton className="h-4 w-32" />
+              <Skeleton className="h-3 w-48" />
+            </div>
+          </div>
+          <Label>載入中 — 圓形對應頭像、兩行對應名字 + 最新訊息</Label>
+        </div>
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center gap-3 border border-border rounded-lg p-3 w-72">
+            <div className="flex items-center justify-center h-10 w-10 rounded-full bg-primary text-on-emphasis text-body font-medium shrink-0">林</div>
+            <div className="flex flex-col gap-0.5 flex-1 min-w-0">
+              <span className="text-body font-medium">林雅婷</span>
+              <span className="text-caption text-fg-secondary truncate">已傳送設計稿連結,請查收</span>
+            </div>
           </div>
+          <Label>載入完成 — 形狀一一對應,版面不跳動(Slack DM 列表)</Label>
         </div>
-        <Label>圓形 avatar、兩行文字寬度遞減 — 符合 Slack DM 列表</Label>
       </Rule>
 
       <Rule

package/src/components/Skeleton/skeleton.spec.md

@@ -54,6 +54,7 @@ Skeleton 是**載入中的內容佔位符**——在資料載入完成前，用
 **判準**:
 - **有已知佈局結構需保留 → Skeleton**(佔位、防跳動)
 - **小區塊 / inline 等待 → CircularProgress**(無 value,indeterminate)
+- **長載入換手**(先 Skeleton、超時換 progress):> 3s 的 fallback 規則見「A11y 預設」「替代文字」段
 
 ---
 
@@ -62,7 +63,7 @@ Skeleton 是**載入中的內容佔位符**——在資料載入完成前，用
 - ❌ 用 Skeleton 取代 Empty（確定沒有資料的空狀態）——語意不同
 - ❌ 用 Skeleton 取代 error state——錯誤需要明確提示 + 解決路徑
 - ❌ Skeleton 形狀嚴重偏離真實內容——會讓使用者預期被打破、體感更慢
-- ❌ 長時間（> 10s）的 loading 一直用 Skeleton——使用者會懷疑是否卡住，需改用 progress indicator 或說明文字
+- ❌ 長時間（> 10s）的 loading 一直用 Skeleton——使用者會懷疑是否卡住，需改用 progress indicator 或說明文字（10s = 硬性上限；> 3s 起即建議換手，見「A11y 預設」「替代文字」段）
 
 ---
 
@@ -71,11 +72,11 @@ Skeleton 是**載入中的內容佔位符**——在資料載入完成前，用
 Skeleton 是 pure passive primitive(占位用的 opacity-pulse div),刻意無變體:
 
 - **無 Inspector**:Skeleton 唯一變因是「形狀」(w / h / rounded),由 consumer 透過 className 決定。互動 Inspector 無 prop 可調——該討論的是「怎麼畫出符合實際內容的形狀」,由 `CommonShapes` story 覆蓋。
-- **無 ColorMatrix**:Skeleton 底色固定為 `bg-muted`(2026-05-20 修正歷史 drift `bg-secondary`,實際 `skeleton.tsx:10` 用 `bg-muted` — 對齊 `color.spec.md` 「Static Subtle」段「placeholder / 退化」原則)。Dark mode 自動由 semantic token 處理,加 color variant 會誤導成狀態變化(Skeleton 是 loading 中,不該有語意色)。
+- **無 ColorMatrix**:Skeleton 底色固定為 `bg-muted`(對齊 `color.spec.md`「Static Subtle」段「placeholder / 退化」原則;2026-05-20 修正歷史 drift `bg-secondary`)。Dark mode 自動由 semantic token 處理,加 color variant 會誤導成狀態變化(Skeleton 是 loading 中,不該有語意色)。
 - **無 SizeMatrix**:Skeleton 無 size prop,尺寸完全由 consumer className(`w-32 h-4`)或 parent 決定——因為它要精確模擬內容形狀,不能限制成 sm/md/lg tier。
 - **無 StateBehavior**:Skeleton 只有「顯示 / 不顯示」兩態(consumer unmount 即消失),無 hover / focus / active / selected / disabled——非互動元件。
 
-對應 anatomy story:保留 `Overview` + 元件特有 `CommonShapes`(避免漂移的標準形狀庫) + `DesignPrinciple`(與 CircularProgress 的分界)。
+對應 anatomy story:保留 `Overview` + 元件特有 `CommonShapes`(避免漂移的標準形狀庫)+ `DesignPrinciple`(與 CircularProgress 的分界)+ `Accessibility`(2026-05-17 加)。
 
 ---
 
@@ -87,7 +88,7 @@ Skeleton 是**純視覺 loading placeholder**,預設 ARIA 行為:
 - **`aria-busy="true"` 由 consumer 容器 own**:loading region 的容器(如 DataTable / Card / Sidebar group)應設 `aria-busy="true"`,告知 SR「該區域 loading 中」;data ready 後 consumer 移除 `aria-busy` 同時 unmount Skeleton
 - **不取得 focus**:Skeleton 永遠 non-interactive,無鍵盤行為
 - **動畫**:`prefers-reduced-motion: reduce` 用戶自動 stop pulse 動畫(`skeleton.tsx:10` 的 `motion-reduce:animate-none`)。pulse 是自動播放的循環動畫,歸 WCAG 2.2.2 Pause, Stop, Hide(Level A);honor `prefers-reduced-motion` 即滿足。注意非 2.3.3 Animation from Interactions(該 SC 是 Level AAA,僅涵蓋由互動 / 捲動觸發的位移動畫,不適用 auto-play loop)
-- **替代文字**:長時間 loading(>3s)consumer 應 fallback 為 `<Empty icon={<CircularProgress/>} description="載入中..." />`(SR-friendly text)— Skeleton 適合 < 3s 短暫 placeholder
+- **替代文字**:長時間 loading(>3s)consumer 應 fallback 為 `<Empty icon={<CircularProgress/>} description="載入中..." />`(SR-friendly text)— Skeleton 適合 < 3s 短暫 placeholder(3s 為建議換手值;> 10s 仍用 Skeleton 屬「禁止事項」硬性違規)
 - **驗證**:Storybook a11y addon panel 0 critical violation。Skeleton 本身無文字內容、無互動角色,axe 不會要求 label;若 consumer 把 Skeleton 包進有語意的容器,label 由該容器負責
 
 ## 相關
@@ -101,4 +102,5 @@ Skeleton 是**純視覺 loading placeholder**,預設 ARIA 行為:
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `circular-progress.spec.md`
 - `progress-bar.spec.md`