@qijenchen/design-system 0.1.0-beta.3

package/src/tokens/opacity/opacity.css

@@ -0,0 +1,23 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   Opacity Tokens
+   ═══════════════════════════════════════════════════════════════════════
+
+   系統內唯一的 opacity token(disabled 狀態)。其他所有透明度需求
+   應透過 alpha 色階(--white-aN / --black-aN)解決,不另開 opacity token。
+
+   **Drag-and-drop reuse(2026-05-06 v14.5.2 對齊 Atlassian Pragmatic)**:
+   - Drag source 半透殘影 → reuse `opacity-disabled`(0.45)。Atlassian Pragmatic
+     guidelines 也是 reuse `opacity.disabled`(他們值 0.40,我們 0.45,role 一致)。
+   - DragOverlay ghost 不另 dim,用 `opacity:1` + `shadow-[var(--elevation-200)]`
+     表達 "lifted preview"(對齊 dnd-kit / Material / Atlassian canonical)。
+   ═══════════════════════════════════════════════════════════════════════ */
+
+@theme inline {
+  --opacity-disabled: 0.45;
+}
+
+
+/* ── Custom Utility ── */
+@utility opacity-disabled {
+  opacity: var(--opacity-disabled);
+}

package/src/tokens/radius/radius.css

@@ -0,0 +1,19 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   Radius Tokens
+   ═══════════════════════════════════════════════════════════════════════
+
+   見 radius.spec.md 的使用原則。
+
+   xs     :2px(極小視覺 indicator,如 Chart legend swatch 8×8 色塊)
+   sm / md:4px(小元件、Tag、Badge、Button、Field、checkbox 等)
+   lg     :8px(卡片、彈窗、容器層)
+   full   :9999px(pill / circular,Avatar、Switch track 等)
+   ═══════════════════════════════════════════════════════════════════════ */
+
+@theme inline {
+  --radius-xs:   2px;
+  --radius-sm:   4px;
+  --radius-md:   4px;
+  --radius-lg:   8px;
+  --radius-full: 9999px;
+}

package/src/tokens/typography/typography.css

