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

package/src/components/FileUpload/file-upload.spec.md

@@ -22,7 +22,7 @@ benchmark:
 
 ## 定位
 
-FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點擊觸發檔案選取浮窗。負責「上傳觸發 + 拖放偵測」,不負責「已上傳檔案清單顯示」(那是 `FileItem` 的職責)。
+FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點擊觸發檔案選取浮窗。核心職責是「上傳觸發 + 拖放偵測」;它**不 own 單筆檔案列的視覺規格**(狀態圖示 / 縮圖 / 進度條 / 列排版屬 `FileItem` 的 SSOT),但**可 orchestrate 內建清單**——透過 `files` prop 內部組合 `FileItem` 渲染已上傳清單(dual-path,見「Props 行為」與「禁止事項」);consumer 自組 `FileItem` 清單亦合法。
 
 **實作基礎**:自建 — native HTML5 `<input type="file">` + drag-and-drop event(dragenter/dragover/dragleave/drop)+ DOM-level state 切換。無 external primitive,因為 Radix 沒 File Upload 對應 primitive,其他 UI kit 的 file upload 多數也是自建這層。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
@@ -146,7 +146,8 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 - `role="button"` + `tabIndex=0`(disabled 或 loading 時 `-1`)
 - Enter / Space 鍵觸發檔案選取浮窗(模擬 click)
 - `aria-disabled={true}` 當 disabled
-- `<input type="file">` 以 `className="hidden"`(`display:none`)隱藏 — 移出無障礙樹、不可聚焦;互動由外層 `role="button"` wrapper 承載。Accessible name 來自 wrapper 內 Empty 的 title + description 文字(name-from-content),非 input 本身
+- `<input type="file">` 以 `className="hidden"`(`display:none`)隱藏 — 移出無障礙樹、不可聚焦;互動由外層 `role="button"` wrapper 承載
+- **Accessible name(name-from-content + custom children 例外)**:預設(未傳 children)時 name 來自 wrapper 內 `<Empty>` 的 title + description 文字,非 input 本身。**但 `children` 會整個覆寫預設結構**——若 consumer 傳入**只有 icon / branding 圖像、無可見文字**的 children,`role="button"` wrapper 就失去 accessible name(SR 讀不出用途)。此情況 consumer **必須**在 `<FileUpload>` root 傳 `aria-label`(經 `{...props}` spread 到 wrapper div),或確保 children 內含可見文字。dropzone 與 button 兩 variant 同理
 
 ---
 

package/src/components/FileUpload/file-upload.tsx

