@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/src/components/DescriptionList/description-list.anatomy.stories.tsx

@@ -0,0 +1,252 @@
+// @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.
+// @anatomy-exempt: inspector 規格表格(token / prop 對照)用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+// @anatomy-rationale:
+//   ColorMatrix N/A — 純 typography 元件,色彩固定為 fg-secondary(label)+
+//     foreground(value),無 variant × state 色彩矩陣。色彩 token 已於
+//     Overview「Typography(閱讀模式)」段列出。
+//   SizeMatrix N/A — 不提供 size prop;大小固定 text-body(14px reading mode),
+//     由 layout(cols / direction / divided)而非 size 決定差異。ColsMatrix 已
+//     涵蓋 layout 變化。
+import type { Meta, StoryObj } from '@storybook/react'
+import { DescriptionList, DescriptionItem } from './description-list'
+import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta = {
+  title: 'Design System/Components/DescriptionList/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>DescriptionList 是 `dl / dt / dd` HTML 語義元件——每個 DescriptionItem 是一組 label(dt)+ value(dd)配對。對齊 Atlassian / Polaris 慣例。CSS grid 容器,`cols` prop 控制欄數。</Desc>
+        <div className="border border-border rounded-lg p-4 max-w-md">
+          <DescriptionList>
+            <DescriptionItem label="Email">user@example.com</DescriptionItem>
+            <DescriptionItem label="團隊">Engineering</DescriptionItem>
+            <DescriptionItem label="時區">UTC+8(台北)</DescriptionItem>
+            <DescriptionItem label="建立時間">2026-04-18</DescriptionItem>
+          </DescriptionList>
+        </div>
+      </div>
+
+      <div>
+        <H3>Typography(閱讀模式)</H3>
+        <Desc>層級靠色彩區分,不靠字體大小。兩者都是 14px,行高 1.5(閱讀模式)。</Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Part</Th><Th>HTML</Th><Th>Typography</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>label</Td><Td mono>&lt;dt&gt;</Td><Td mono>text-body(14px)+ text-fg-secondary(neutral-8)</Td></tr>
+              <tr><Td mono>value</Td><Td mono>&lt;dd&gt;</Td><Td mono>text-body(14px)+ text-foreground(neutral-9)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>間距</H3>
+        <Desc>items 之間垂直間距走 `--layout-space-tight` token(density-aware)——切 density 自動適配,避免硬寫 px / py-N 脫鉤 token;label → value(同 item 內)走 `--item-gap-label-desc-reading`(2px,見下表 row 1)。</Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Direction</Th><Th>位置</Th><Th>Value</Th><Th>Rationale</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>vertical</Td><Td>label → value(同 item 內)</Td><Td mono>--item-gap-label-desc-reading(2px)</Td><Td>極小間距,視覺上 label 與 value 緊密配對(dt body + dd body → reading token)</Td></tr>
+              <tr><Td mono>vertical</Td><Td>items 之間垂直 gap</Td><Td mono>gap-y-[var(--layout-space-tight)]</Td><Td>density-aware;Gestalt proximity 群組</Td></tr>
+              <tr><Td mono>vertical</Td><Td>columns 之間水平 gap</Td><Td mono>gap-x-4(16px)</Td><Td>cols &gt; 1 時欄間距</Td></tr>
+              <tr><Td mono>horizontal(divided=false)</Td><Td>items 之間垂直 gap</Td><Td mono>mb-[var(--layout-space-tight)] last:mb-0</Td><Td>等同 vertical 的 items gap,density-aware</Td></tr>
+              <tr><Td mono>horizontal(divided=false)</Td><Td>label ↔ value</Td><Td mono>justify-between + gap-4</Td><Td>最小 16px,content 之間自然拉開</Td></tr>
+              <tr><Td mono>horizontal(divided=true)</Td><Td>每 item 上下 padding</Td><Td mono>py-[var(--layout-space-tight)]</Td><Td>density-aware,形成 cell-like row 高度;row 間有 border-b border-divider 對齊格線</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const Inspector: Story = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: { description: { story: '右側 Controls 切 props 即時 render,取代 Figma inspect。調整 `cols` / `direction` / `divided` 看 CSS grid 配置變化。' } },
+  },
+  args: {
+    cols: 2,
+    direction: 'vertical',
+    divided: false,
+  },
+  argTypes: {
+    cols: { control: 'radio', options: [1, 2, 3] },
+    direction: { control: 'radio', options: ['vertical', 'horizontal'] },
+    divided: { control: 'boolean', description: 'horizontal 模式下,每個 item 下加 border-b 對齊 rows(長列表建議開)' },
+  },
+  render: (args) => (
+    <div className="border border-border rounded-lg p-4 max-w-lg">
+      <DescriptionList {...args}>
+        <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
+        <DescriptionItem label="團隊">Engineering</DescriptionItem>
+        <DescriptionItem label="職稱">Design Engineer</DescriptionItem>
+        <DescriptionItem label="時區">UTC+8(台北)</DescriptionItem>
+        <DescriptionItem label="建立時間">2026-04-18</DescriptionItem>
+        <DescriptionItem label="最後登入">2026-04-21 09:12</DescriptionItem>
+      </DescriptionList>
+    </div>
+  ),
+}
+
+export const ColsMatrix: Story = {
+  name: '欄數（1 / 2 / 3）',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>cols=1(預設,窄容器)</H3>
+        <Desc>垂直堆疊,適合 ProfileCard、sidebar detail 等窄容器。</Desc>
+        <div className="border border-border rounded-lg p-4 max-w-xs">
+          <DescriptionList cols={1}>
+            <DescriptionItem label="Email">user@example.com</DescriptionItem>
+            <DescriptionItem label="團隊">Engineering</DescriptionItem>
+            <DescriptionItem label="時區">UTC+8(台北)</DescriptionItem>
+          </DescriptionList>
+        </div>
+      </div>
+
+      <div>
+        <H3>cols=2(中等寬度)</H3>
+        <Desc>兩欄並排,適合 ProfileCard info fields / detail panel。</Desc>
+        <div className="border border-border rounded-lg p-4 max-w-lg">
+          <DescriptionList cols={2}>
+            <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
+            <DescriptionItem label="職稱">Design Engineer</DescriptionItem>
+            <DescriptionItem label="Email">user@example.com</DescriptionItem>
+            <DescriptionItem label="電話">0912-345-678</DescriptionItem>
+            <DescriptionItem label="團隊">Engineering</DescriptionItem>
+            <DescriptionItem label="時區">UTC+8</DescriptionItem>
+          </DescriptionList>
+        </div>
+      </div>
+
+      <div>
+        <H3>cols=3(寬容器)</H3>
+        <Desc>三欄,適合寬 detail panel 顯示大量屬性。</Desc>
+        <div className="border border-border rounded-lg p-4 max-w-3xl">
+          <DescriptionList cols={3}>
+            <DescriptionItem label="訂單編號">#20260418-001</DescriptionItem>
+            <DescriptionItem label="狀態">已出貨</DescriptionItem>
+            <DescriptionItem label="建立時間">2026-04-18 10:35</DescriptionItem>
+            <DescriptionItem label="付款方式">信用卡</DescriptionItem>
+            <DescriptionItem label="配送方式">宅配</DescriptionItem>
+            <DescriptionItem label="預計送達">2026-04-20</DescriptionItem>
+            <DescriptionItem label="商品">Q1 行銷套組</DescriptionItem>
+            <DescriptionItem label="數量">3</DescriptionItem>
+            <DescriptionItem label="總金額">NT$ 2,490</DescriptionItem>
+          </DescriptionList>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>空值呈現 — 一律用 `—` 字元(em dash)</H3>
+        <Desc>
+          DescriptionList 是唯讀資訊展示,空值不留空白(會讓使用者以為資料沒載入完)。一律用 em dash
+          (`—`)明確表達「有查過,但這個欄位目前沒值」。對齊 Atlassian / Polaris / GitHub 的資訊卡慣例。
+        </Desc>
+        <div className="border border-dashed border-divider rounded-md p-4 max-w-md">
+          <DescriptionList cols={2}>
+            <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
+            <DescriptionItem label="職稱"><span className="text-fg-muted">—</span></DescriptionItem>
+            <DescriptionItem label="Email">user@example.com</DescriptionItem>
+            <DescriptionItem label="電話"><span className="text-fg-muted">—</span></DescriptionItem>
+            <DescriptionItem label="團隊">Engineering</DescriptionItem>
+            <DescriptionItem label="直屬主管"><span className="text-fg-muted">—</span></DescriptionItem>
+          </DescriptionList>
+        </div>
+        <p className="text-footnote text-fg-muted mt-3">
+          空值不應該用「N/A」/「暫無」等字串——不同 consumer 會選不同字,破壞視覺一致。一律 em dash。
+        </p>
+      </div>
+
+      <div>
+        <H3>長 value — 自然換行,撐高該 grid cell</H3>
+        <Desc>
+          `value` 是自然流文字,超過欄寬自然換行(CSS grid 會讓該 row 的 cell 變高,其他 cell 保持 label
+          top-aligned)。不使用 truncate——value 是被讀的內容,截斷會讓使用者漏資訊。
+        </Desc>
+        <div className="border border-dashed border-divider rounded-md p-4 max-w-md">
+          <DescriptionList cols={2}>
+            <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
+            <DescriptionItem label="職稱">Senior Staff Principal Engineer, Design Systems</DescriptionItem>
+            <DescriptionItem label="辦公地點">Taipei, Taiwan</DescriptionItem>
+            <DescriptionItem label="Email">very.long.email.address@subdomain.example.com</DescriptionItem>
+          </DescriptionList>
+        </div>
+      </div>
+
+      <div>
+        <H3>多行 value(地址 / 介紹 / 摘要)</H3>
+        <Desc>
+          Value 接受任何 ReactNode,包括多行文字。`dd` 保持 top-aligned,label 垂直靠上。
+          適合展示地址、人物介紹、商品描述等需多行的資訊。
+        </Desc>
+        <div className="border border-dashed border-divider rounded-md p-4 max-w-md">
+          <DescriptionList cols={1}>
+            <DescriptionItem label="公司地址">
+              台北市信義區忠孝東路五段 68 號 18 樓<br />
+              Taipei 110, Taiwan<br />
+              電話:02-2345-6789
+            </DescriptionItem>
+            <DescriptionItem label="產品介紹">
+              本產品採用最新 AMOLED 螢幕,支援 120Hz 高刷新率。
+              支援 IP68 防水防塵。續航力一整天,最快 45W 充電。
+            </DescriptionItem>
+          </DescriptionList>
+        </div>
+      </div>
+
+      <div>
+        <H3>結合 ReactNode value(Tag / Badge / Link)</H3>
+        <Desc>
+          `value` 可放任何 ReactNode——Tag(狀態)、Badge(計數)、Link(相關文件)。型別是寬鬆的
+          `ReactNode`,支援組合。
+        </Desc>
+        <div className="border border-dashed border-divider rounded-md p-4 max-w-md">
+          <DescriptionList cols={1}>
+            <DescriptionItem label="訂單狀態">
+              <span className="inline-flex items-center gap-1 text-success">
+                <span className="w-2 h-2 rounded-full bg-success" />
+                已出貨
+              </span>
+            </DescriptionItem>
+            <DescriptionItem label="物流追蹤">
+              <a href="#" className="text-primary hover:text-primary-hover underline">
+                FedEx #1234567890
+              </a>
+            </DescriptionItem>
+          </DescriptionList>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙',
+  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">{"詳 `description-list.spec.md`「無障礙」段。摘要:\n\n- 語意 HTML:外層 <dl>,每組 <dt>(term)+ <dd>(description)— screen reader 讀「term X, description Y」配對敘事\n- DT/DD 配對:DescriptionItem 強制一組配對,不分開暴露 <dt>/<dd> primitive\n- 空值:consumer 傳 — 占位(SR 讀出長破折號,比空 <dd> 明確)\n- 多欄 cols>1:視覺 grid、DOM 仍 item 順序,SR 依 DOM 敘事\n- 無互動:純唯讀呈現,無 keyboard / focus state(無 ARIA 補強需求,語意由原生 dl/dt/dd 承載)"}</p>
+    </div>
+  ),
+}