@@ -0,0 +1,118 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   Typography Tokens
+   ═══════════════════════════════════════════════════════════════════════
+
+   ┌─ 設計原則 ────────────────────────────────────────────────────────────┐
+   │  font-size 與預設 line-height 烤進 token。                           │
+   │  font-weight 永遠由使用端疊加，不寫死在 token。                      │
+   │                                                                      │
+   │  line-height 的選擇基於「是否適合多行閱讀」：                        │
+   │    lh 1.5  → 適合閱讀的連續段落（14px / 16px）                     │
+   │    lh 1.3  → 標題、短文字、不需閱讀行距的場景                       │
+   │                                                                      │
+   │  12px 以下不適合作為連續閱讀內文，一律 lh 1.3。                     │
+   └──────────────────────────────────────────────────────────────────────┘
+
+   ┌─ Heading scale  全部 lh 1.3 ────────────────────────────────────────┐
+   │  text-h1   48px   頁面主標題                                        │
+   │  text-h2   32px   區塊標題                                          │
+   │  text-h3   24px   子區塊標題                                        │
+   │  text-h4   20px   小節標題                                          │
+   │  text-h5   16px   元件層級標題                                      │
+   │  text-h6   14px   最小層級標題                                      │
+   └──────────────────────────────────────────────────────────────────────┘
+
+   ┌─ Body scale  lh 1.5，可用 leading-compact 覆蓋為 1.3 ──────────────┐
+   │  text-body-lg  16px   16px 為主版面的段落內文                       │
+   │  text-body     14px   ★ 主要內文基準                                │
+   └──────────────────────────────────────────────────────────────────────┘
+
+   ┌─ Supplementary scale  全部 lh 1.3 ──────────────────────────────────┐
+   │  text-caption   12px   圖表附註、元件 helper text、標籤文字         │
+   │  text-footnote  10px   法律文字、來源標注（極少用）                 │
+   └──────────────────────────────────────────────────────────────────────┘
+   ═══════════════════════════════════════════════════════════════════════ */
+
+:root {
+  /* Font Size */
+  --font-h1-size:       48px;
+  --font-h2-size:       32px;
+  --font-h3-size:       24px;
+  --font-h4-size:       20px;
+  --font-h5-size:       16px;
+  --font-h6-size:       14px;
+
+  --font-body-lg-size:  16px;
+  --font-body-size:     14px;
+
+  --font-caption-size:  12px;
+  --font-footnote-size: 10px;
+
+  /* ─ Letter-spacing(role-specific only;raw tracking-* utility 禁用)─
+     `--tracking-shortcut`:鍵盤快捷鍵顯示專用(⌘K / Ctrl+S 等)。寬一階
+     letter-spacing 讓 glyph 之間呼吸感對齊鍵帽 visual idiom — 對齊
+     Material / GitHub Primer / Polaris KeyboardKey / Tailwind「wider tracking
+     for uppercase buttons + labels」canonical。0.1em 與 Tailwind tracking-widest
+     相同值但語義特定(不放任 raw utility 漏)。  */
+  --tracking-shortcut: 0.1em;
+}
+
+
+/* ── Tailwind Theme Bridge ──
+   font-sans — Roboto 為品牌字體（假設系統已有，不另外載入 web font）
+
+   ┌─ Stack 順序 ───────────────────────────────────────────────────────┐
+   │  1. Roboto（假設系統有；沒有則 fallback）                           │
+   │  2. OS 系統字 fallback（macOS / Windows / generic）                 │
+   │  3. CJK 字體 fallback（瀏覽器 glyph-level fallback 自動觸發）       │
+   │  4. generic + emoji                                                │
+   └────────────────────────────────────────────────────────────────────┘
+
+   原理：瀏覽器做 glyph-level fallback，自動沿 stack 找有對應字元的字體 */
+@theme {
+  --font-sans:
+    /* Brand font — 假設系統已有 */
+    Roboto,
+    /* Latin OS fallback */
+    -apple-system, BlinkMacSystemFont,
+    "Segoe UI Variable", "Segoe UI",
+    system-ui,
+    /* Japanese */
+    "Hiragino Sans", "Yu Gothic UI", Meiryo, "Noto Sans JP",
+    /* Korean */
+    "Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans KR",
+    /* Chinese (TC) */
+    "PingFang TC", "Microsoft JhengHei UI", "Microsoft JhengHei",
+    /* generic */
+    sans-serif,
+    /* emoji */
+    "Apple Color Emoji", "Segoe UI Emoji";
+}
+
+
+/* ── Tailwind Utility Bridge ── */
+
+@utility text-h1      { font-size: var(--font-h1-size);      line-height: 1.3; }
+@utility text-h2      { font-size: var(--font-h2-size);      line-height: 1.3; }
+@utility text-h3      { font-size: var(--font-h3-size);      line-height: 1.3; }
+@utility text-h4      { font-size: var(--font-h4-size);      line-height: 1.3; }
+@utility text-h5      { font-size: var(--font-h5-size);      line-height: 1.3; }
+@utility text-h6      { font-size: var(--font-h6-size);      line-height: 1.3; }
+
+@utility text-body-lg { font-size: var(--font-body-lg-size); line-height: 1.5; }
+@utility text-body    { font-size: var(--font-body-size);    line-height: 1.5; }
+
+@utility text-caption  { font-size: var(--font-caption-size);  line-height: 1.3; }
+@utility text-footnote { font-size: var(--font-footnote-size); line-height: 1.3; }
+
+
+/* ── line-height override
+   leading-normal (1.5) 已是 Tailwind 內建，只補 leading-compact ── */
+@utility leading-compact { line-height: 1.3; }
+
+
+/* ── Letter-spacing semantic utility(對齊 single semantic value per role 哲學)──
+   `tracking-shortcut`:鍵盤快捷鍵 hint(Command / DropdownMenuShortcut 等)。
+   禁 raw `tracking-(tight|wide|wider|widest|tighter)` per typography.spec.md L91-105
+   + utility-registry.json block list。新增 role 需新 token + 新 @utility。 */
+@utility tracking-shortcut { letter-spacing: var(--tracking-shortcut); }

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

