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

package/src/tokens/typography/typography.spec.md

@@ -0,0 +1,204 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
+
+# Typography 設計原則
+
+Typography 定義字體尺寸與行高的 token 系統，確保全系統文字層級一致。
+
+## 設計原則
+
+Typography 由三個獨立維度組成，分開疊加：
+
+| 維度 | 控制方式 | 說明 |
+|------|---------|------|
+| font-size | `text-{role}` utility | token 決定，不可繞過 |
+| line-height | 烤進 token，需要時覆蓋 | heading / supplementary → 1.3；body → 1.5 |
+| font-weight | `font-normal` / `font-medium` / `font-bold` | 使用端疊加，不寫死在 token |
+
+**line-height 的選擇基於「是否適合多行閱讀」：**
+- `1.5`：適合連續閱讀的段落（14px / 16px）
+- `1.3`：標題、短文字、截斷場景、不需要閱讀行距
+- 12px 以下不適合作為連續閱讀內文，一律 1.3
+
+**font-weight 等同 `<strong>` 的疊加邏輯：**
+- 不加 = 400，一般文字
+- `font-medium` = 500，行內中等強調
+- `font-bold` = 700，強調（等同 `<strong>`）
+
+
+## Token 表
+
+| Utility        | font-size | line-height | 用途 |
+|----------------|-----------|-------------|------|
+| `text-h1`      | 48px      | 1.3         | 頁面主標題 |
+| `text-h2`      | 32px      | 1.3         | 區塊標題 |
+| `text-h3`      | 24px      | 1.3         | 子區塊標題 |
+| `text-h4`      | 20px      | 1.3         | 小節標題 |
+| `text-h5`      | 16px      | 1.3         | 元件層級標題 |
+| `text-h6`      | 14px      | 1.3         | 最小層級標題 |
+| `text-body-lg` | 16px      | 1.5         | 16px 為主版面的段落內文 |
+| `text-body`    | 14px      | 1.5         | ★ 主要內文基準 |
+| `text-caption` | 12px      | 1.3         | 圖表附註、標籤文字、元件內次要說明 |
+| `text-footnote`| 10px      | 1.3         | 法律文字、來源標注（極少用）|
+
+**h5（16px）vs body-lg（16px）/ h6（14px）vs body（14px）**：同尺寸配對的統一判別法——line-height 區分角色（標題 1.3 / 段落 1.5），使用端再疊 font-weight / color 強化標題層級，需有意識地選擇（詳「同尺寸但不同角色的選法」）。
+
+
+## line-height 覆蓋（僅 14/16px body 可覆蓋）
+
+**Token canonical**：除 `text-body`（14px）/ `text-body-lg`（16px）外，**所有 size 行高皆固定**：
+- `text-h1`–`text-h6`：全部 lh 1.3 固定（標題不需多行閱讀行距）
+- `text-caption`（12px）/ `text-footnote`（10px）：全部 lh 1.3 固定（小字不適合 1.5）
+- `text-body` / `text-body-lg`：**唯二**可覆蓋（預設 lh 1.5 閱讀段落，可 `leading-compact` 覆蓋為 1.3）
+
+唯一合理覆蓋情境：`text-body` / `text-body-lg` 用於**單行固定高度容器**（Button / Tabs trigger / Chip / Notice banner / MenuItem row / SelectMenu / TreeView / DropdownMenu / Combobox input），避免 1lh > chrome height 造成垂直偏移：
+
+```tsx
+{/* ✅ Button 文字（單行 28/32/36px chrome height）*/}
+<button className="h-field-sm text-body leading-compact">確認</button>
+
+{/* ✅ Notice banner 單行 alert text */}
+<span className="text-body leading-compact">已儲存</span>
+```
+
+單行保證由容器自身承擔（Button / SegmentedControl item 等套 `whitespace-nowrap`）——`leading-compact` 不處理 2 行以上的 label；多行截斷是 `line-clamp-*` + 預設行高的職責（見下方反 pattern）。
+
+可用的 override utility：
+- `leading-compact`：1.3（自訂，只給 `text-body` / `text-body-lg`）
+- `leading-normal`：1.5（Tailwind 內建，**極少用**——僅 stories `<p>` 補 12px footnote 段落呼吸感，正式 DS 元件**不需**主動覆蓋成 1.5，因為 `text-body` / `text-body-lg` 預設就是 1.5）
+
+### 反 pattern（禁用）
+
+```tsx
+{/* ❌ 用 leading-compact + line-clamp 「截斷副標」
+       line-clamp 自己處理截斷，不需要動 line-height；該選對的 token */}
+<p className="text-body leading-compact line-clamp-2">副標說明</p>
+
+{/* ❌ 用 h5/h6 + leading-normal「當段落」
+       h5/h6 是標題語義，不該當段落；同 size 該換 body-lg / body */}
+<p className="text-h5 leading-normal">較小的說明段落</p>
+```
+
+### 同尺寸但不同角色的選法（用 token 自然區分，不靠 leading 覆寫）
+
+| 尺寸 | 段落（閱讀） | 標題（掃視 + bold） |
+|---|---|---|
+| 16px | `text-body-lg`（lh 1.5） | `text-h5`（lh 1.3，加 `font-medium`/`font-semibold`） |
+| 14px | `text-body`（lh 1.5） | `text-h6`（lh 1.3，加 `font-medium`/`font-semibold`） |
+
+**結論**：90% 情境用 token 預設就對；唯一覆寫 = body/body-lg 進單行固定高度容器套 `leading-compact`。
+
+
+## 組合範例
+
+```tsx
+{/* 頁面標題 */}
+<h1 className="text-h1">專案總覽</h1>
+
+{/* 區塊標題加重 */}
+<h2 className="text-h2 font-medium">執行進度</h2>
+
+{/* 主要內文 */}
+<p className="text-body">一般說明段落，預設 400 weight。</p>
+
+{/* 行內強調 */}
+<p className="text-body">
+  此操作將<span className="font-medium">永久刪除</span>該筆資料。
+</p>
+
+{/* 截斷副標 */}
+<p className="text-body leading-compact line-clamp-2 text-fg-secondary">
+  這是一段較長的副標說明，超過兩行會被截斷顯示。
+</p>
+
+{/* 欄位附屬說明 */}
+<span className="text-caption text-fg-muted">最多 200 字元</span>
+```
+
+
+## 禁止事項
+
+```tsx
+// ❌ 不要用 Tailwind 原始 text-sm / text-lg / text-base
+<p className="text-sm">內文</p>
+
+// ❌ 不要硬寫 font-size 或 line-height
+<p style={{ fontSize: '14px' }}>內文</p>
+
+// ❌ 不要用 12px 做連續閱讀段落
+<p className="text-caption">這是一整段很長的說明文字...</p>
+
+// ❌ 不要把 font-weight 寫死在外層容器（應在需要的元素上疊加）
+<section className="text-body font-medium">...</section>
+
+// ❌ 不要用 Tailwind 原始 tracking-* utility(letter-spacing 必 role-specific)
+<kbd className="tracking-widest">⌘K</kbd>
+```
+
+
+## Letter-spacing(role-specific only)
+
+**哲學**:`letter-spacing` 跟 font-size / line-height 同層 — utility scale(`tracking-tight..widest`)是 raw scale 非 semantic role,每 consumer 自挑值 = 跨元件不一致。本 DS 採 **single semantic value per role**(對齊 Polaris / Material / Apple),每個需要 letter-spacing 變化的 role 必先 codify token。
+
+### 既定 role
+
+| Token | 值 | Tailwind utility | Role |
+|---|---|---|---|
+| `--tracking-shortcut` | `0.1em` | `tracking-shortcut` | 鍵盤快捷鍵 hint(`⌘K` / `Ctrl+S` 等),Command/CommandShortcut + DropdownMenuShortcut + 同類 kbd 顯示 consumed via `text-caption` 或 `text-footnote` |
+
+### 新增 role 流程
+
+1. typography.css `:root` 加 `--tracking-<role>: <value>;`
+2. typography.css 加 `@utility tracking-<role> { letter-spacing: var(--tracking-<role>); }`
+3. utility-registry.json `typography.allow` 加 `tracking-<role>`
+4. 本 spec.md 加 row 到上表 + 對應 role 對齊世界級 cite(M22)
+5. Consumer code 用新 utility
+
+**對齊**:Material 3「letter-spacing per type role」/ Polaris「single semantic letter-spacing per scale」/ GitHub Primer「kbd typography canonical」/ Tailwind「wider tracking for uppercase + labels」。
+
+
+## 世界級對照
+
+對齊 M8(binary strict rule 必 ≥3 家世界級對照),「禁 Tailwind `text-sm`/`text-base` raw utility」+「禁硬寫 fontSize」是本 spec 的 binary strict rule,以下為支撐 rationale。
+
+| 維度 | 本 DS | Material 3 | Carbon | Tailwind v4 | Ant Design | Polaris | Apple HIG |
+|------|-------|-----------|--------|-------------|------------|---------|-----------|
+| 命名哲學 | semantic role(h1-h6 + body)| Type scale roles(Display / Headline / Title / Label / Body)| Productive vs Expressive 雙軌 | utility size(`text-{xs..9xl}`)| 階梯 h1-h5 + base | semantic role(`heading-{md..3xl}` + `body-{sm..lg}`)| Dynamic Type(Title 1-3 / Headline / Body / Callout / Footnote / Caption 1-2)|
+| Body base | **14px** | 14 / 16(可切)| 14(productive)/ 16(expressive)| 16(`text-base`)| 14(`fontSizeBase`)| 14(`body-md`)| 17(`Body`)|
+| Heading 跨度 | h1=48 → h6=14(6 tier)| Display 1-2 + Headline 1-6(8+ tier)| Productive 01-07 + Heading 01-07(14 tier)| `text-xs` (12) → `text-9xl` (128)(13 tier)| h1=38 → h5=16(5 tier)| `heading-md` (16) → `heading-3xl` (40)(5 tier)| Title 1-3(3 tier)|
+| Line-height 哲學 | **二元**(1.5 reading / 1.3 compact)| Ratio ladder(隨 size 1.2-1.6 連續)| 二元(reading 1.5 / supplementary 1.3)| Ratio ladder(`leading-{tight..loose}` 1.25-2)| Unique 1.5715 | 隨 size(0.875-1.5)| 隨 size + Dynamic |
+| Font weight 階 | **3 階**(400/500/700)| 5 階(300-700)| 3 階(Light/Regular/SemiBold)| 9 階(100-900)| 4 階(400/500/600/700)| 4 階(400/500/600/650)| 9 階 + SF |
+
+## 設計哲學
+
+四個關鍵決策,各自有世界級先例支撐:
+
+**(1) Body base = 14px(對齊 Material / Carbon / Ant 三家共識)** <!-- @benchmark-unverified -->
+
+14px 是 productivity tool 共識(Linear / Notion / Figma / Jira / Stripe Dashboard),16px 是 reading-first 哲學(Apple iOS / Polaris 的 storefront / Medium)。本 DS 場景是 dense workspace(規格 / 表格 / Dashboard),14px 同時讓 information density 高 + 對齊 system tool 慣例。捨棄 16 base 的代價是「行動裝置可讀性」,但 DS 主場景是 desktop。
+
+**(2) 二元 line-height(1.5 / 1.3)— 對齊 Carbon「productive vs supplementary」哲學** <!-- @benchmark-unverified -->
+
+Material / Tailwind 用 ratio ladder(隨 size 連續變化)雖精細,但 consumer 心智負擔重(每 size 對應不同 lh,需查表)。Carbon 的「productive reading 1.5 / supplementary compact 1.3」二元規則,讓 reader 一眼判斷「是要連續閱讀還是 scanning」即可選對 — 對應本 DS 的 scanning(MenuItem / FileItem)vs reading(Empty / Field description)二分法。
+
+捨棄連續 ratio 的代價是「極大字級 lh 過鬆」(48px h1 仍 1.3),實測無此問題(本 DS 無 60+ display 級字)。
+
+**(3) h5/h6 與 body-lg/body 同 size(16/14)— 靠 lh + weight 區分,不開新 size tier** <!-- @benchmark-unverified -->
+
+Material 用 17 tier(Display 1-2 + Headline 1-6 + Title 1-2 + Subtitle 1-2 + Body 1-2 + Button + Caption + Overline),Apple Dynamic Type 11 tier 跨平台 — 兩家 size scale 過度膨脹是 DS 維護負擔(每加 1 tier 就要全 component grep 評估)。
+
+本 DS 採 Carbon-aligned 二元覆寫(同 16px 用 lh 1.3 = h5 標題 / lh 1.5 = body-lg 段落),靠 line-height + font-weight + color 區分角色,維持 token table 在 10 個 utility 內。代價是「使用端需有意識選 h5 vs body-lg」,但對應「同尺寸但不同角色的選法」判別法明寫「需有意識地選擇」。
+
+**(4) Font weight 3 階(400/500/700)— 對齊 Carbon / Polaris 共識** <!-- @benchmark-unverified -->
+
+Tailwind / Apple SF 的 9 階 weight scale 涵蓋 marketing / 印刷需求,但 productivity DS 95% 場景只用 normal / medium / bold(對齊 Carbon Light/Regular/SemiBold + Polaris 400/500/600/650)。捨棄 100-300 hairline + 800-900 black 的代價是「行銷 hero text 表現力」,DS 不收 marketing 場景,接受。
+
+## 跨元件參考
+
+行高在 row 類元件中的應用（scanning vs reading 模式）詳見 `patterns/element-anatomy/item-anatomy.spec.md`「兩種閱讀模式」節。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `empty.spec.md`
+- `token-system.spec.md`

