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

package/src/components/DescriptionList/description-list.spec.md

@@ -10,11 +10,10 @@ benchmark:
   - Polaris DescriptionList: github.com/Shopify/polaris/tree/main/polaris-react/src/components/DescriptionList
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # DescriptionList 設計原則
 
-唯讀 label + value 展示元件，用於呈現結構化的屬性資訊。HTML 語義為 `dl` + `dt` + `dd`，對齊 Atlassian、Shopify Polaris 慣例。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+唯讀 label + value 展示元件，用於呈現結構化的屬性資訊。HTML 語義固定為 `dl` + `dt` + `dd`，讓屬性名稱與值保有原生 definition-list 關係。
 
 ## 定位
 
@@ -28,7 +27,7 @@ benchmark:
 ## 何時用
 
 - **Profile / detail panel 的屬性列表**：使用者資料（Email / Phone / Role / Created at）
-- **NameCard 的 info fields**：HoverCard 內的次要資訊展示
+- **ProfileCard 的 info fields**：HoverCard 內的次要資訊展示
 - **固定資訊展示**：產品規格、訂單明細、設定值（唯讀）
 - **HTML 語義為 `dl` + `dt` + `dd`**：對 screen reader 明確表達「屬性-值」關係
 
@@ -44,14 +43,14 @@ benchmark:
 ## 結構
 
 - `DescriptionList`：外層 `dl`，vertical 模式為 CSS grid、horizontal 模式為 flex column
-- `DescriptionItem`：一組 `dt`（label）+ `dd`（value），透過 context 知道當前 direction 自動切 layout
+- `DescriptionItem`：一組 `dt`（label）+ `dd`（value），透過 context 知道當前 orientation 自動切 layout
 
-## Direction(2026-04-20 新增)
+## Orientation(2026-04-20 新增)
 
-| direction | Layout | 典型情境 | 世界級對照 |
+| orientation | Layout | 典型情境 | 世界級對照 |
 |-----------|--------|---------|-----------|
-| `vertical`(預設)| label 在上 / value 在下 | NameCard detail、sidebar 長 value(地址、bio) | Atlassian DescriptionList、Polaris DescriptionList |
-| `horizontal` | label 左 / value 右對齊 | **file info panel / 訂單詳情 / settings summary**(短 value 的 metadata 列) | Google Drive file info、Notion file panel、iOS Settings | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| `vertical`(預設)| label 在上 / value 在下 | ProfileCard detail、sidebar 長 value(地址、bio) | Atlassian DescriptionList、Polaris DescriptionList |
+| `horizontal` | label 左 / value 右對齊 | **file info panel / 訂單詳情 / settings summary**(短 value 的 metadata 列) | label 欄形成可掃描軸，value 保留較寬內容區 |
 
 **判斷法**:
 - value 預期長(多字、可能換行)→ vertical(讓 value 佔滿寬)
