@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

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

@@ -0,0 +1,353 @@
+// @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.
+// @overlay-open-skip: 本檔為 usage-guidance(設計原則)story——每個 Rule 卡片以「關閉的 trigger 按鈕」並排比較 Sheet / Dialog / Popover 何時用;全部 defaultOpen 會讓多個 portal 疊在一起、視覺全毀。overlay 開啟狀態的視覺覆蓋由 sheet.stories.tsx(展示)+ sheet.anatomy.stories.tsx(Inspector defaultOpen)負責。
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Trash2, Filter } from 'lucide-react'
+import {
+  Sheet,
+  SheetTrigger,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+  SheetBody,
+  SheetFooter,
+  SheetClose,
+} from './sheet'
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogBody,
+  DialogFooter,
+} from '@/design-system/components/Dialog/dialog'
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverBody,
+} from '@/design-system/components/Popover/popover'
+import { Button } from '@/design-system/components/Button/button'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+import { Input } from '@/design-system/components/Input/input'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { CheckboxGroup } from '@/design-system/components/Checkbox/checkbox-group'
+
+const meta: Meta = {
+  title: 'Design System/Components/Sheet/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-wrap gap-3 items-start">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── WhenToUse — 何時使用 Sheet ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsDialogRule(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Sheet 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Sheet/展示" name="建立新專案（右側滑入）"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">建立新專案（右側滑入）</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Sheet/展示" name="編輯成員詳情（右側滑入）"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">編輯成員詳情（右側滑入）</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見本頁下方「vs 近親」對照段)。</p>
+    </div>
+
+      {/* vs 近親 — VsDialogRule — 原 VsDialogRule */}
+      <div>
+      <Rule
+        title="Sheet — 從邊緣滑入,側邊工作流程 / 複雜表單 / 長時間編輯"
+        note="使用者在主頁看清單、點擊某一項 → Sheet 從右側滑入編輯。Sheet 較輕、較長,讓使用者可以「看到 context 同時編輯」。典型案例:Jira issue drawer、Linear issue detail、Stripe customer detail panel、Notion database 單列展開編輯"
+      >
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="tertiary">編輯專案設定</Button>
+          </SheetTrigger>
+          <SheetContent side="right" className="flex flex-col sm:max-w-lg">
+            <SheetHeader>
+              <SheetTitle>專案設定</SheetTitle>
+              <SheetDescription>修改此專案的基本資訊與通知偏好</SheetDescription>
+            </SheetHeader>
+            {/* Body 必用 SheetBody(內建 ScrollArea + 浮層 padding SSOT px-loose/pt-tight/pb-bottom);
+                自組 ScrollArea + py-4 = 水平 0 padding 歷史 bug,詳 sheet.tsx SheetBody comment。 */}
+            <SheetBody className="flex flex-col gap-[var(--layout-space-loose)]">
+                <Field>
+                  <FieldLabel>名稱</FieldLabel>
+                  <Input defaultValue="產品路線圖" />
+                </Field>
+                <Field>
+                  <FieldLabel>描述</FieldLabel>
+                  <Input defaultValue="Q1 / Q2 產品開發重點" />
+                </Field>
+                <Field>
+                  <FieldLabel>通知</FieldLabel>
+                  <CheckboxGroup>
+                    <Checkbox defaultChecked label="新任務" />
+                    <Checkbox label="每日摘要" />
+                  </CheckboxGroup>
+                </Field>
+            </SheetBody>
+            <SheetFooter>
+              <SheetClose asChild>
+                <Button variant="tertiary">取消</Button>
+              </SheetClose>
+              <Button variant="primary">儲存</Button>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+        <Label>↑ 多欄位編輯 + 仍想看主頁 context → Sheet(側滑不完全遮蔽主頁)</Label>
+      </Rule>
+
+      <Rule
+        title="Dialog — 居中 modal,短確認 / 重要決策 / 不可逆動作"
+        note="視覺完全聚焦,overlay 遮住主頁。適合需要使用者完全停下、做決定的場景。典型案例:Stripe 永久刪除客戶、Notion workspace 轉移、Linear 刪除 project、Figma 放棄未儲存變更"
+      >
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button variant="primary" danger startIcon={Trash2}>永久刪除專案</Button>
+          </DialogTrigger>
+          <DialogContent autoHeight maxWidth="440px">
+            <DialogHeader>
+              <DialogTitle>確定要永久刪除此專案?</DialogTitle>
+            </DialogHeader>
+            <DialogBody>
+              <p className="text-body">此動作無法復原。所有任務、評論、附件都將一併刪除。</p>
+            </DialogBody>
+            <DialogFooter>
+              <Button variant="tertiary">取消</Button>
+              <Button variant="primary" danger>永久刪除</Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+        <Label>↑ 短決策 + 不可逆 → Dialog(完全聚焦,不讓使用者漏掉)</Label>
+      </Rule>
+
+      <Rule
+        title="判準 — Sheet 做「工作」,Dialog 做「決定」"
+        note="Sheet 用於需要 context 的多欄位編輯(使用者會花時間填,想看主頁資料)。Dialog 用於聚焦決策(確認 / 取消,不需要看主頁)。Sheet 可長、可複雜;Dialog 短、視線聚集"
+      >
+        <Label>Sheet:建立 issue、編輯成員、filter 面板、detail drawer</Label>
+        <Label>Dialog:刪除確認、放棄變更、登入、付款確認</Label>
+      </Rule>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotSheetRule。
+          短確認 → Dialog 的完整 live 對照已在上方「Dialog — 居中 modal」段示範,此處不重複(2026-06-11 精簡)。 */}
+      <Rule
+        title="何時不用 / 替代元件 — 短確認 / 不可逆動作 → Dialog"
+        note="「刪除 / 登出 / 放棄變更」這類要使用者完全停下做決定的場景,用 Dialog 的居中 modal 強制聚焦。Sheet 側滑視覺不夠強,使用者可能點旁邊就跳過(live 對照見上方「Dialog — 居中 modal」段)"
+      >
+        <Label>↑ 短決策應該用 Dialog(Sheet 太長太輕)</Label>
+      </Rule>
+
+      <Rule
+        title="何時不用 / 替代元件 — 輕量提示 / 設定 mini panel → Popover"
+        note="filter 條件、快速切換設定、小型操作面板 — 不需要 Sheet 的龐大篇幅。Popover 附在 trigger 旁邊、更輕量、使用者可忽略繼續主流程"
+      >
+        <Popover>
+          <PopoverTrigger asChild>
+            <Button variant="tertiary" startIcon={Filter}>篩選</Button>
+          </PopoverTrigger>
+          {/* naked popover(無 PopoverTitle)→ 自傳 aria-label 讓 role="dialog" 有 accessible name(popover.spec.md A11y) */}
+          <PopoverContent align="start" aria-label="依狀態篩選">
+            <PopoverBody>
+              <CheckboxGroup>
+                <Checkbox defaultChecked label="進行中" />
+                <Checkbox label="已完成" />
+              </CheckboxGroup>
+            </PopoverBody>
+          </PopoverContent>
+        </Popover>
+        <Label>↑ 少量選項 + 輕量補充 UI → Popover(別用 Sheet 的整面篇幅)</Label>
+      </Rule>
+
+      <Rule
+        title="何時不用 / 替代元件 — Mobile 大量內容、沉浸編輯 → full Dialog 或專屬頁面"
+        note="Sheet 在 mobile 預設占 75% 寬,若內容複雜需全螢幕,改用 fullscreen Dialog 或導航到獨立頁面。Mobile 上硬塞大量欄位到 right Sheet 會變得難滑、難看"
+      >
+        <Label>↑ 手機上大量欄位 + 複雜表單 → 獨立頁面或 fullscreen Dialog</Label>
+      </Rule>
+
+      <Rule
+        title="何時不用 / 替代元件 — 短暫回饋(成功 / 失敗)→ Toast"
+        note="「已儲存」「刪除失敗」這類短暫非阻斷的回饋,用 Toast 自動消失。Sheet 需要使用者明確關閉,給短訊息用 Sheet 是過度阻斷"
+      >
+        <Label>↑ 操作結果回饋 → Toast(不用 Sheet 讓使用者手動關)</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const SidePropRule: Story = {
+  name: 'Side 屬性：消費者用 right（其餘內部基建）',
+  render: () => (
+    <div>
+      <Rule
+        title="right（消費者唯一合法 side，預設）— detail / 編輯 / 建立"
+        note="消費者 Sheet API 只能用 side=&quot;right&quot;。世界級 SaaS 一致的 convention:Jira issue drawer、Linear issue detail、GitHub PR file diff drawer、Stripe customer drawer、Notion database row expand 都在右側。理由是:使用者視線「從左(清單)看到右(詳情)」,右側 Sheet 符合自然閱讀動線"
+      >
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="tertiary">右側編輯</Button>
+          </SheetTrigger>
+          <SheetContent side="right">
+            <SheetHeader>
+              <SheetTitle>任務詳情</SheetTitle>
+              <SheetDescription>#PROJ-234 · 指派給Ada Chen</SheetDescription>
+            </SheetHeader>
+            <SheetBody className="text-body text-fg-secondary">
+              登入頁在連續輸入錯誤密碼 3 次後未顯示鎖定提示,使用者反覆嘗試仍無回饋。建議補上鎖定倒數與重設連結。
+            </SheetBody>
+          </SheetContent>
+        </Sheet>
+        <Label>↑ 列表點 row → 右側滑入編輯,左側列表仍可見</Label>
+      </Rule>
+
+      <Rule
+        title="left（DS 內部基建，非消費者 API）— Sidebar 小視口 left-slide"
+        note="left 保留 DS 內部基建用（例:Sidebar 在小視口從 left 滑入）,消費者 code 禁止傳 side=&quot;left&quot;,需 user 授權。世界級 mobile nav convention(Slack / Gmail hamburger / Material navigation drawer 在左)是此變體的設計來源,但本 DS 的 mobile navigation 應走專屬 navigation 元件,不混在消費者 Sheet。以下為內部能力示範。"
+      >
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="tertiary">☰ 左側目錄</Button>
+          </SheetTrigger>
+          <SheetContent side="left">
+            <SheetHeader>
+              <SheetTitle>目錄</SheetTitle>
+            </SheetHeader>
+            <div className="flex-1 py-2 flex flex-col">
+              {['總覽', '任務', '成員', '設定'].map(name => (
+                <button key={name} type="button" className="px-3 py-2 text-body text-left hover:bg-neutral-hover rounded-md">
+                  {name}
+                </button>
+              ))}
+            </div>
+          </SheetContent>
+        </Sheet>
+        <Label>↑ 主導覽 / 目錄 → 左側(mobile hamburger 展開)</Label>
+      </Rule>
+
+      <Rule
+        title="bottom（DS 內部基建，非消費者 API）"
+        note="bottom 保留 DS 內部基建用,消費者 code 禁止傳 side=&quot;bottom&quot;。iOS / Material Bottom Sheet convention(手機拇指操作區在螢幕下半)是此變體來源,但本 DS 若需 mobile bottom sheet 應走專屬 BottomSheet 元件,不混在消費者 Sheet 的 side prop。以下為內部能力示範。"
+      >
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="tertiary">分享</Button>
+          </SheetTrigger>
+          <SheetContent side="bottom" className="max-w-full">
+            <SheetHeader>
+              <SheetTitle>分享</SheetTitle>
+            </SheetHeader>
+            <SheetBody className="flex flex-col gap-2">
+              {['複製連結', '傳送到 Email', '加入我的最愛', '匯出 PDF'].map(name => (
+                <button key={name} type="button" className="px-3 py-2 text-body text-left hover:bg-neutral-hover rounded-md">
+                  {name}
+                </button>
+              ))}
+            </SheetBody>
+          </SheetContent>
+        </Sheet>
+        <Label>↑ 手機拇指操作區 → bottom Sheet</Label>
+      </Rule>
+
+      <Rule
+        title="top（DS 內部基建，非消費者 API）"
+        note="top 保留 DS 內部基建用,消費者 code 禁止傳 side=&quot;top&quot;。一般產品極少用(視線從頭頂滑入不自然),僅系統層級的內部情境保留。"
+      >
+        <Label>↑ 消費者不用 top;為 DS 內部保留變體</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 消費者傳 side=&quot;left&quot; / &quot;bottom&quot; / &quot;top&quot;"
+        note="消費者 Sheet API 只能用 right。傳其他方向 = 越權使用 DS 內部基建變體(需 user 授權)。需 mobile navigation / bottom sheet 請用專屬元件,不要借 Sheet 的內部 side。"
+      >
+        <Label warn>↑ 消費者只用 side=&quot;right&quot;;left / bottom / top 是內部基建,不可直接傳</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const HeaderFooterStructureRule: Story = {
+  name: '頁首 / 頁尾 結構',
+  render: () => (
+    <div>
+      <Rule
+        title="標準結構 — Header(標題 + 描述) + 主內容 + Footer(按鈕列)"
+        note="與 Dialog 共用 overlay-surface 視覺語言(bg-surface-raised / elevation-200;容器邊框用較淡的 border-divider,Dialog 用 border-border)。Header 放 SheetTitle + SheetDescription,Footer 放按鈕列;主內容區用 SheetBody(內建 ScrollArea 跨 OS 一致捲軸 + 浮層 padding SSOT)吃長內容"
+      >
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="tertiary">建立新客戶</Button>
+          </SheetTrigger>
+          <SheetContent side="right" className="flex flex-col sm:max-w-lg">
+            <SheetHeader>
+              <SheetTitle>建立新客戶</SheetTitle>
+              <SheetDescription>填寫基本資料後可進行付款設定</SheetDescription>
+            </SheetHeader>
+            {/* Body 必用 SheetBody(內建 ScrollArea + 浮層 padding SSOT) */}
+            <SheetBody className="flex flex-col gap-[var(--layout-space-loose)]">
+                <Field>
+                  <FieldLabel>公司名稱</FieldLabel>
+                  <Input placeholder="輸入公司名稱" />
+                </Field>
+                <Field>
+                  <FieldLabel>聯絡人 Email</FieldLabel>
+                  <Input placeholder="contact@example.com" />
+                </Field>
+            </SheetBody>
+            <SheetFooter>
+              <SheetClose asChild>
+                <Button variant="tertiary">取消</Button>
+              </SheetClose>
+              <Button variant="primary">建立</Button>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+        <Label>↑ Header(why)+ Body(do what)+ Footer(finalize),三段式結構</Label>
+      </Rule>
+
+      <Rule
+        title="Footer 按鈕順序 — 取消在左(或起點),Primary 在右(終點)"
+        note="與 Dialog 一致。使用者動線從左到右、從起點到終點,Primary 放終點符合「完成動作」的位置。破壞性動作加 danger,不改位置"
+      >
+        <Label>✅ 左:取消 / 右:儲存</Label>
+        <Label>✅ 左:取消 / 右:永久刪除(danger 顏色疊加,位置不變)</Label>
+      </Rule>
+    </div>
+  ),
+}
+

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

@@ -16,7 +16,7 @@ benchmark:
 
 ## 定位
 
-Sheet 是**從畫面邊緣滑入的浮層面板**——上 / 下 / 左 / 右四個方向，用於側邊操作、暫時性 panel、mobile fullscreen 編輯。
+Sheet 是**從畫面邊緣滑入的浮層面板**。**消費者 API = 右側滑入**（`side="right"`，detail panel / 編輯 / filter drawer，對齊 Jira / Linear / Notion 右側 detail drawer 慣例）。`top` / `bottom` / `left` 變體**保留 DS 內部基建用**（例：Sidebar 在小視口從 left 滑入），消費者 code **禁止傳** `side="top" | "bottom" | "left"`，這些用途需 user 授權（canonical 見 `sheet.tsx` L23-27 + showcase `AR35`）。
 
 **實作基礎**：shadcn passthrough——基於 Radix Dialog（`side` variant，非居中 modal）。本 DS 保留 shadcn 原結構 + 橋接 DS token。
 
@@ -28,7 +28,7 @@ Sheet 是**從畫面邊緣滑入的浮層面板**——上 / 下 / 左 / 右四
 
 - **側邊操作面板**：filter panel、detail pane、task 編輯 side sheet
 - **暫時性內容展示**：notification drawer、cart summary、activity history
-- **Mobile fullscreen 編輯**：桌機用 Dialog 的場景在手機改用 Sheet bottom / fullscreen
+- **Mobile 側邊編輯**：桌機 detail / 編輯 flow 在手機沿用同一個右側 Sheet（mobile 預設占 75% 寬）。內容過於複雜需全螢幕時改用 fullscreen Dialog 或導航到獨立頁面，不借 `side="bottom"`（bottom 為 DS 內部基建變體、非消費者 API；需 mobile bottom sheet 另用專屬元件）
 - **跟主頁面平行的工作流程**：使用者在主頁看清單，sheet 編輯某一項，不離開清單 context
 
 ## 何時不用
@@ -48,11 +48,11 @@ Sheet 是**從畫面邊緣滑入的浮層面板**——上 / 下 / 左 / 右四
 
 | | 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**
@@ -60,17 +60,17 @@ Sheet 是**從畫面邊緣滑入的浮層面板**——上 / 下 / 左 / 右四
 
 ---
 
-## 為何無 Inspector
+## Inspector
 
-Sheet 是**側邊滑入 modal 容器**,關鍵決策維度是 `side`(top / right / bottom / left)× size(響應式)× open/close——已由元件特有 `SideMatrix`(4 個方向結構對照) + `SizeMatrix` + `StateBehavior`(open/close/ESC) + `ColorMatrix` 四張矩陣覆蓋。互動 Inspector 切換 side 不如 side-by-side 4 方向對照直觀——需要視覺比較各方向滑入結構。內容完全由 consumer 決定,Sheet 本身無 variant/disabled 等可試玩 prop。
+`Inspector` 提供互動 Controls 即時切換 SheetContent 三個關鍵維度:`side`(top / right / bottom / left,看四方向滑入動畫 + 位置)、`width`(default / sm / lg 寬度覆寫)、`showFooter`(是否顯示底部 CTA 列)。內容區由 consumer 決定,Inspector 聚焦容器層級的可試玩 prop。
 
-對應 anatomy story:保留 `Overview` + 元件特有 `SideMatrix`(4 方向 × 用途) + `ColorMatrix` + `SizeMatrix` + `StateBehavior`。
+對應 anatomy story:`Overview` + `Inspector` + 元件特有 `SideMatrix`(4 方向 × 用途) + `ColorMatrix` + `SizeMatrix` + `StateBehavior`。
 
 ---
 
 ## 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**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。`side` 維持 physical direction。
 - **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。
 
@@ -129,7 +132,7 @@ Sheet 為容器,內容由 consumer 決定;focus trap + Escape close + `aria-labe
 - Esc — 關閉
 - Shift+Tab — 反向 focus 循環
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:Radix primitive 自管 focus trap / visible ring(per design-system focus-visible canonical)。**Restoration 例外(2026-07-14)**:Radix 內建「關閉回焦 trigger」依賴 `SheetTrigger` 的 triggerRef;**controlled-without-trigger**(如 AppShellAside 手機模式)triggerRef=null + 內建 preventDefault 會讓焦點掉 `<body>` — 必自建 `onCloseAutoFocus` snapshot 還原(先例:AppShellAside app-shell.tsx / DatePicker Range date-picker.tsx:1061;WCAG 2.4.3)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -138,11 +141,7 @@ Sheet 為容器,內容由 consumer 決定;focus trap + Escape close + `aria-labe
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `accordion.spec.md`
-- `scroll-area.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `app-shell.spec.md`
-- `density.spec.md`
+- `dialog.spec.md`
+- `popover.spec.md`
+- `scroll-area.spec.md`

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

@@ -0,0 +1,172 @@
+// @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 type { Meta, StoryObj } from '@storybook/react'
+import {
+  Sheet,
+  SheetTrigger,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetBody,
+  SheetFooter,
+  SheetClose,
+} from './sheet'
+import { Button } from '@/design-system/components/Button/button'
+import { Field, FieldLabel, FieldDescription } from '@/design-system/components/Field/field'
+import { Input } from '@/design-system/components/Input/input'
+import { Textarea } from '@/design-system/components/Textarea/textarea'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { CheckboxGroup } from '@/design-system/components/Checkbox/checkbox-group'
+
+const meta: Meta = {
+  title: 'Design System/Components/Sheet/展示',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: { description: { component: '從畫面右側滑入的模態工作面，提供 header、可捲 body 與 footer。當次要流程需要更多空間但仍應保留原頁脈絡時使用；短小選項改用 Popover。' } },
+  },
+}
+export default meta
+type Story = StoryObj
+
+export const CreateProjectRight: Story = {
+  name: '建立新專案（右側滑入）',
+  render: () => (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button variant="primary">建立新專案</Button>
+      </SheetTrigger>
+      <SheetContent side="right" className="flex flex-col sm:max-w-lg">
+        <SheetHeader>
+          <SheetTitle>建立新專案</SheetTitle>
+        </SheetHeader>
+        {/* Field-to-field gap = `--layout-space-loose`:form 用 `flex-col gap-*` 單值,保守選 loose
+            讓「非 fw ↔ 非 fw」Input↔Input 合規(規則 3 per-transition 原意 loose);
+            fw-adjacent 的微 tight 視覺損失 < 非 fw-adjacent 的 loose 破壞。
+            詳 `layoutSpace.spec.md` 規則 3 caveat。 */}
+        <SheetBody className="flex flex-col gap-[var(--layout-space-loose)]">
+          <Field>
+            <FieldLabel>專案名稱</FieldLabel>
+            <Input placeholder="例:Q2 產品路線圖" />
+          </Field>
+          <Field>
+            <FieldLabel>描述</FieldLabel>
+            <Textarea placeholder="簡述此專案的目標與範圍" rows={4} />
+            <FieldDescription>選填,可在建立後補上</FieldDescription>
+          </Field>
+          {/* 多選場景:初始成員權限(從設計系統中組合出 Jira / Linear 專案建立流程的典型多選欄位)
+              label 明確是「多選權限」;若要做「開 / 關通知」這種 binary toggle,用 Switch 不用 CheckboxGroup。 */}
+          <Field>
+            <FieldLabel>初始成員權限</FieldLabel>
+            <FieldDescription>可勾選多項,所有成員預設獲得這些權限</FieldDescription>
+            <CheckboxGroup>
+              <Checkbox defaultChecked label="檢視專案內容" />
+              <Checkbox defaultChecked label="新增與編輯任務" />
+              <Checkbox label="管理成員與設定" />
+            </CheckboxGroup>
+          </Field>
+        </SheetBody>
+        <SheetFooter>
+          <SheetClose asChild>
+            <Button variant="tertiary">取消</Button>
+          </SheetClose>
+          <Button variant="primary">建立專案</Button>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ),
+}
+
+export const EditUserRight: Story = {
+  name: '編輯成員詳情（右側滑入）',
+  render: () => (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button variant="tertiary">檢視成員詳情</Button>
+      </SheetTrigger>
+      <SheetContent side="right" className="flex flex-col">
+        <SheetHeader>
+          <SheetTitle>Ada Chen</SheetTitle>
+        </SheetHeader>
+        {/* Field-to-field gap = `--layout-space-loose`:form 用 `flex-col gap-*` 單值,保守選 loose
+            讓「非 fw ↔ 非 fw」Input↔Input 合規(規則 3 per-transition 原意 loose);
+            fw-adjacent 的微 tight 視覺損失 < 非 fw-adjacent 的 loose 破壞。
+            詳 `layoutSpace.spec.md` 規則 3 caveat。 */}
+        <SheetBody className="flex flex-col gap-[var(--layout-space-loose)]">
+          <Field>
+            <FieldLabel>顯示名稱</FieldLabel>
+            <Input defaultValue="Ada Chen" />
+          </Field>
+          <Field>
+            <FieldLabel>職稱</FieldLabel>
+            <Input defaultValue="Design Engineer" />
+          </Field>
+          <Field>
+            <FieldLabel>Email</FieldLabel>
+            <Input defaultValue="ada.chen@example.com" />
+          </Field>
+          <Field>
+            <FieldLabel>進階權限</FieldLabel>
+            <FieldDescription>可勾選多項</FieldDescription>
+            <CheckboxGroup>
+              <Checkbox defaultChecked label="管理其他成員帳號" />
+              <Checkbox defaultChecked label="編輯工作區設定" />
+              <Checkbox label="刪除專案與資料" />
+            </CheckboxGroup>
+          </Field>
+        </SheetBody>
+        <SheetFooter>
+          <SheetClose asChild>
+            <Button variant="tertiary">取消</Button>
+          </SheetClose>
+          <Button variant="primary">儲存變更</Button>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ),
+}
+
+// LeftNavigation 範例移除(AR35):消費者 Sheet API **只能用 side="right"**。
+// 左側 / 頂部 / 底部為 DS 內部基建用(如 Sidebar 在 narrow viewport 時切 left 滑入),
+// 需 user 明示授權。本 stories 檔不提供未授權用法示範。
+
+/**
+ * OpenSnapshot — visual-audit 專用 story(對齊 Dialog OpenSnapshot canonical)。
+ * `defaultOpen` 讓 Sheet render 即開著,Playwright 截圖抓得到 chrome(Header / Body / Footer)。
+ * 世界級 Polaris / Atlassian chromatic 稽核共通 pattern。
+ */
+export const OpenSnapshot: Story = {
+  name: '開啟狀態',
+  tags: ['test-only'],
+  render: () => (
+    <Sheet defaultOpen>
+      <SheetTrigger asChild>
+        <Button>打開 Sheet</Button>
+      </SheetTrigger>
+      <SheetContent className="flex flex-col sm:max-w-lg">
+        <SheetHeader>
+          <SheetTitle>編輯使用者 profile</SheetTitle>
+        </SheetHeader>
+        <SheetBody className="flex flex-col gap-[var(--layout-space-loose)]">
+          <Field>
+            <FieldLabel>顯示名稱</FieldLabel>
+            <Input defaultValue="Alan Chen" />
+          </Field>
+          <Field>
+            <FieldLabel>職稱</FieldLabel>
+            <Input defaultValue="Senior Designer" />
+          </Field>
+          <Field>
+            <FieldLabel>自我介紹</FieldLabel>
+            <Textarea defaultValue="設計師,專注於 DS + tooling。" rows={3} />
+          </Field>
+        </SheetBody>
+        <SheetFooter>
+          <SheetClose asChild>
+            <Button variant="tertiary">取消</Button>
+          </SheetClose>
+          <Button variant="primary">儲存</Button>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ),
+}