package/src/tokens/typography/typography.stories.tsx

@@ -0,0 +1,133 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/Typography',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+字體 token 系統。token 只定義 \`font-size\` 與 \`line-height\`，\`font-weight\` 由使用端疊加。
+
+完整規則：\`packages/design-system/src/tokens/typography/typography.spec.md\`
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function TypeRow({ utility, meta, sample }: { utility: string; meta: string; sample: string }) {
+  return (
+    <div className="grid items-baseline gap-x-6 gap-y-1 border-b border-border py-4 last:border-0"
+      style={{ gridTemplateColumns: '180px 1fr' }}>
+      <div>
+        <code className="block text-caption font-medium text-fg-secondary">{utility}</code>
+        <span className="text-caption text-fg-muted">{meta}</span>
+      </div>
+      <div className={utility}>{sample}</div>
+    </div>
+  )
+}
+
+
+// ── Stories ──────────────────────────────────────────────────────────────────
+
+export const TypeScale: Story = {
+  name: '字型尺寸',
+  parameters: {
+    docs: {
+      description: {
+        story: '所有 typography role 的視覺對照。font-weight 預設 400，line-height 已烤進各 token。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-2xl">
+      <TypeRow utility="text-h1"       meta="48px · lh 1.3" sample="頁面主標題 Page Title" />
+      <TypeRow utility="text-h2"       meta="32px · lh 1.3" sample="區塊標題 Section Heading" />
+      <TypeRow utility="text-h3"       meta="24px · lh 1.3" sample="子區塊標題 Subsection" />
+      <TypeRow utility="text-h4"       meta="20px · lh 1.3" sample="小節標題 Group Title" />
+      <TypeRow utility="text-h5"       meta="16px · lh 1.3" sample="元件層級標題 Component Heading" />
+      <TypeRow utility="text-h6"       meta="14px · lh 1.3" sample="最小層級標題 Inline Label" />
+      <TypeRow utility="text-body-lg"  meta="16px · lh 1.5" sample="16px 版面的段落內文。充足的行距讓視線流暢移動，適合較寬鬆的閱讀情境。" />
+      <TypeRow utility="text-body"     meta="14px · lh 1.5" sample="主要內文基準。產品中絕大多數的說明文字、列表內容、表單說明都使用這個尺寸。" />
+      <TypeRow utility="text-caption"  meta="12px · lh 1.3" sample="圖表附註、helper text、標籤文字" />
+      <TypeRow utility="text-footnote" meta="10px · lh 1.3" sample="法律文字、來源標注（極少用）" />
+    </div>
+  ),
+}
+
+
+export const FontWeight: Story = {
+  name: '字重',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'font-weight 不寫死在 token，由使用端疊加。' +
+          '`font-medium`（500）對應中等強調，`font-bold`（700）對應 `<strong>`。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-lg space-y-1">
+      {[
+        { label: '（預設）font-normal', cls: 'font-normal', weight: '400' },
+        { label: 'font-medium',         cls: 'font-medium', weight: '500' },
+        { label: 'font-bold',           cls: 'font-bold',   weight: '700' },
+      ].map(({ label, cls, weight }) => (
+        <div key={weight} className="flex items-baseline gap-6 border-b border-border py-3 last:border-0">
+          <div className="w-44 shrink-0">
+            <code className="text-caption font-medium text-fg-secondary">{label}</code>
+            <span className="ml-2 text-caption text-fg-muted">{weight}</span>
+          </div>
+          <p className={`text-body ${cls}`}>
+            此操作將永久刪除該筆資料，請確認後再繼續。
+          </p>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+
+export const LineHeight: Story = {
+  name: '行高',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`text-body` / `text-body-lg`（14/16px）唯二可覆蓋行高的 token，預設 1.5（閱讀段落），' +
+          '可 `leading-compact` 覆蓋為 1.3 — 唯一合理情境是「單行固定高度容器」' +
+          '（Button / Tabs trigger / Chip / Notice / MenuItem 等），避免 1lh > chrome height 造成垂直偏移。' +
+          'h1-h6 / caption / footnote 全 lh 1.3 固定不可覆蓋。',
+      },
+    },
+  },
+  render: () => (
+    <div className="grid max-w-2xl grid-cols-2 gap-6">
+      <div>
+        <code className="mb-2 block text-caption font-medium text-fg-secondary">
+          text-body · leading-normal (1.5)
+        </code>
+        <p className="text-body leading-normal rounded-md bg-neutral-hover p-4">
+          適合連續閱讀的段落內文。充足的行距讓眼睛在換行時容易找到下一行的起點，降低閱讀疲勞。
+        </p>
+      </div>
+      <div>
+        <code className="mb-2 block text-caption font-medium text-fg-secondary">
+          text-body · leading-compact (1.3)
+        </code>
+        <p className="text-body leading-compact rounded-md bg-neutral-hover p-4">
+          適合單行固定高度容器內文字（Button / Tabs trigger / Chip / Notice / MenuItem 等），避免 1lh 大於容器高度造成垂直偏移。
+        </p>
+      </div>
+    </div>
+  ),
+}

package/src/tokens/uiSize/icon-size.ts

@@ -33,8 +33,7 @@
  * ── 防漂移 ──
  * 1. uiSize.spec.md「Icon Size Tier」段 codify 16/16/16/20 tier(text-based canonical)
  * 2. 本 const 程式化 SSOT(type-safe Record<RowSize, number>)
- * 3. Hook `check_icon_size_literal.sh`(write-time regex 攔非標準 literal)
- * 4. Audit Dim「Icon size literal compliance」DS-wide audit-time scan
+ * 3. Audit Dim「Icon size literal compliance」DS-wide audit-time scan(write-time hook 尚未實作 — 改靠 audit-time + mindset)
  *
  * ── Carve-out(不適用本 SSOT)──
  * - `rating.spec.md` Rating star 20/24/24(identity scale,cite Ant/Material/Airbnb)

package/src/tokens/uiSize/uiSize.css

@@ -24,6 +24,11 @@
   --field-height-md: 2rem;      /* 32px */
   --field-height-lg: 2.25rem;   /* 36px */
 
+  /* Field horizontal padding — 固定 12px(不隨 size/density);form-context field 左右內距 SSOT。
+     跟 --table-cell-px(cell-context)同 -px 慣例;Input/Select/Combobox/DatePicker/TimePicker/Textarea
+     + tag 模式右緣 re-assert 全消費此 token(取代散落的 px-3 / inline 0.75rem,M17 SSOT 可傳播)。 */
+  --field-px: 0.75rem;          /* 12px */
+
   /* Table Row Height — DataTable */
   --table-row-sm: 2rem;         /* 32px */
   --table-row-md: 2.5rem;       /* 40px */
@@ -49,6 +54,19 @@
      不寫成 calc() 公式因為 lg 無法完美遵守(54 → 56 為了 8px grid 取整),hardcode 比假公式誠實。 */
   --chrome-header-height: 3rem; /* 48px */
 
+  /* Sidebar / Layout primitive sizing(2026-05-26 ship 進 published per consumer SSOT gap):
+     原本 declared in DS repo `src/globals.css`,沒進 npm-published tokens aggregator
+     → consumer install DS + import `@qijenchen/design-system/styles/tokens` 拿不到
+     → AppShell + Sidebar gap div 用 `var(--sidebar-width)` undefined → 解析 0px → flex 跑版
+     對齊 docs:`components/Sidebar/sidebar.spec.md` L613-614 token table
+     Why uiSize.css:layout primitive widths 是 ui sizing semantic 範疇(對齊 --field-height / --chrome-header)
+     */
+  --sidebar-width: 15rem;          /* 240px expanded sidebar */
+  --sidebar-width-min: 240px;      /* 最小寬,同時是 AppShell Aside floor(ASIDE_WIDTH_MIN) */
+  --sidebar-width-mobile: 18rem;   /* 288px mobile sheet 抽屜 */
+  --sidebar-menu-icon-size: 1rem;   /* 16px sm/md row(per ICON_SIZE.sm/md);size=lg 罕見 case 下方 override 1.25rem(20px) */
+  --sidebar-width-icon: calc(2 * var(--layout-space-loose, 1rem) + var(--sidebar-menu-icon-size));
+
   /* Tree Indent — TreeView + DataTable nested rows(SSOT,2026-05-04)
      公式:chevronSize + gap-2 = 16+8(sm/md)/ 20+8(lg)
      Consumer:TreeView depth indent / DataTable nested row depth indent */
@@ -67,6 +85,9 @@
 
 [data-ui-size="lg"],
 [data-density="lg"] {
+  /* Sidebar lg override(per src/globals.css 原 declaration:size=lg 罕見 case)*/
+  --sidebar-menu-icon-size: 1.25rem; /* 20px(lg)*/
+
   --field-height-sm: 2rem;      /* 32px */
   --field-height-md: 2.25rem;   /* 36px */
   --field-height-lg: 2.5rem;    /* 40px */