@@ -63,13 +62,13 @@ benchmark:
 
 ```tsx
 // 短 metadata 列,無需 divider
-<DescriptionList direction="horizontal">
+<DescriptionList orientation="horizontal">
   <DescriptionItem label="建立">2026-04-20</DescriptionItem>
   <DescriptionItem label="修改">2026-04-20</DescriptionItem>
 </DescriptionList>
 
 // 檔案資訊 — 多 row + key 長度不一 → divided 對齊格線
-<DescriptionList direction="horizontal" divided>
+<DescriptionList orientation="horizontal" divided>
   <DescriptionItem label="檔名">Q1 財報分析.xlsx</DescriptionItem>
   <DescriptionItem label="類型">application/vnd.xlsx</DescriptionItem>
   <DescriptionItem label="大小">1.2 MB</DescriptionItem>
@@ -78,37 +77,37 @@ benchmark:
 
 ## Typography（閱讀模式）
 
-層級靠色彩區分，不靠字體大小：
+層級靠色彩區分，不靠字體大小。Token 為 SSOT（具體 px / 色值由各 token spec 定義，本 spec 不硬寫）：
 
-- **label (dt)**：`text-body`（14px）`text-fg-secondary`（neutral-8）
-- **value (dd)**：`text-body`（14px）`text-foreground`（neutral-9）
+- **label (dt)**：`text-body` + `text-fg-secondary`
+- **value (dd)**：`text-body` + `text-foreground`
 - 兩者行高均為 1.5（閱讀模式）
 
 ## 間距
 
-### Vertical direction
+### Vertical orientation
 
 - **label → value**(同 item 內):`--item-gap-label-desc-reading` token(2px)——極小間距,視覺上 label 與 value 緊密配對
 - **items 之間垂直 gap**:`gap-y-[var(--layout-space-tight)]`——density-aware,跟隨系統密度設定
 - **columns 之間水平 gap**:`gap-x-4`(16px)
 
-### Horizontal direction(divided=false)
+### Horizontal orientation(divided=false)
 
 - **items 之間垂直 gap**:`mb-[var(--layout-space-tight)]` per item(last:mb-0)——density-aware,等同 vertical 的 items gap
 - label ↔ value 水平距離:`justify-between` + `gap-4`(最小 16px,content 之間拉開)
 
-### Horizontal direction(divided=true)
+### Horizontal orientation(divided=true)
 
 - 每個 item `py-[var(--layout-space-tight)]`(density-aware,形成 cell-like row 高度)
 - 每個 item 底部 `border-b border-divider`,`last:border-b-0`——row 之間視覺格線,key 長度不一時易於對齊掃描
 - **何時開 divided**:長列表(≥ 4 rows)/ key 長度差異大(短 vs 長 label 並排易顯亂) → divided 可對齊格線;短列表(< 4 rows)且 key 長度相近 → 不需 divided(border 反而噪音)
-- **世界級對照**:Google Drive 詳細資訊面板 / Notion 檔案屬性 / iOS Settings list rows,divided 是 file info / settings 的 canonical 呈現 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **使用判準**:divided 適用需要逐列掃描與明確 row boundary 的 file info / settings 表面；單一短清單不為裝飾而強加 divider
 
 ## Props
 
-### `direction`:vertical / horizontal
+### `orientation`:vertical / horizontal
 
-見上「Direction」段。
+見上「Orientation」段。
 
 ### `divided`:horizontal 專用 row divider
 
@@ -118,8 +117,8 @@ benchmark:
 
 | 值 | 用途 |
 |---|---|
-| `1`(預設)| 垂直堆疊,適合窄容器(NameCard、sidebar detail)|
-| `2` | 兩欄並排,適合中等寬度(NameCard info fields)|
+| `1`(預設)| 垂直堆疊,適合窄容器(ProfileCard、sidebar detail)|
+| `2` | 兩欄並排,適合中等寬度(ProfileCard info fields)|
 | `3` | 三欄,適合寬容器(detail panel)|
 
 Horizontal 模式永遠單欄(label + value 排列就是橫向,不再有欄概念)。
@@ -140,10 +139,12 @@ consumer 要在 DL 上方加 section heading(「基本資料」/「團隊資訊
 
 **為什麼相等**(Gestalt proximity canonical):heading 與下方 items 的關係是「擁有 / 歸屬」—— 相同距離讓視覺上 heading 與 items 形成一個群組。若拉大 gap(例 `mb-4`),heading 看似與 items「分離」,失去歸屬感;若縮小 gap(例 `mb-0`),heading 與 items 黏在一起無呼吸。
 
-**世界級對照**:iOS Settings / Notion properties / Ant Descriptions / Polaris Card.Section — heading 和 items 之間的 gap 皆與 item-item gap 相等(或近似)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Heading 與第一個 item 的 gap 使用同一 section rhythm，不另開一個只供 heading 的距離 tier；確切 token 由本元件 source 擁有。
 
 **Heading typography 建議**:`text-body font-medium text-foreground`(同 item label size,靠 weight 區分層級),不用加粗 / 放大 / 換色——讓 heading 是「標籤」不是「標題」。
 
+**常見誤解**:(1)「DL label 視覺像 FieldLabel 就拿來排表單」— `dl` 無 `<label for>` 對 input 的綁定,編輯場景一律 Field(見禁止事項第 1 條);(2)「section heading 是 DL 內建 prop」— heading 是 consumer pattern(DL 無 heading prop),需要分組時 consumer 自包並遵守上方 gap 規則。
+
 ---
 
 ## vs Field 系統
@@ -171,30 +172,31 @@ consumer 要在 DL 上方加 section heading(「基本資料」/「團隊資訊
 
 - **語意 HTML**:外層 `<dl>`,每組內 `<dt>` 為 term、`<dd>` 為 description——screen reader 會讀成「term X, description Y」對話,明確表達屬性-值關係
 - **DT / DD 配對**:每個 `<dt>` 必須有對應的 `<dd>`(不可孤立),否則 SR 敘事會中斷;元件內建一組 `DescriptionItem` 強制配對,不分開暴露 `<dt>` / `<dd>` primitive
-- **空值呈現**:value 空時以 `—` 占位(由 consumer 填入或於 DL 內 normalize),`text-fg-muted` 降低視覺重量;SR 會讀出「長破折號」,比空 `<dd>` 更明確
+- **空值呈現**:value 空時由 **consumer 自行傳入** `<span className="text-foreground">-</span>` 占位(半形 hyphen `-`,對齊 Field `EMPTY_DISPLAY` DS-wide 空值符號,2026-07-08 user 拍板「空值都用"-"⋯我從頭到尾哪裡有說要用全形的」;元件不自動 normalize——`<dd>` 直接 render `children`),`text-foreground`(同 value 色——「-」是不可編輯供檢視的值,非 placeholder 提示,2026-07-09 user 拍板)。**a11y known follow-up**:裸 `-` SR 敘事弱(半形連字號多被 SR 略過),宜補 `<span className="sr-only">無資料</span>` 或 `aria-label`,比空 `<dd>` 更明確
 - **多欄 `cols > 1`**:視覺為 grid 欄位,但 DOM 順序為 item 順序——SR 仍依 DOM 敘事(term1 → desc1 → term2 → desc2),不依視覺欄位;設計時確保 DOM 順序符合語意分組
-- **長值換行**:value 內長字串(URL / ID)以 `break-words` 處理,避免撐破 grid;不強制單行 truncate,長內容保留可讀完整性
+- **長值換行**:horizontal 模式的 value(`<dd>`)以 `break-all min-w-0` 處理,讓 URL / ID 等無空白長字串能斷行,避免撐破單列;vertical 模式 value 佔滿整欄寬,自然流文字依字詞換行(不強制單行 truncate,長內容保留可讀完整性)。若 vertical 模式需展示無空白長字串(連續英數 token),由 consumer 自行於該 value 加 `break-all`
 - **列表識別**:預設 `<dl>` 有部分瀏覽器 SR 不視為 list,若需明確 list 語意,DL 根容器可搭配 `role="list"` + `<div role="listitem">`(目前預設不加,保留標準 `<dl>` 語意,consumer 可自行加 role 覆蓋)
 
 ---
 
-## 為何無 Inspector / ColorMatrix / SizeMatrix
+## 為何無 ColorMatrix / SizeMatrix
 
 DescriptionList 是**唯讀 label / value 資料呈現**(非互動 / 非 variant 驅動):
 
-- **無 Inspector**:DL 的決策維度是 columns(單欄 / 雙欄 / 多欄)已在 `ColsMatrix` 覆蓋。互動 Inspector 無進一步 prop(value 呈現由資料決定,非 prop 切換)。
+- **有 Inspector**:DL 雖唯讀,但有 layout prop 可即時切換——`Inspector` story 暴露 `cols`(1 / 2 / 3)/ `orientation`(vertical / horizontal)/ `divided` 三個 prop 的 Controls,取代 Figma inspect。`orientation` 與 `divided` 是 `ColsMatrix`(只示範 cols)沒涵蓋的維度。
 - **無 ColorMatrix**:DL 固定 semantic token(label `text-fg-secondary` / value `text-foreground`),無自己的色彩變體,dark mode 由 semantic token 自動切換。加 color variant 不符語意(DL 是資訊展示,非狀態載體)。
 - **無 SizeMatrix**:DL 無 size prop——垂直間距隨 `layout-space` token 感知 density(見「間距」段),但 label / value typography 走 reading mode 固定 tier,不提供 sm / md / lg 變體。不同 density 由 token 自動處理,非 prop 切換。
 
-對應 anatomy story:保留 `Overview` + `ColsMatrix`(元件特有 1 / 2 / auto 欄對照) + `StateBehavior`(空值 `—` / 長值 / 多行)。
+對應 anatomy story(實際 5 個,對齊 6-canonical 結構;ColorMatrix / SizeMatrix N/A):`Overview`(anatomy + typography + 間距) + `Inspector`(Controls 即時切 `cols` / `orientation` / `divided`) + `ColsMatrix`(元件特有 1 / 2 / 3 欄對照) + `StateBehavior`(空值 `-` / 長值 / 多行 / ReactNode value) + `Accessibility`(`dl/dt/dd` 語意 + 無互動說明)。
 
 ---
 
 ## 邊界案例
 
-- **Disabled(action cell)**:DescriptionList 主體為唯讀資料呈現,本身無 disabled state;若 `<dd>` 內 consumer 嵌入 inline action(Button / Link),該 action 自行 own disabled,DL 不干預(token 走 Button SSOT)。
+- **Disabled(action cell)**:DescriptionList 主體為唯讀資料呈現,本身無 disabled state。**dd 內互動內容 canonical(2026-07-04 Q9 拍板,三處立場收斂)**:操作型互動(Button / Input)**禁止**(見「禁止事項」— 需要動作 → Field read-only / inline-edit / action row / 卡片 header action);展示 / 導覽型 ReactNode(Tag / Badge / **Link**)**允許**,Link 自行 own disabled,DL 不干預。對齊 Polaris(ReactNode 型別 + 純敘述範例)/ Ant(action 放 extra 不放 dd)/ Carbon(read-only default)三家共識。
 - **Loading**:DL 非 async surface,無 loading prop。若 page-level data 載入中,consumer 應在 DL 外層用 `<Skeleton>`(每組 dt/dd 對應一條 skeleton line)取代;DL 本體不渲染 loading state。
-- **Empty(no items / empty value)**:no items → consumer 應 conditional 渲 `<Empty>` 取代 DL,不渲空 `<dl>`(SR 會讀「empty list」造成混淆);individual value 空 → 渲 `—`(em dash,`text-fg-muted`,已在「無障礙」段 codify)。
+- **Empty(no items / empty value)**:no items → consumer 應 conditional 渲 `<Empty>` 取代 DL,不渲空 `<dl>`(SR 會讀「empty list」造成混淆);individual value 空 → consumer 應自行傳入半形 `-`(hyphen,對齊 Field `EMPTY_DISPLAY`,2026-07-08 user 拍板;包 `text-foreground`(色同 value,2026-07-09);元件不自動 normalize,已在「無障礙」段 codify)。
+- **長 label / 長值**:horizontal 模式 label(`dt`)`shrink-0` 不收縮、不截斷,value(`dd`)`break-all min-w-0` 斷行吸收擠壓;vertical 模式兩者佔滿欄寬自然換行。無空白長字串(URL / ID)詳「無障礙」段「長值換行」。
 - **Dark mode**:走 semantic token(`text-fg-secondary` / `text-foreground`)自動 adapt。
 - **Density**:垂直 gap 隨 `layout-space` token density-aware(見「間距」段),typography fixed reading mode tier 不變。
 
@@ -204,11 +206,14 @@ DescriptionList 是**唯讀 label / value 資料呈現**(非互動 / 非 variant
 
 - `../Field/field.spec.md` — 表單輸入（需要編輯的對應元件）
 - `../DataTable/data-table.spec.md` — 多筆同結構資料（table 對應）
-- `../NameCard/name-card.spec.md` — NameCard info fields 的消費者
+- `../ProfileCard/profile-card.spec.md` — ProfileCard info fields 的消費者
 - `../../tokens/layoutSpace/layoutSpace.spec.md` — 垂直 gap 的 density 感知 token
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `data-table.spec.md`
+- `field.spec.md`
 - `item-anatomy.spec.md`
+- `profile-card.spec.md`

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

@@ -0,0 +1,113 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { DescriptionList, DescriptionItem } from './description-list'
+
+const meta: Meta<typeof DescriptionList> = {
+  title: 'Design System/Components/DescriptionList/展示',
+  component: DescriptionList,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '用於顯示單一實體的多組唯讀屬性，並以 `dl / dt / dd` 保留「欄位—值」語意。需編輯時改用 Field 系統，多筆同結構資料改用 DataTable，只有一組值則用簡單 layout。',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof DescriptionList>
+
+/* ── User profile(Email / Role / Team)─────────────────────────────── */
+export const UserProfile: Story = {
+  name: '使用者個資',
+  render: () => (
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-md">
+      <DescriptionList cols={1}>
+        <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
+        <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
+        <DescriptionItem label="職稱">Design Engineer</DescriptionItem>
+        <DescriptionItem label="團隊">Design Systems</DescriptionItem>
+        <DescriptionItem label="時區">UTC+8(台北)</DescriptionItem>
+      </DescriptionList>
+    </div>
+  ),
+}
+
+/* ── Product spec(iPhone 規格對照風格)─────────────────────────────── */
+export const ProductSpec: Story = {
+  name: '產品規格',
+  render: () => (
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-2xl">
+      <DescriptionList cols={2}>
+        <DescriptionItem label="螢幕尺寸">6.7 吋 Super Retina XDR</DescriptionItem>
+        <DescriptionItem label="處理器">A18 Pro</DescriptionItem>
+        <DescriptionItem label="儲存容量">256GB / 512GB / 1TB</DescriptionItem>
+        <DescriptionItem label="主相機">48MP 廣角 + 12MP 超廣角</DescriptionItem>
+        <DescriptionItem label="電池續航">最長 29 小時影片播放</DescriptionItem>
+        <DescriptionItem label="防水等級">IP68</DescriptionItem>
+      </DescriptionList>
+    </div>
+  ),
+}
+
+/* ── 訂單明細(Stripe checkout 風格)────────────────────────────────── */
+export const OrderSummary: Story = {
+  name: '訂單明細',
+  render: () => (
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-md">
+      {/* title 到第一個 item 的間距 = item 之間間距(Gestalt proximity canonical,見 spec;對齊 Horizontal story)*/}
+      <div className="text-body font-medium mb-[var(--layout-space-tight)]">訂單摘要</div>
+      <DescriptionList cols={1}>
+        <DescriptionItem label="訂單編號">#20260418-A241</DescriptionItem>
+        <DescriptionItem label="商品">Pro 年費方案 × 5 人</DescriptionItem>
+        <DescriptionItem label="小計">NT$ 12,000</DescriptionItem>
+        <DescriptionItem label="折扣(首年 20% off)">−NT$ 2,400</DescriptionItem>
+        <DescriptionItem label="稅金(5%)">NT$ 480</DescriptionItem>
+        <DescriptionItem label="付款方式">Visa ending 4242</DescriptionItem>
+        <DescriptionItem label="總金額">
+          <span className="font-medium">NT$ 10,080</span>
+        </DescriptionItem>
+      </DescriptionList>
+    </div>
+  ),
+}
+
+/* ── Detail panel(三欄 dense)────────────────────────────────────── */
+export const DetailPanel: Story = {
+  name: '詳情面板',
+  render: () => (
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-3xl">
+      <DescriptionList cols={3}>
+        <DescriptionItem label="訂單狀態">已出貨</DescriptionItem>
+        <DescriptionItem label="建立時間">2026-04-18 10:35</DescriptionItem>
+        <DescriptionItem label="預計送達">2026-04-20</DescriptionItem>
+        <DescriptionItem label="配送方式">宅配</DescriptionItem>
+        <DescriptionItem label="付款方式">信用卡</DescriptionItem>
+        <DescriptionItem label="追蹤編號">FX-1234567890</DescriptionItem>
+      </DescriptionList>
+    </div>
+  ),
+}
+
+/* ── Horizontal orientation(label 左 / value 右,divided=false)──────── */
+export const Horizontal: Story = {
+  name: '水平佈局',
+  render: () => (
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-md">
+      {/* title 到第一個 item 的間距 = item 之間間距(Gestalt proximity canonical,見 spec) */}
+      <div className="text-body font-medium mb-[var(--layout-space-tight)]">檔案資訊</div>
+      <DescriptionList orientation="horizontal">
+        <DescriptionItem label="檔名">Q1-roadmap.pdf</DescriptionItem>
+        <DescriptionItem label="類型">application/pdf</DescriptionItem>
+        <DescriptionItem label="大小">2.4 MB</DescriptionItem>
+        <DescriptionItem label="修改時間">2026-04-18</DescriptionItem>
+      </DescriptionList>
+    </div>
+  ),
+}
+
+// @story-history: HorizontalDivided retired 2026-05-17 per audit Dim 24/25 strict re-run —
+//   違 story-rules.md L42「同 affordance 內 prop variations 用 Controls 不另開」。Horizontal orientation
+//   已展示;divided 是單一 prop toggle,anatomy Inspector 已 expose Controls (L85-86)。
+//   原本內容 archive 於 git history(若要看 divided 視覺,進 anatomy Inspector 開 divided=true)。
+//   2026-06-12:刪除 zombie export _RETIRED_HorizontalDivided,對齊 DS-wide comment-only 退役慣例(deep-audit dim25)。

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

@@ -12,7 +12,7 @@ import { cn } from '@/lib/utils'
  * value (dd): text-body (14px) text-foreground (neutral-9)
  * 兩者都是 14px × 1.5 行高——層級靠色彩區分，不靠字體大小。
  *
- * ── direction（2026-04-20 新增）──
+ * ── orientation（2026-04-20 新增）──
  * vertical（預設）：label 在上 / value 在下，適合長 value（地址、bio、說明段落）、
  *                   form-like 資訊展示
  * horizontal     ：label 左 / value 右對齊，適合短 value 的 metadata 列
@@ -24,21 +24,21 @@ import { cn } from '@/lib/utils'
  * 不一時需要對齊格線才易讀 → 開 divided；短列表（< 4 rows）不需要。
  *
  * ── 間距 ──
- * vertical: label → value（同 item 內）: `var(--item-gap-label-desc)` token（預設 2px,item-anatomy SSOT）
+ * vertical: label → value（同 item 內）: `var(--item-gap-label-desc-reading)` token（2px,item-anatomy reading tier SSOT;code L115 dd 消費）
  * horizontal: label ↔ value: gap-x-4（16px）最小間距
  * items 之間垂直 gap: layout-space-tight（density-aware）
  * divided horizontal 模式：每 item py-[var(--layout-space-tight)]（cell-like row 高度）
  */
 
-export type DescriptionDirection = 'vertical' | 'horizontal'
+export type DescriptionListOrientation = 'vertical' | 'horizontal'
 
 interface DescriptionContextValue {
-  direction: DescriptionDirection
+  orientation: DescriptionListOrientation
   divided: boolean
 }
 
 const DescriptionContext = React.createContext<DescriptionContextValue>({
-  direction: 'vertical',
+  orientation: 'vertical',
   divided: false,
 })
 
@@ -46,7 +46,7 @@ export interface DescriptionListProps extends React.HTMLAttributes<HTMLDListElem
   /** grid 欄數（vertical 才生效；horizontal 永遠單欄），預設 1 */
   cols?: 1 | 2 | 3
   /** 項目排列方向，預設 vertical（label 在上 / value 在下） */
-  direction?: DescriptionDirection
+  orientation?: DescriptionListOrientation
   /**
    * horizontal 模式下每個 item 下方加分隔線以對齊 rows。預設 false。
    * 短列表（< 4 rows）不需要；檔案 metadata 等長列表、key 長度不一時建議開。
@@ -61,10 +61,10 @@ const colsClass: Record<number, string> = {
 }
 
 const DescriptionList = React.forwardRef<HTMLDListElement, DescriptionListProps>(
-  ({ cols = 1, direction = 'vertical', divided = false, className, ...props }, ref) => {
-    const isHorizontal = direction === 'horizontal'
+  ({ cols = 1, orientation = 'vertical', divided = false, className, ...props }, ref) => {
+    const isHorizontal = orientation === 'horizontal'
     // Memoize provider value(2026-04-22 D3 perf audit):避免每 render 重建 2-field object
-    const ctxValue = React.useMemo(() => ({ direction, divided }), [direction, divided])
+    const ctxValue = React.useMemo(() => ({ orientation, divided }), [orientation, divided])
     return (
       <DescriptionContext.Provider value={ctxValue}>
         <dl
@@ -90,8 +90,8 @@ export interface DescriptionItemProps extends React.HTMLAttributes<HTMLDivElemen
 
 const DescriptionItem = React.forwardRef<HTMLDivElement, DescriptionItemProps>(
   ({ label, children, className, ...props }, ref) => {
-    const { direction, divided } = React.useContext(DescriptionContext)
-    if (direction === 'horizontal') {
+    const { orientation, divided } = React.useContext(DescriptionContext)
+    if (orientation === 'horizontal') {
       return (
         <div
           ref={ref}
@@ -112,7 +112,9 @@ const DescriptionItem = React.forwardRef<HTMLDivElement, DescriptionItemProps>(
     return (
       <div ref={ref} className={cn('flex flex-col', className)} {...props}>
         <dt className="text-body text-fg-secondary">{label}</dt>
-        <dd className="text-body mt-[var(--item-gap-label-desc-reading)]">{children}</dd>
+        {/* text-foreground 顯式宣告(2026-07-05 fix):與 horizontal 分支一致,不靠容器繼承 —
+            spec Typography 段 / tsx docblock / anatomy Overview 三處 canonical 皆宣稱 dd = text-foreground */}
+        <dd className="text-body text-foreground mt-[var(--item-gap-label-desc-reading)]">{children}</dd>
       </div>
     )
   },
@@ -123,14 +125,14 @@ DescriptionItem.displayName = 'DescriptionItem'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const descriptionListMeta = {
   component: 'DescriptionList',
-  family: null, // non-family composite / overlay / layout
+  family: 'composite', // 對齊 description-list.spec.md frontmatter family: composite(SSOT)
   variants: {
 
   },
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: [], // 純唯讀 dl/dt/dd,無 hover/active/focus/disabled 互動 state(spec「為何無 ColorMatrix / SizeMatrix」段)
   tokens: {
     bg: [],
     fg: ['text-fg-secondary', 'text-foreground'],

package/src/components/DescriptionList/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './description-list'