@@ -0,0 +1,52 @@
+/**
+ * Icon Size SSOT — cross-domain re-export entry
+ *
+ * Owner:`packages/design-system/src/patterns/element-anatomy/item-anatomy.tsx:66` `ICON_SIZE`
+ * Spec:`packages/design-system/src/tokens/uiSize/uiSize.spec.md` 「Icon Size Tier」段
+ *
+ * ── 為什麼 re-export 不直接動 owner ──
+ * `ICON_SIZE` const codified in `item-anatomy.tsx` 是 row primitive SSOT(MenuItem / TreeView /
+ * Sidebar / DropdownMenu / SelectionItem / Item-anatomy 等 row-based primitives 消費)。
+ *
+ * Form control(Button / Input / Combobox / DatePicker / Tabs / Select / SegmentedControl 等)
+ * 不該 cross-domain import patterns/element-anatomy(會造成 components→patterns 反向 dependency
+ * 增加 cycle 風險)。透過 `tokens/uiSize/` 作 token home 是 cross-domain SSOT 的慣例(token 是 DS
+ * 內最底層,所有 layer 都可 consume 不違反 dependency direction)。
+ *
+ * ── Tier ──
+ * `field-height-xs / sm / md` → icon **16px**
+ * `field-height-lg`           → icon **20px**
+ *
+ * 詳 spec L132+ Icon Size Tier 段(stroke 下限 12px / Tag-Field 配對 / etc.)
+ *
+ * ── Consumer 用法 ──
+ * ```tsx
+ * import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
+ *
+ * // sm/md → 16, lg → 20
+ * <LucideIcon size={ICON_SIZE[size]} />
+ *
+ * // form control xs(field-height-xs 24)用 ICON_SIZE.sm(同 16,per spec L132 Tier)
+ * <LucideIcon size={size === 'xs' ? ICON_SIZE.sm : ICON_SIZE[size]} />
+ * ```
+ *
+ * ── 防漂移 ──
+ * 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
+ *
+ * ── Carve-out(不適用本 SSOT)──
+ * - `rating.spec.md` Rating star 20/24/24(identity scale,cite Ant/Material/Airbnb)
+ * - `avatar.spec.md` Avatar 內 icon `round_even(size × 0.6)`(Material/Apple HIG)
+ * - `empty.tsx` Empty 用 Avatar 48 wrap → icon 28(Avatar formula derived)
+ * - `file-viewer.tsx` thumb 64 → icon 20(thumbnail file-type indicator,hardcode 無公式)
+ * - `circular-progress.tsx` `strokeWidth = max(2, size/10)`(stroke ring 厚度公式,非 icon)
+ * - `steps.tsx` INDICATOR_ICON_SIZE `{sm:0, md:16, lg:20}`(部分對齊 tier,sm 因圓圈 8px 太小)
+ * - `slider.tsx` thumb 固定不隨 size 變(視覺 single tier)
+ * - `checkbox.tsx` + `switch.tsx` check `{sm:12, md:12, lg:16}`(form-control internal,stroke 下限)
+ *
+ * 詳 uiSize.spec.md「跨 regime pointer index」段。
+ */
+export { ICON_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'
+export type { RowSize } from '@/design-system/patterns/element-anatomy/item-anatomy'

package/src/tokens/uiSize/uiSize.css

@@ -0,0 +1,125 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   Component Size — Semantic Tokens
+   ═══════════════════════════════════════════════════════════════════════
+
+   元件高度的語義 token。rem 單位，尊重使用者瀏覽器字體設定（WCAG）。
+   透過 data-density 切換 md / lg 模式。
+
+   ┌─ Field Height ────────────────────────────────────────────────────┐
+   │  Button、Input、Checkbox/Radio SelectionItem 等互動元件      │
+   │  xs 固定不隨 density 縮放（密集 UI、Button xs）                   │
+   │  sm / md / lg 隨 density 響應                                    │
+   └─────────────────────────────────────────────────────────────────┘
+
+   ┌─ Table Row ───────────────────────────────────────────────────────┐
+   │  DataTable 行高                                                  │
+   │  sm / md / lg 三種尺寸，density 切換統一 +0.5rem (+8px)          │
+   └─────────────────────────────────────────────────────────────────┘
+   ═══════════════════════════════════════════════════════════════════════ */
+
+:root {
+  /* Field Height — Button、Input、SelectionItem、SegmentedControl */
+  --field-height-xs: 1.5rem;    /* 24px — 固定，不隨 density 縮放 */
+  --field-height-sm: 1.75rem;   /* 28px */
+  --field-height-md: 2rem;      /* 32px */
+  --field-height-lg: 2.25rem;   /* 36px */
+
+  /* Table Row Height — DataTable */
+  --table-row-sm: 2rem;         /* 32px */
+  --table-row-md: 2.5rem;       /* 40px */
+  --table-row-lg: 3rem;         /* 48px */
+
+  /* Tab Height — Tabs
+     獨立於 field-height 與 table-row：tabs 是 navigation container，
+     需要比 form control 更大的呼吸感。數值目前與 table-row 對齊，
+     但概念獨立，不用 var() alias — 未來任何一方調整都不牽動另一方。 */
+  --tab-height-sm: 2rem;        /* 32px — ★ 預設(2026-05-17 從 md 改),overlay / chrome / dense */
+  --tab-height-md: 2.5rem;      /* 40px — future tier(無 recommended use case,2026-05-17 從 default 降級) */
+  --tab-height-lg: 3rem;        /* 48px — 獨立 tabs 取代 chrome header(= --chrome-header-height) */
+
+  /* Chrome Header Height — Sidebar / FileViewer Toolbar+InfoPanel / app top bar / page header
+     + Overlay family chrome (Dialog/Sheet/Popover/Coachmark header+footer via overlay-surface SurfaceHeader/SurfaceFooter)
+     (SSOT,2026-05-23 deep-audit Phase A Decision 1 codify per user verbatim「決策一照你建議」 —
+     從 src/globals.css 搬到 DS tokens 因 npm-package consumer 沒 src/globals.css 會崩 header 高度,違 M17 SSOT 鐵律)
+     consumer:patterns/header-canonical/chrome-header.tsx、overlay-surface.tsx、dialog.tsx 等
+     世界級對照:Linear 48px / Atlassian 48-56 / Material small AppBar 48-56 / VS Code activity-bar 48
+     ── 為什麼是 48 / 56(hardcode,非公式) ──
+     世界級 app 的 header 高度集中在 40–64px,甜蜜點 48–56。
+     兩個值都 snap 到 8px grid。anchor 是 field-height-md(容納 md Button + 上下呼吸空間)。
+     不寫成 calc() 公式因為 lg 無法完美遵守(54 → 56 為了 8px grid 取整),hardcode 比假公式誠實。 */
+  --chrome-header-height: 3rem; /* 48px */
+
+  /* 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 */
+  --tree-indent-sm: 1.5rem;     /* 24px */
+  --tree-indent-md: 1.5rem;     /* 24px */
+  --tree-indent-lg: 1.75rem;    /* 28px */
+
+  /* DataTable Panel Widths — Sort manager / Filter panel cells(SSOT,2026-05-23 deep-audit Phase A.4 Decision 2 codify per user verbatim「決策二照你建議做」+「確保最SSOT最簡潔」)
+     Consumer:data-table-sort-manager.tsx / data-table-filter-panel.tsx
+     不 density-scale(panels 是 floating layout,不該跟密度走)
+     Naming aligned to family `--<component>-<part>-<size>`(per --field-height-* / --table-row-* / --tab-height-* precedent)*/
+  --data-table-sort-panel-width: 30rem;       /* 480px — sort manager root container width */
+  --data-table-filter-field-width: 10rem;     /* 160px — filter cell column selector(flat + nested 同 width) */
+  --data-table-filter-op-width: 7.5rem;       /* 120px — filter cell operator selector(when value cell exists) */
+}
+
+[data-ui-size="lg"],
+[data-density="lg"] {
+  --field-height-sm: 2rem;      /* 32px */
+  --field-height-md: 2.25rem;   /* 36px */
+  --field-height-lg: 2.5rem;    /* 40px */
+
+  --table-row-sm: 2.5rem;       /* 40px */
+  --table-row-md: 3rem;         /* 48px */
+  --table-row-lg: 3.5rem;       /* 56px */
+
+  --tab-height-sm: 2.5rem;      /* 40px */
+  --tab-height-md: 3rem;        /* 48px */
+  --tab-height-lg: 3.5rem;      /* 56px */
+
+  --chrome-header-height: 3.5rem; /* 56px(lg density) */
+}
+
+/* 2026-04-22:md reset selector — 當祖先層級(e.g. html[data-density="lg"])已 cascading
+   lg overrides 下來,subtree 元件(Popover / DropdownMenu / Tooltip 等)宣告 `data-density="md"`
+   或 `data-ui-size="md"` 時必須能 reset 回 md default,否則 Portal 逃逸 + cascading
+   會讓 lock md 失效(Meta-Pattern M3 Portal subtree context drift 類)。 */
+[data-ui-size="md"],
+[data-density="md"] {
+  --field-height-sm: 1.75rem;   /* 28px — md default */
+  --field-height-md: 2rem;      /* 32px — md default */
+  --field-height-lg: 2.25rem;   /* 36px — md default */
+
+  --table-row-sm: 2rem;         /* 32px */
+  --table-row-md: 2.5rem;       /* 40px */
+  --table-row-lg: 3rem;         /* 48px */
+
+  --tab-height-sm: 2rem;        /* 32px */
+  --tab-height-md: 2.5rem;      /* 40px */
+  --tab-height-lg: 3rem;        /* 48px */
+
+  --tree-indent-sm: 1.5rem;     /* 24px — md default */
+  --tree-indent-md: 1.5rem;     /* 24px — md default */
+  --tree-indent-lg: 1.75rem;    /* 28px — md default */
+}
+
+
+/* ── Tailwind Theme Bridge ──
+   橋接成 spacing utility，讓 h-field-md / h-table-row-lg 等 class 可用 */
+@theme inline {
+  --spacing-field-xs:    var(--field-height-xs);
+  --spacing-field-sm:    var(--field-height-sm);
+  --spacing-field-md:    var(--field-height-md);
+  --spacing-field-lg:    var(--field-height-lg);
+  --spacing-table-row-sm: var(--table-row-sm);
+  --spacing-table-row-md: var(--table-row-md);
+  --spacing-table-row-lg: var(--table-row-lg);
+  --spacing-tab-sm: var(--tab-height-sm);
+  --spacing-tab-md: var(--tab-height-md);
+  --spacing-tab-lg: var(--tab-height-lg);
+  --spacing-tree-indent-sm: var(--tree-indent-sm);
+  --spacing-tree-indent-md: var(--tree-indent-md);
+  --spacing-tree-indent-lg: var(--tree-indent-lg);
+}