package/src/components/DescriptionList/description-list.principles.stories.tsx

@@ -0,0 +1,309 @@
+// @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 React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { DescriptionList, DescriptionItem } from './description-list'
+import { Input } from '@/design-system/components/Input/input'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+import { Button } from '@/design-system/components/Button/button'
+import { Tag } from '@/design-system/components/Tag/tag'
+
+const meta: Meta = {
+  title: 'Design System/Components/DescriptionList/設計原則',
+  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-col gap-4">{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>
+)
+
+const Frame = ({ children, className }: { children: React.ReactNode; className?: string }) => (
+  <div className={`border border-border rounded-lg p-4 ${className ?? ''}`}>{children}</div>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── WhenToUse — 何時使用 DescriptionList ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsDataTableRule(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>適合 DescriptionList 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" name="使用者個資"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">使用者個資</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" name="產品規格"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">產品規格</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" name="訂單明細"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">訂單明細</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" name="詳情面板"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">詳情面板</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" 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「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+    </div>
+
+      {/* vs 近親 — VsDataTableRule — 原 VsDataTableRule */}
+      <div>
+      <Rule
+        title="DescriptionList — 單一實體的屬性列表(key-value 配對)"
+        note="每一行是同一個對象(使用者 / 訂單 / 商品)的不同屬性(姓名 / email / 時區)。讀取模式,不支援排序、篩選、多選"
+      >
+        <Frame className="max-w-md">
+          <div className="text-body font-medium mb-2">使用者資料</div>
+          <DescriptionList cols={1}>
+            <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
+            <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
+            <DescriptionItem label="職稱">Design Engineer</DescriptionItem>
+          </DescriptionList>
+        </Frame>
+        <Label>↑ 「一個使用者」的多個屬性 → DescriptionList(語意:dl/dt/dd)</Label>
+      </Rule>
+
+      <Rule
+        title="DataTable — 多個同結構實體的集合(多 row)"
+        note="每一 row 是不同實體、同樣欄位結構。需要排序、篩選、分頁 → DataTable,不是 DescriptionList"
+      >
+        <Frame className="max-w-xl">
+          <table className="w-full text-body border-collapse">
+            <thead>
+              <tr className="text-fg-secondary text-left">
+                <th className="pb-2 font-normal">姓名</th>
+                <th className="pb-2 font-normal">Email</th>
+                <th className="pb-2 font-normal">團隊</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr className="border-t border-divider">
+                <td className="py-2">Ada Chen</td>
+                <td className="py-2">ada.chen@example.com</td>
+                <td className="py-2">Design</td>
+              </tr>
+              <tr className="border-t border-divider">
+                <td className="py-2">王小明</td>
+                <td className="py-2">ming@example.com</td>
+                <td className="py-2">Engineering</td>
+              </tr>
+            </tbody>
+          </table>
+        </Frame>
+        <Label>↑ 「多個使用者」的同結構屬性 → DataTable(需要排序 / 篩選)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 用 DescriptionList 展示多筆同結構資料"
+        note="DescriptionList 的 dt 重複 = 視覺噪音,且無法排序 / 篩選 / 分頁。使用者眼睛掃不到對齊點 → 難比較"
+      >
+        <Frame className="max-w-md">
+          <DescriptionList cols={1}>
+            <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
+            <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
+            <DescriptionItem label="姓名">王小明</DescriptionItem>
+            <DescriptionItem label="Email">ming@example.com</DescriptionItem>
+            <DescriptionItem label="姓名">林大華</DescriptionItem>
+            <DescriptionItem label="Email">dahua@example.com</DescriptionItem>
+          </DescriptionList>
+        </Frame>
+        <Label warn>↑ 「姓名 / Email」重複三次 — table 式資料應改用 DataTable</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const LayoutRule: Story = {
+  name: '直式 vs 橫式（欄數對照）',
+  render: () => (
+    <div>
+      <Rule
+        title="cols=1(vertical stack)— 長清單、窄容器、mobile-friendly"
+        note="label 在上、value 在下的垂直堆疊 → 適合 sidebar、ProfileCard、mobile detail view。Value 可以佔滿整行寬,長文字不壓迫"
+      >
+        <Frame className="max-w-xs">
+          <DescriptionList cols={1}>
+            <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
+            <DescriptionItem label="職稱">Senior Design Engineer</DescriptionItem>
+            <DescriptionItem label="團隊">Design Systems</DescriptionItem>
+            <DescriptionItem label="時區">UTC+8(台北)</DescriptionItem>
+          </DescriptionList>
+        </Frame>
+        <Label>↑ 窄容器(320px)時垂直堆疊 — 不會因為兩欄而壓縮 value</Label>
+      </Rule>
+
+      <Rule
+        title="cols=2 / 3(grid)— 短對比、desktop 寬容器、可快速掃視"
+        note="多個屬性並排 → 適合 detail panel、訂單摘要、產品規格。使用者眼睛可以水平掃視比較 — 但 value 必須短(一行內),不然會破壞 grid 對齊"
+      >
+        <Frame className="max-w-2xl">
+          <DescriptionList cols={2}>
+            <DescriptionItem label="訂單編號">#20260418-A241</DescriptionItem>
+            <DescriptionItem label="狀態">已出貨</DescriptionItem>
+            <DescriptionItem label="建立時間">2026-04-18</DescriptionItem>
+            <DescriptionItem label="預計送達">2026-04-20</DescriptionItem>
+            <DescriptionItem label="付款方式">信用卡</DescriptionItem>
+            <DescriptionItem label="總金額">NT$ 10,080</DescriptionItem>
+          </DescriptionList>
+        </Frame>
+        <Label>↑ 寬容器(700px+)並排展示 — 使用者可快速對照多個屬性</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 窄容器硬塞多欄 → value 被擠爆"
+        note="cols 數量要配合容器寬度。窄容器(<400px)硬塞 2 欄會讓 value 斷行、視覺節奏亂掉"
+      >
+        <Frame className="max-w-xs">
+          <DescriptionList cols={2}>
+            <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
+            <DescriptionItem label="職稱">Senior Design Engineer</DescriptionItem>
+          </DescriptionList>
+        </Frame>
+        <Label warn>↑ 窄容器配 cols=2 → email 與職稱都被壓到斷行,可讀性差</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const LabelAlignmentRule: Story = {
+  name: '標籤 對齊 — 一律左對齊（堆疊）',
+  render: () => (
+    <div>
+      <Rule
+        title="本系統採 stacked(label 在上、value 在下)— label 左對齊"
+        note="對齊 Atlassian / Shopify Polaris / Stripe 慣例——label 與 value 垂直堆疊,兩者都左對齊。閱讀節奏由上往下、由左往右,不需視線左右跳動。這是 vertical(預設)模式的結構;label 左 / value 右的 metadata 列改用既有 `direction=&quot;horizontal&quot;` prop(見 spec「Direction」段)"
+      >
+        <Frame className="max-w-md">
+          <DescriptionList cols={2}>
+            <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
+            <DescriptionItem label="職稱">Design Engineer</DescriptionItem>
+            <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
+            <DescriptionItem label="電話">0912-345-678</DescriptionItem>
+          </DescriptionList>
+        </Frame>
+        <Label>↑ 每一組:label(neutral-8)在上,value(neutral-9)在下,同左對齊</Label>
+      </Rule>
+
+      <Rule
+        title="層級靠色彩,不靠字體大小"
+        note="label 與 value 皆為 14px,視覺層級由 text-fg-secondary(label)和 text-foreground(value)的對比建立。這讓閱讀流暢,不會因字體大小落差讓 label 喧賓奪主"
+      >
+        <Frame className="max-w-md">
+          <DescriptionList cols={1}>
+            <DescriptionItem label="此 label 是 neutral-8(text-fg-secondary)">
+              此 value 是 neutral-9(text-foreground)
+            </DescriptionItem>
+          </DescriptionList>
+        </Frame>
+      </Rule>
+
+      <Rule
+        title="❌ 不要自己用 flex 改 horizontal layout"
+        note="手刻 flex 模擬 label 左 / value 右 → 失去 dl/dt/dd 語意,且多欄配置下 grid 對齊錯亂。有此需求 → 用既有 `direction=&quot;horizontal&quot;` prop(dl/dt/dd 語意完整保留,見 showcase「水平佈局」story),不要自組 layout"
+      >
+        <Frame className="max-w-md">
+          <div className="flex justify-between py-1">
+            <span className="text-body text-fg-secondary">姓名</span>
+            <span className="text-body">Ada Chen</span>
+          </div>
+          <div className="flex justify-between py-1">
+            <span className="text-body text-fg-secondary">Email</span>
+            <span className="text-body">ada.chen@example.com</span>
+          </div>
+        </Frame>
+        <Label warn>
+          ↑ 這是自訂 layout 模擬 key-right-value-left → 不是 DescriptionList,也無 dl/dt/dd 語義
+        </Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const NoInteractionRule: Story = {
+  name: '唯讀:不放互動元件',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ value 可以是 ReactNode(Tag / Badge / Link),但必須是展示性質"
+        note="Tag 顯示狀態、Badge 顯示計數、Link 指向相關資源——這些都是「讀完就知道」的展示元件,不需使用者操作 DescriptionList 本身"
+      >
+        <Frame className="max-w-md">
+          <DescriptionList cols={1}>
+            <DescriptionItem label="訂單狀態">
+              <Tag>已出貨</Tag>
+            </DescriptionItem>
+            <DescriptionItem label="物流追蹤">
+              <a href="#" className="text-primary hover:text-primary-hover underline">
+                FedEx #1234567890
+              </a>
+            </DescriptionItem>
+            <DescriptionItem label="預計送達">2026-04-20</DescriptionItem>
+          </DescriptionList>
+        </Frame>
+      </Rule>
+
+      <Rule
+        title="❌ 需要編輯 → 用 Field 系統,不是 DescriptionList"
+        note="DescriptionList 是唯讀展示。若使用者要能改(Input / Select / DatePicker),改用 Field — 有明確的 label、input、validation、submit 語義"
+      >
+        <div className="flex flex-col gap-3 max-w-md">
+          <Field>
+            <FieldLabel>Email</FieldLabel>
+            <Input defaultValue="ada.chen@example.com" />
+          </Field>
+          <Field>
+            <FieldLabel>職稱</FieldLabel>
+            <Input defaultValue="Design Engineer" />
+          </Field>
+        </div>
+        <Label>↑ 可編輯欄位 → Field 系統;唯讀屬性 → DescriptionList</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 在 value 放 Button / Input 等互動元件"
+        note="DescriptionList 的語義是唯讀屬性展示。放 Button 會讓 screen reader 在 dd 內讀到 button → 使用者混淆(這是一個屬性還是一個動作?)。若要「讀取為主 + 偶爾編輯」,改用 Field 的 read-only mode 或 inline-edit pattern"
+      >
+        <Frame className="max-w-md">
+          <DescriptionList cols={1}>
+            <DescriptionItem label="Email">
+              <div className="flex items-center gap-2">
+                <span>ada.chen@example.com</span>
+                <Button variant="text" size="xs">編輯</Button>
+              </div>
+            </DescriptionItem>
+          </DescriptionList>
+        </Frame>
+        <Label warn>
+          ↑ dd 內放 Button 破壞「唯讀屬性」語義 → 改用 Field(read-only mode + inline edit)
+        </Label>
+      </Rule>
+      {/* 「多筆同結構 → DataTable」的 ❌ 對照由「使用指引」story(vs DataTable 段)擁有,不在此重複 */}
+    </div>
+  ),
+}