@@ -222,7 +222,11 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
       <div ref={ref} className={cn('w-full', hasFiles && 'flex flex-col')}>
       {variant === 'button' ? (
         // ── button variant:緊湊觸發(form-friendly,省空間),click-only(無拖放區)──
-        <div className={className} {...props}>
+        // consumer onClick 在此 wrapper div 承載(type = MouseEvent<HTMLDivElement>,對齊 FileUploadProps
+        // extends HTMLAttributes<HTMLDivElement>)。Button 觸發開檔會冒泡至此 → 同時觸發 consumer handler。
+        // 2026-07-17 修:onClick 於 L128 destructure 後未再 compose,button variant 靜默丟失公開 DOM prop
+        // (dropzone variant 經 handleClick 的 onClick?.(e) 正確 compose,button variant 漏接)。
+        <div className={className} onClick={onClick} {...props}>
           <input
             ref={inputRef}
             type="file"

package/src/components/FileViewer/file-viewer.anatomy.stories.tsx

@@ -710,7 +710,7 @@ export const SizeMatrix: Story = {
               <tr>
                 <Td>Body 垂直 padding</Td>
                 <Td mono>pt-[var(--layout-space-tight)] pb-[var(--layout-space-loose)]</Td>
-                <Td>非對稱:top tight / bottom loose(對齊 layoutSpace v6 規則 4「bounded region 容器底 = loose」)</Td>
+                <Td>非對稱:top tight / bottom loose(bounded region 容器底部留白較寬鬆,內容不貼底、捲動時收尾更透氣)</Td>
               </tr>
               <tr>
                 <Td>Section 間 gap</Td>

package/src/components/FileViewer/file-viewer.principles.stories.tsx

@@ -423,7 +423,7 @@ export const ReadOnlyRule: Story = {
 
         <Rule
           title="✅ readOnly — 其他人上傳的 / 公開公告 / 只讀 link 分享"
-          note="readOnly=true 時說明區依 DS Textarea readonly canonical:有值 → 可聚焦選取但不可改的 native readonly textarea;空值 → display div 顯 emptyDisplay(`-`,非 placeholder);onDescriptionChange 不觸發。故 readonly 無 description 時顯示 `-`,不會出現「為這個檔案加上說明...」的編輯誘導 placeholder"
+          note="readOnly=true 時說明區依 DS Textarea readonly canonical:有值 → 可聚焦選取但不可改的 native readonly textarea;空值 → view div 顯 emptyDisplay(`-`,非 placeholder);onDescriptionChange 不觸發。故 readonly 無 description 時顯示 `-`,不會出現「為這個檔案加上說明...」的編輯誘導 placeholder"
         >
           <Button variant="tertiary" startIcon={FolderOpen} onClick={() => setRoOpen(true)}>
             開啟公司公告(readOnly)

package/src/components/FileViewer/file-viewer.spec.md

@@ -140,7 +140,7 @@ FileViewer Toolbar 消費 `patterns/action-bar/action-bar.spec.md` 的**左中
 - **zoom** — 同一張檔案的微調(影響範圍:當前 renderer 的 transform state),影響最小
 - **info** — 切換附加資訊面板(影響範圍:layout,不破壞現有內容)
 - **download** — 把內容搬出 viewer(影響範圍:外部檔案系統,不可逆副作用)
-- **close** — 結束整個 viewing session(影響範圍:最大)。註:close = `setOpen(false)`,**僅卸載 `DialogContent` 子樹**;外層 FileViewer 元件恆掛載,shell state(zoom / infoOpen / index 等 `useState`)**保留** —— 重開同一檔沿用上次 zoom / infoOpen,非 fresh state
+- **close** — 結束整個 viewing session(影響範圍:最大)。註:close = `setOpen(false)`,**僅卸載 `DialogContent` 子樹**;外層 FileViewer 元件恆掛載,shell state(zoom / infoOpen 等 `useState`)**保留** —— 重開同一檔沿用上次 zoom / infoOpen,非 fresh state(**index 例外**:uncontrolled 時開啟即重置為 `initialIndex`,`file-viewer.tsx` 開啟 effect)
 
 ### Dismiss canonical(Close X)
 

package/src/components/FileViewer/file-viewer.stories.tsx

@@ -203,7 +203,7 @@ const figmaDesignFile: FileInfo[] = [
     mimeType: 'image/png',
     size: 2_840_000,
     description:
-      'Dashboard v2 最終設計稿 — 對齊 spec 2.3 節「Frozen columns + row actions」,可 zoom 看細節對齊。',
+      '營運儀表板 v2 最終設計稿 — 凍結欄與列操作已定案,可 zoom 檢視 spacing 與色彩細節。',
     metadata: {
       '設計師': 'Claire Wu',
       'Figma link': 'figma.com/file/xyz/Dashboard',

package/src/components/FileViewer/file-viewer.tsx

@@ -530,13 +530,13 @@ const InfoPanel = React.memo(function InfoPanel({
         {/* 檔案資訊 — 用 DS DescriptionList horizontal + divided(Google Drive /
             Notion file info panel 模式):
             - section header 用 FieldLabel 同款 typography 保視覺一致
-            - DescriptionList direction="horizontal" divided 提供 row 下底線
+            - DescriptionList orientation="horizontal" divided 提供 row 下底線
               對齊格線,key 長度不一也易讀
             - 不再手刻 dl/dt/dd — canonical 由 DS primitive own */}
         {/* heading → first-item gap = item → item gap(Gestalt proximity,見 description-list.spec.md) */}
         <div className="flex flex-col gap-[var(--layout-space-tight)]">
           <span className="text-body font-normal text-foreground">{labels.fileInfoHeading}</span>
-          <DescriptionList direction="horizontal" divided>
+          <DescriptionList orientation="horizontal" divided>
             <DescriptionItem label="檔名">{file.name}</DescriptionItem>
             <DescriptionItem label="類型">{file.mimeType || '-'}</DescriptionItem>
             {sizeText && (
@@ -775,6 +775,7 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
   allowDownload = true,
   onDownload,
   labels: labelsOverride,
+  className,
   ...props
 }, ref) {
   const labels = React.useMemo(

package/src/components/HoverCard/hover-card.anatomy.stories.tsx

@@ -89,7 +89,7 @@ export const VisualVariants: Story = {
         <div className="flex items-center gap-6">
           <HoverCard>
             <HoverCardTrigger asChild>
-              <Button variant="tertiary" size="sm">hover 看 Card</Button>
+              <Button variant="tertiary" size="sm">Ada Chen</Button>
             </HoverCardTrigger>
             <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-4 shadow-[var(--elevation-200)]">
               <div className="w-56">
@@ -108,11 +108,13 @@ export const VisualVariants: Story = {
         <div className="flex items-center gap-6">
           <HoverCard>
             <HoverCardTrigger asChild>
-              <Button variant="tertiary" size="sm">hover 看 Tooltip 樣式</Button>
+              <Button variant="tertiary" size="sm">+3 位協作者</Button>
             </HoverCardTrigger>
             <HoverCardContent className="bg-tooltip rounded-md px-3 py-2" data-theme="dark">
-              <div className="text-caption w-56">
-                深色樣式——常見於 OverflowIndicator 顯示溢出清單(+3 more 的 hover 展開)
+              <div className="text-caption w-56 flex flex-col gap-1">
+                <span>林思妤</span>
+                <span>陳柏宇</span>
+                <span>Aisha Khan</span>
               </div>
             </HoverCardContent>
           </HoverCard>

package/src/components/HoverCard/hover-card.principles.stories.tsx

@@ -97,7 +97,12 @@ export const UsageGuidance: Story = {
         >
           <HoverCard>
             <HoverCardTrigger asChild>
-              <a className="text-primary underline cursor-pointer inline-flex items-center gap-1">
+              <a
+                href="https://help.acme.com/user-manual"
+                target="_blank"
+                rel="noreferrer"
+                className="text-primary underline cursor-pointer inline-flex items-center gap-1"
+              >
                 使用者手冊 <ExternalLink size={12} />
               </a>
             </HoverCardTrigger>

package/src/components/HoverCard/hover-card.spec.md

@@ -22,7 +22,7 @@ Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
 **分類**：Internal primitive——不進 root barrel front-door、不裸用;DS 內由 Avatar(`hoverCard`)/ OverflowIndicator / ProfileCard 場景組合消費;consumer 需要時可經 per-component subpath 包裝並自行確認後使用(`.claude/rules/ui-development.md`「Root barrel front-door 排除」SSOT,internal ≠ 禁用)(frontmatter `isInternal`:root barrel 排除,storybook `Design System/Internal/HoverCard`)。
 
 - **是**：hover 顯示可互動內容（按鈕、連結、可選取文字——**滑鼠互動**；鍵盤進不了卡片，見「A11y 預設」）的浮層容器，定位為滑鼠 / focus 使用者的補充閱讀 surface
-- **不是**：Tooltip（純文字提示、不可互動、hover 離開即消失）；也不是鍵盤可操作的互動浮層（那是 Popover）
+- **不是**：Tooltip（純文字提示、**內容不可互動**；指標可短暫移到浮層屬 WCAG 1.4.13 hoverable grace，非「立即消失」）；也不是鍵盤可操作的互動浮層（那是 Popover）
 
 **Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
 
@@ -54,7 +54,7 @@ Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
 |---|---|---|
 | 觸發 | hover | hover |
 | **內容可互動** | 是——限滑鼠（Radix 設 content 內 tabbable node 為 `tabindex="-1"`，鍵盤不可達，見「A11y 預設」） | 否（純文字） |
-| 停留行為 | 滑鼠移到浮層上不消失 | 滑鼠離開 trigger 即消失 |
+| 停留行為 | 滑鼠可移到浮層互動不消失 | 滑鼠可短暫移到浮層（WCAG 1.4.13 grace，`tooltip.tsx` 未設 `disableHoverableContent`），但內容不可互動 |
 | 視覺樣式 | 由 consumer 決定（亮色 card 或深色 tooltip 風格皆可） | 統一深色背景 |
 | 典型用例 | ProfileCard、內容預覽、溢出清單 | icon 用途、shortcut、截斷文字補全 |
 

package/src/components/HoverCard/hover-card.tsx

@@ -85,8 +85,10 @@ export const hoverCardMeta = {
   },
   states: ['default'],
   tokens: {
-    bg: ['bg-surface-raised'],
-    fg: ['--foreground'],
+    // 2026-07-16 deep-audit A.1b:清 Phase-1 佔位 — HoverCard 為純行為 primitive,
+    // Content 不套任何 bg/fg(spec「純行為 primitive」段);bg-surface-raised 屬 consumer(ProfileCard)。
+    bg: [],
+    fg: [],
     ring: [],
   },
 } as const

package/src/components/InlineEdit/inline-edit.anatomy.stories.tsx

@@ -0,0 +1,184 @@
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { InlineEdit } from './inline-edit'
+import { Select } from '@/design-system/components/Select/select'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+
+// 就地編輯無 disabled 態的世界級對照(cite,per M22):
+//   MUI X isCellEditable/cellMode https://mui.com/x/react-data-grid/editing/
+//   AG Grid editable https://www.ag-grid.com/react-data-grid/cell-editing/
+//   Atlassian inline-edit readView/editView https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx
+//
+// InlineEdit 設計規格(anatomy)—— view ↔ edit 二態就地編輯 primitive。
+// Model A(2026-07-16):view 不自帶幾何 cva,委派控件 view mode / fieldViewGeometry helper;read↔edit 零跳。
+const meta: Meta<typeof InlineEdit> = {
+  title: 'Design System/Components/InlineEdit/設計規格',
+  component: InlineEdit,
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof InlineEdit>
+
+// ── shared UI ────────────────────────────────────────────────────────────────
+function Section({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <section className="mb-8">
+      <h3 className="mb-3 border-b border-divider pb-2 text-body-lg font-semibold text-foreground">{title}</h3>
+      {children}
+    </section>
+  )
+}
+function PropRow({ name, type, def, desc }: { name: string; type: string; def: string; desc: string }) {
+  return (
+    <tr className="border-b border-divider align-top">
+      <td className="py-2 pr-4 font-mono text-caption text-foreground">{name}</td>
+      <td className="py-2 pr-4 font-mono text-caption text-fg-secondary">{type}</td>
+      <td className="py-2 pr-4 font-mono text-caption text-fg-muted">{def}</td>
+      <td className="py-2 text-caption text-fg-secondary">{desc}</td>
+    </tr>
+  )
+}
+function Stateful({ value: initial, ...props }: Omit<React.ComponentProps<typeof InlineEdit>, 'onCommit'>) {
+  const [value, setValue] = React.useState(initial)
+  return <InlineEdit {...props} value={value} onCommit={setValue} />
+}
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="max-w-[720px]">
+      <Section title="定位">
+        <p className="text-body text-fg-secondary">
+          就地編輯 primitive:值平常以 <b>view 態</b>(純內容)呈現,滑鼠移入顯示灰底提示、點擊(或鍵盤 Enter)切成
+          <b> edit 態</b>(真正的 Field 控件)。與 DataTable cell 同一份就地編輯語義 —— 只有 <code>view ↔ edit</code> 兩態
+          + <code>editable</code> 判準閘,<b>無 disabled 態</b>(世界級就地編輯共識,cite 見檔頭)。
+        </p>
+      </Section>
+      <Section title="Model A —— view 幾何來源">
+        <p className="mb-2 text-body text-fg-secondary">
+          InlineEdit <b>不自帶</b> geometry cva(消 M17 重複)。view 幾何來源分兩路,read↔edit 零跳因兩態同一顆控件、只差 chrome:
+        </p>
+        <ul className="ml-5 list-disc text-body text-fg-secondary">
+          <li><b>值-格式化</b>(Select→Tag / 日期 / avatar):<code>renderRead</code> 委派 <code>{'<Control mode="view">'}</code>,
+            幾何 + 內部間距(多 tag gap / avatar↔label)皆由控件 view×default 提供。</li>
+          <li><b>純值 / 標題</b>(<code>as="h1"</code>):套 <code>fieldViewGeometry(size, multiline)</code> helper
+            (= view×default 幾何 SSOT:<code>px-field-px</code> + <code>min-h-field</code> + 多行 <code>py-2</code>)。</li>
+        </ul>
+      </Section>
+    </div>
+  ),
+}
+
+export const Inspector: Story = {
+  name: '屬性一覽',
+  render: () => (
+    <div className="max-w-[860px]">
+      <table className="w-full">
+        <thead>
+          <tr className="border-b-2 border-border text-left">
+            <th className="py-2 pr-4 text-caption font-semibold text-fg-muted">Prop</th>
+            <th className="py-2 pr-4 text-caption font-semibold text-fg-muted">型別</th>
+            <th className="py-2 pr-4 text-caption font-semibold text-fg-muted">預設</th>
+            <th className="py-2 text-caption font-semibold text-fg-muted">說明</th>
+          </tr>
+        </thead>
+        <tbody>
+          <PropRow name="value" type="T" def="—" desc="已提交的欄位值(view 顯示 / edit 初值)。泛型:string / number / string[] / PersonValue" />
+          <PropRow name="onCommit" type="(next: T) => void" def="—" desc="blur / Enter 且草稿有變更時提交" />
+          <PropRow name="editable" type="boolean" def="true" desc="false → view 無 hover 入口、無藍框、不可進 edit、不灰化(鎖定 = 純 view)" />
+          <PropRow name="renderRead" type="(v: T) => ReactNode" def="String(value)" desc="格式化 view;鐵律:渲染對應控件 mode='view',不可自刻" />
+          <PropRow name="renderEdit" type="(p) => ReactNode" def="Input/Textarea" desc="edit 控件(必 mode='edit');非 string 值必傳" />
+          <PropRow name="multiline" type="boolean" def="false" desc="Jira description 類:view 換行 + edit 用 Textarea(py-2 = Textarea)" />
+          <PropRow name="as" type="'span'|'h1'..'h6'|'p'|'div'" def="'span'" desc="view 語意標籤;標題保留文件大綱 a11y" />
+          <PropRow name="size" type="'sm'|'md'|'lg'" def="sm(fieldCtx cascade)" desc="接 fieldCtx.size;standalone fallback sm。靜態 fieldPreferredSize='sm' 讓外層 Field 自動收 sm" />
+          <PropRow name="label" type="string" def="—" desc="view 按鈕 aria-label(「編輯 {label}」)+ 控件 aria-label" />
+        </tbody>
+      </table>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="grid max-w-[720px] grid-cols-[140px_1fr] gap-x-6 gap-y-5">
+      <span className="text-body font-medium text-foreground">view(可編)</span>
+      <div><Stateful value="Fix flaky e2e test" label="標題" /></div>
+      <span className="text-body font-medium text-foreground">view(鎖定)</span>
+      <div><Stateful value="PROJ-482(系統產生)" label="編號" editable={false} /></div>
+      <span className="text-body font-medium text-foreground">多行</span>
+      <div><Stateful value={'第一行說明\n第二行說明(換行保留上下 padding)'} label="說明" multiline /></div>
+      <span className="text-body font-medium text-foreground">格式化(Tag)</span>
+      <div>
+        <Stateful
+          value="in-progress"
+          label="狀態"
+          renderRead={(v) => (
+            <Select mode="view" display="tag" size="sm" value={v as string} options={[
+              { value: 'in-progress', label: '進行中', tagVariant: 'blue' },
+              { value: 'done', label: '完成', tagVariant: 'green' },
+            ]} />
+          )}
+          renderEdit={(p) => (
+            <Select
+              autoFocus
+              display="tag"
+              size="sm"
+              defaultOpen
+              value={p.value as string}
+              aria-label={p['aria-label']}
+              options={[
+                { value: 'in-progress', label: '進行中', tagVariant: 'blue' },
+                { value: 'done', label: '完成', tagVariant: 'green' },
+              ]}
+              onChange={(next) => { p.onChange(next as string); p.commit() }}
+            />
+          )}
+        />
+      </div>
+      <span className="text-body font-medium text-foreground">空值</span>
+      <div><Stateful value="" label="負責人" placeholder="指派負責人…" /></div>
+    </div>
+  ),
+}
+
+// auto-sm 靠 Field 偵測 child 靜態 `fieldPreferredSize`(對齊 detectControlLayout 讀 fieldLayout)——
+//   **必 InlineEdit 為 Field 直接子**(包一層 wrapper 元件會遮蔽靜態,Field 偵測不到 → 退回 md)。
+function CascadeDemo() {
+  const [title, setTitle] = React.useState('Fix flaky checkout e2e test')
+  const [owner, setOwner] = React.useState('')
+  return (
+    <div className="w-[420px] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]">
+      {/* Field 偵測 InlineEdit 靜態 fieldPreferredSize='sm' → 未指定 size 自動收 sm;
+          vertical orientation → InlineEdit -mx 讓 view 值落 FieldLabel 同左緣 */}
+      <Field className="mb-4">
+        <FieldLabel>任務標題</FieldLabel>
+        <InlineEdit value={title} onCommit={setTitle} label="任務標題" />
+      </Field>
+      <Field>
+        <FieldLabel>負責人</FieldLabel>
+        <InlineEdit value={owner} onCommit={setOwner} label="負責人" placeholder="指派…" />
+      </Field>
+    </div>
+  )
+}
+export const InFieldCascade: Story = {
+  name: '包進表單欄位:尺寸自動收斂與左緣對齊',
+  render: () => <CascadeDemo />,
+}
+
+export const Accessibility: Story = {
+  name: '無障礙',
+  render: () => (
+    <div className="max-w-[640px] text-body text-fg-secondary">
+      <ul className="ml-5 list-disc space-y-1">
+        <li>view 疊隱形 <code>{'<button aria-label="編輯 {label}">'}</code> —— Tab 可聚焦、Enter/Space 進 edit;
+          與 <code>as="h1"</code> 分離(HTML 不允許 heading 巢狀於 button),標題大綱不破壞。</li>
+        <li>鍵盤 focus 顯 <code>border-primary</code> 藍框(<code>focus-visible</code>,僅鍵盤);滑鼠點擊不顯藍框。</li>
+        <li>結算焦點路徑分流:鍵盤 Enter/Esc → 焦點回 view 按鈕;滑鼠 blur → 純 view 不搶焦。</li>
+        <li><code>editable=false</code>:不渲染 Pressable,鍵盤跳過,語意 = 唯讀值(非 disabled)。</li>
+        <li>edit 態 = 真正的 Field 控件,繼承其 a11y(Input/Textarea/Select 各自 ARIA)。</li>
+      </ul>
+    </div>
+  ),
+}

package/src/components/InlineEdit/inline-edit.principles.stories.tsx

@@ -0,0 +1,142 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — 本檔 brand 引用(Jira/Linear/Notion)為真實業務場景示意(mindset #4),非 URL-citable 的 DS 行為 benchmark claim。
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { InlineEdit } from './inline-edit'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+import { Input } from '@/design-system/components/Input/input'
+
+/**
+ * InlineEdit 設計原則(principles)—— 何時用 / 何時不用 / 近親分界 / 內容準則。
+ */
+const meta: Meta<typeof InlineEdit> = {
+  title: 'Design System/Components/InlineEdit/設計原則',
+  component: InlineEdit,
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof InlineEdit>
+
+function Card({ tone, title, children }: { tone: 'do' | 'dont' | 'neutral'; title: string; children: React.ReactNode }) {
+  const ring = tone === 'do' ? 'border-success' : tone === 'dont' ? 'border-error' : 'border-border'
+  const tag = tone === 'do' ? '✓ 適用' : tone === 'dont' ? '✕ 不適用' : '—'
+  const tagColor = tone === 'do' ? 'text-success' : tone === 'dont' ? 'text-error' : 'text-fg-muted'
+  return (
+    <div className={`rounded-lg border ${ring} bg-surface p-[var(--layout-space-loose)]`}>
+      <p className={`mb-1 text-caption font-semibold ${tagColor}`}>{tag}</p>
+      <p className="mb-2 text-body font-medium text-foreground">{title}</p>
+      <div className="text-body text-fg-secondary">{children}</div>
+    </div>
+  )
+}
+function Stateful({ value: initial, ...props }: Omit<React.ComponentProps<typeof InlineEdit>, 'onCommit'>) {
+  const [value, setValue] = React.useState(initial)
+  return <InlineEdit {...props} value={value} onCommit={setValue} />
+}
+
+export const WhenToUse: Story = {
+  name: '何時用',
+  render: () => (
+    <div className="grid max-w-[860px] grid-cols-2 gap-4">
+      <Card tone="do" title="詳情面板的可編欄位">
+        Jira / Linear issue 詳情、Notion property —— 值平常是純內容,原地點擊即可改,不跳表單。
+        <div className="mt-3"><Stateful value="Fix flaky checkout e2e test" label="標題" /></div>
+      </Card>
+      <Card tone="do" title="標題型就地編輯">
+        頁面 / 文件標題 <code>as="h1"</code>,保留文件大綱,同時可點擊改名。
+        <div className="mt-3"><Stateful as="h2" value="Q3 產品路線圖" readClassName="text-h5 font-bold" label="文件標題" /></div>
+      </Card>
+      <Card tone="do" title="唯讀值同場並列(editable=false)">
+        系統產生值(訂單編號、建立時間)與可編欄位並列 —— 用 <code>editable=false</code>,視覺一致但無編輯入口、不灰化。
+        <div className="mt-3"><Stateful value="PROJ-482" label="編號" editable={false} /></div>
+      </Card>
+      <Card tone="do" title="格式化值就地編輯">
+        狀態 Tag / 日期 / 負責人頭像 —— <code>renderRead</code> 委派控件 view mode,edit 換該控件 edit mode。
+      </Card>
+    </div>
+  ),
+}
+
+export const WhenNotToUse: Story = {
+  name: '何時不用',
+  render: () => (
+    <div className="grid max-w-[860px] grid-cols-2 gap-4">
+      <Card tone="dont" title="整張表單填寫">
+        新增 / 建立流程要一次填多欄 —— 用 <code>&lt;Field&gt; + 控件</code> 明確表單,不用逐欄就地編輯。
+        <div className="mt-3">
+          <Field><FieldLabel>Email</FieldLabel><Input placeholder="you@company.com" /></Field>
+        </div>
+      </Card>
+      <Card tone="dont" title="永久唯讀、不同場可編欄位">
+        純展示頁(唯讀報表)—— 直接用 <code>&lt;Control mode="view"&gt;</code> 或純文字,不需就地編輯的 hover 入口成本。
+      </Card>
+      <Card tone="dont" title="需要即時驗證 / 複雜互動">
+        密碼、需即時錯誤回饋、multi-step 的欄位 —— 用完整 Field + FieldError,不塞進二態就地編輯。
+      </Card>
+      <Card tone="dont" title="條件停用的欄位">
+        「選國家前城市不可填」這種表單條件停用 —— 用 <code>&lt;Field mode="disabled"&gt;</code>,不是 InlineEdit
+        (就地編輯無 disabled 態;鎖定 = editable=false 純 view)。
+      </Card>
+    </div>
+  ),
+}
+
+export const VsControlView: Story = {
+  name: '近親分界:就地編輯 vs 唯讀展示 vs 表單',
+  render: () => (
+    <div className="max-w-[820px]">
+      <table className="w-full">
+        <thead>
+          <tr className="border-b-2 border-border text-left text-caption font-semibold text-fg-muted">
+            <th className="py-2 pr-4">用它</th>
+            <th className="py-2 pr-4">場景</th>
+            <th className="py-2">可編 / 入口</th>
+          </tr>
+        </thead>
+        <tbody className="text-body text-fg-secondary">
+          <tr className="border-b border-divider align-top">
+            <td className="py-2 pr-4 font-medium text-foreground">InlineEdit</td>
+            <td className="py-2 pr-4">詳情面板、可原地改的值</td>
+            <td className="py-2">view↔edit,hover 入口(editable=true)</td>
+          </tr>
+          <tr className="border-b border-divider align-top">
+            <td className="py-2 pr-4 font-medium text-foreground">InlineEdit editable=false</td>
+            <td className="py-2 pr-4">與可編欄位並列的唯讀值(訂單編號)</td>
+            <td className="py-2">純 view,無入口、不灰化</td>
+          </tr>
+          <tr className="border-b border-divider align-top">
+            <td className="py-2 pr-4 font-medium text-foreground">{'<Control mode="view">'}</td>
+            <td className="py-2 pr-4">永久唯讀展示頁的值</td>
+            <td className="py-2">純展示,無互動</td>
+          </tr>
+          <tr className="align-top">
+            <td className="py-2 pr-4 font-medium text-foreground">{'<Field> + 控件'}</td>
+            <td className="py-2 pr-4">表單填寫(一次多欄)</td>
+            <td className="py-2">恆 edit,label + error</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  ),
+}
+
+export const ContentGuidelines: Story = {
+  name: '內容準則',
+  render: () => (
+    <div className="grid max-w-[860px] grid-cols-2 gap-4">
+      <Card tone="do" title="placeholder 用行動語氣">
+        空值提示寫「指派負責人…」「新增說明…」,告訴使用者能做什麼,而非「無」。
+        <div className="mt-3"><Stateful value="" label="負責人" placeholder="指派負責人…" /></div>
+      </Card>
+      <Card tone="do" title="label 傳人類可讀名稱">
+        <code>label</code> 組出 aria-label「編輯 負責人」—— 傳欄位真名,別傳代號。
+      </Card>
+      <Card tone="dont" title="別把格式化 Tag 自刻">
+        狀態值要顯示 Tag,<code>renderRead</code> 必須渲染 <code>&lt;Select mode="view" display="tag"&gt;</code> ——
+        自己拼 <code>&lt;Tag&gt;</code> 會與 edit 態格式漂移。
+      </Card>
+      <Card tone="neutral" title="多行用 multiline">
+        Jira description 類長文字傳 <code>multiline</code> —— view 保留換行、edit 換 Textarea,上下 padding 一致。
+      </Card>
+    </div>
+  ),
+}