@qijenchen/design-system 0.1.0-beta.10

package/src/tokens/color/semantic.css

@@ -0,0 +1,539 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   Semantic Tokens — Layer 2
+   ═══════════════════════════════════════════════════════════════════════
+
+   架構流派：Atlassian-style Semantic State Token（見 color.spec.md「架構流派定位」）
+   核心原則：靜態色用 primitive（無 mode 知識），互動狀態用 semantic（封裝 mode swap）
+
+   ┌─ 元件如何消費 ──────────────────────────────────────────────────────┐
+   │  Button / Checkbox / Badge（語義元件）                              │
+   │    → 用 semantic 全套：--primary、--primary-hover、--primary-text   │
+   │                                                                     │
+   │  Tag / Avatar（分類元件）— 有意的混合存取                            │
+   │    → 靜態色用 primitive：--color-blue-1、--color-blue-6、-7         │
+   │      （bg、subtle、text 沒有 mode 翻轉問題）                         │
+   │    → 互動色用 semantic hue token：--blue-hover、--blue-active       │
+   │      （hover/active 需要 dark mode swap，必須住 semantic 層）        │
+   │                                                                     │
+   │  ⚠ 「混合存取」不是 code smell——是有意的職責分離                   │
+   │    靜態色與互動狀態本來就是兩個不同概念，不該綁同一層。              │
+   │    Tailwind 也是同樣分離（bg-blue-500 vs hover:bg-blue-600）。       │
+   │                                                                     │
+   │  分類 vs 語義為何兩條 namespace？                                    │
+   │    Tag 的「藍」≠ semantic「primary」。改 primary 從藍變紫，         │
+   │    Tag 的 blue variant 不該跟著變。所以分類用 primitive 解耦，      │
+   │    semantic 用 purpose token 表達意圖。                              │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   ┌─ 命名原則 ────────────────────────────────────────────────────────────┐
+   │  短名稱（無 --color- 前綴），對應到 Layer 1 原始色票                │
+   │  以語義 purpose 命名（primary / error / info / success / warning…） │
+   │  shadcn compat aliases 已於 2026-04-18 全數移除                      │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   ┌─ Surface 分層（非常重要）────────────────────────────────────────────┐
+   │  --canvas        頁面最底層（HTML body 背景）                       │
+   │  --surface       非遮蓋型容器（card、sidebar、table 等）             │
+   │                  dark mode 使用半透明，可疊加在 canvas 上            │
+   │  --surface-raised 遮蓋型浮層（modal、popover、dropdown、lightbox）  │
+   │                  必須不透明，避免底層內容透出                        │
+   │                  **含 overlay 內 chrome**：FileViewer toolbar /     │
+   │                  filmstrip / sidebar、Dialog footer 等 raised       │
+   │                  surface 都套此 token（不用 canvas、不用 surface）  │
+   │  --overlay       backdrop 遮罩（dialog 背後的半透明黑）              │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   ┌─ 文字 / Icon 層級 ───────────────────────────────────────────────────┐
+   │  --foreground      一般資訊（neutral-9）                            │
+   │  --fg-secondary    較次要的資訊、helper text（neutral-8）            │
+   │  --fg-muted        placeholder、caption、弱化 icon（neutral-7）     │
+   │  --fg-disabled     disabled 文字（neutral-6）                       │
+   │                                                                     │
+   │  文字色一律使用 neutral alpha，透明度疊加在任何背景皆可維持對比      │
+   │  弱化 icon hover 後變 fg-secondary（neutral-8）                     │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   ┌─ 互動狀態（引用色盤 step）─────────────────────────────────────────────┐
+   │  Light: hover = step -5（較亮），active = step -7（較暗）           │
+   │  Dark:  hover = step -7（較亮），active = step -5（較暗）           │
+   │                                                                     │
+   │  相對色階公式保證 -5 永遠比 base 亮、-7 永遠比 base 暗。           │
+   │  高亮度色相（yellow 等）的 hover gap 較小，這是物理事實——           │
+   │  cursor 變化 + 細微色移疊加仍提供足夠回饋。                         │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   ┌─ 邊框 / 分隔 ─────────────────────────────────────────────────────────┐
+   │  --border        元件邊框（neutral-5）                              │
+   │  --border-hover  input/checkbox/radio hover 邊框（neutral-6）       │
+   │  --divider       分隔線（neutral-4，比 border 更淡）                │
+   │  --ring          focus 輪廓（= primary）                           │
+   │  選中狀態的邊框或文字 → 直接使用 var(--primary-hover)              │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   ┌─ Static Subtle ─────────────────────────────────────────────────────┐
+   │  --muted          弱化底色 Tag neutral（neutral-2）                 │
+   │  --secondary      Badge low 底色（neutral-3，比 muted 深一階）      │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   ┌─ 中性互動背景（兩個獨立 family）─────────────────────────────────────┐
+   │  Default state family（non-selected element 的互動）                │
+   │    --neutral-hover        hover 回饋          = neutral-1            │
+   │    --neutral-active       :active click 回饋 = neutral-2            │
+   │                                                                     │
+   │  Selected state family（toggle on / 持續選中 element 的互動）       │
+   │    --neutral-selected         rest 持續選中   = neutral-2            │
+   │    --neutral-selected-hover   hover（變淺）   = neutral-1            │
+   │    --neutral-selected-active  :active 深一階  = neutral-3            │
+   │                                                                     │
+   │  --bg-disabled                互動元件 disabled 背景  = neutral-2    │
+   │                                                                     │
+   │  ⚠ active vs selected 語意區分（見 color.spec.md「active vs selected」）│
+   │    active   = :active 瞬間 click 回饋（transient）                  │
+   │    selected = 持續 toggle on / 長時間選中狀態（persistent）          │
+   │    值相同不代表應合併 token——語意獨立就該是獨立 token，             │
+   │    未來若 selected 視覺需獨立演化不影響 active。                    │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   ┌─ Nested Theme 架構 ─────────────────────────────────────────────────┐
+   │  CSS 變數在定義元素解析，子孫繼承的是結果不是 var() 表達式。        │
+   │  為了支援 nested theme（如 tooltip 內 data-theme="dark"），         │
+   │  所有語義 token 用 :root, [data-theme] 定義，                       │
+   │  每個 theme 邊界重新解析。                                          │
+   │                                                                     │
+   │  三層結構：                                                         │
+   │    ① :root               — 只有 --brand（永遠不變）                │
+   │    ② :root, [data-theme] — 所有語義 token（default = light）       │
+   │    ③ [data-theme="dark"] — 只覆寫跟 light 不同的值                 │
+   │                                                                     │
+   │  判斷標準只有一個：「這個 token 在 dark 要不要變？」                │
+   │    要 → ② 寫 light 預設，③ 覆寫 dark 值                           │
+   │    不要 → 只寫在 ②                                                 │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   ┌─ Tailwind utility 一覽（@theme inline 橋接）─────────────────────────┐
+   │  Surface     bg-canvas / bg-surface / bg-surface-raised              │
+   │              bg-overlay / bg-tooltip                                 │
+   │  Text level  text-foreground / text-fg-secondary / text-fg-muted    │
+   │              text-fg-disabled / text-inverse-fg                      │
+   │  Semantic    bg-primary / bg-info / bg-error / bg-success / bg-warning│
+   │   (base)     text-{primary|info|error|success|warning}              │
+   │   (hover)    hover:bg-{primary|info|error|success|warning}-hover    │
+   │   (active)   active:bg-{primary|info|error|success|warning}-active  │
+   │   (subtle)   bg-{primary|info|error|success|warning}-subtle         │
+   │   (text)     text-{info|error|success|warning}-text                  │
+   │                  ↑ 用於 subtle bg 上的文字（資訊呈現）                │
+   │  Special     text-warning-foreground（yellow solid 例外）            │
+   │  Neutral     bg-neutral-hover / bg-neutral-active / bg-disabled     │
+   │              bg-neutral-selected / bg-neutral-selected-hover /       │
+   │              bg-neutral-selected-active                              │
+   │              bg-muted / bg-secondary                                 │
+   │  Border      border-border / border-border-hover / border-divider   │
+   │  Focus       ring-ring                                               │
+   │  Inverse     bg-inverse-neutral-hover / bg-inverse-neutral-active   │
+   │              （solid neutral 上的互動 overlay）                      │
+   │                                                                      │
+   │  Tag/Avatar 的色相 hover/active 用 var() 直接引用：                  │
+   │     hover: var(--blue-hover) / var(--red-hover) / ...                │
+   │     （不橋接成 utility class——只有 Tag/Avatar dismiss 一個 consumer）│
+   └─────────────────────────────────────────────────────────────────────┘
+
+   選中邊框/文字 → border-[var(--primary-hover)] / text-[var(--primary-hover)]
+   ═══════════════════════════════════════════════════════════════════════ */
+
+
+/* ── ① Fixed — 永遠不變，不隨 theme 切換 ── */
+:root {
+  --brand:                #DF3232;
+}
+
+
+/* ── ② All Semantic Tokens（default = light）──
+   :root, [data-theme] 讓每個 theme 邊界重新解析。
+   所有語義 token 都在這裡。dark 要改的在 ③ 覆寫。 */
+:root, [data-theme] {
+
+  /* Surface — 2026-05-20 fix(user 抓 raw oklch 違反 semantic 直指 primitive 規則):
+     從 raw oklch(1 0 0) 改指 primitive --color-white(L66 absolute anchor) */
+  --canvas:               var(--color-white);
+  --surface:              var(--color-white);
+  --surface-raised:       var(--color-white);
+  /* --surface-strong:強 emphasis 中性 surface(2026-05-07 v15.15 user 拍板 final)。
+     Material 3 `surface-container-high` / Atlassian `color.background.neutral.bold` 對應。
+     用途:avatar overlay dismiss button bg / overflow indicator badge / 強調中性 surface。
+     hover 兩 mode 都走 neutral-7-opaque(step-7 在 dark mode 自動 lighter 公式 →
+     對稱「engaged」感:light hover 變深 / dark hover 變亮)。
+     **用 -opaque variant**(對齊 `--surface-raised` 既有 opaque convention):surface 是
+     視覺底色 layer,alpha 跟下層 bg compositing 致視覺位移 + colorMix accuracy 不可靠。 */
+  --surface-strong:       var(--color-neutral-6-opaque);
+  --surface-strong-hover: var(--color-neutral-7-opaque);
+  --overlay:              var(--black-a45);
+  --tooltip:              var(--color-neutral-9-opaque);
+
+  /* 文字 / Icon */
+  --foreground:           var(--color-neutral-9);
+  --warning-foreground:   var(--black-a85);
+  --fg-secondary:         var(--color-neutral-8);
+  --fg-muted:             var(--color-neutral-7);
+  --fg-disabled:          var(--color-neutral-6);
+
+  /* On-emphasis:飽和色底的對比文字(white on filled surface)
+     消費者:Avatar color variants(blue/red/green/... fill + on-emphasis text)
+           Steps filled indicator(completed/active 的 icon 色)
+     為什麼獨立 token:foreground 是 neutral 文字色,warning-foreground 是 warning
+     子場景 amber 底的對比,都不是「任何飽和色底的通用對比」。Polaris 叫 text-onEmphasis,
+     Material 叫 on-primary/on-secondary family。我們用 on-emphasis 保持通用。
+     Dark mode 不反轉(白字在飽和色底永遠白)
+     2026-05-20 fix:raw oklch → primitive --color-white */
+  --on-emphasis:          var(--color-white);
+
+  /* Brand / Action — 品牌主操作色
+     --primary-text 為 SOP 規定的 5 件套之一，目前無消費者
+     （Button 直接用 text-white, Tag 用 primitive --color-blue-7） */
+  --primary:              var(--color-blue-6);
+  --primary-hover:        var(--color-blue-5);
+  --primary-active:       var(--color-blue-7);
+  --primary-subtle:       var(--color-blue-1);
+  --primary-text:         var(--color-blue-7);
+
+  /* Status: Info — 資訊狀態色
+     目前指向 blue（與 primary 同源），但語義獨立——如未來 brand 改色，
+     primary 跟著改，info 仍維持「資訊=藍」的通用慣例 */
+  --info:                 var(--color-blue-6);
+  --info-hover:           var(--color-blue-5);
+  --info-active:          var(--color-blue-7);
+  --info-subtle:          var(--color-blue-1);
+  --info-text:            var(--color-blue-7);
+
+  /* Status: Error — 指向 primitive deep-orange */
+  --error:                var(--color-deep-orange-6);
+  --error-hover:          var(--color-deep-orange-5);
+  --error-active:         var(--color-deep-orange-7);
+  --error-subtle:         var(--color-deep-orange-1);
+  --error-text:           var(--color-deep-orange-7);
+
+  /* Status: Success — 指向 primitive green */
+  --success:              var(--color-green-6);
+  --success-hover:        var(--color-green-5);
+  --success-active:       var(--color-green-7);
+  --success-subtle:       var(--color-green-1);
+  --success-text:         var(--color-green-7);
+
+  /* Status: Warning — 指向 primitive yellow */
+  --warning:              var(--color-yellow-6);
+  --warning-hover:        var(--color-yellow-5);
+  --warning-active:       var(--color-yellow-7);
+  --warning-subtle:       var(--color-yellow-1);
+  --warning-text:         var(--color-yellow-7);
+
+  /* Hue Interaction Tokens — 色相 bg 的 hover / active 互動狀態
+     ─────────────────────────────────────────────────────────────────
+     用途：作為 bg 使用的飽和色相（Tag/Avatar solid 等）的 hover/active 狀態。
+
+     設計原則：跟 --primary-hover/active 同模式——solid 色彩 shade change
+     （hover 較亮 step、active 較暗 step），跨整個設計系統視覺一致。
+
+     存在原因：直接用 primitive `--color-{hue}-5/7` 在 dark mode 公式翻轉
+     方向錯誤，需要 semantic 層做 dark mode swap 維持「hover lift / active
+     press」方向跨 mode 一致。
+
+     刻意只有 hover/active：base/subtle/text 必須直接用 primitive
+     （`--color-{hue}-6` / `-1` / `-7`）。沒有 `--blue` base 或 `--blue-subtle`
+     等 token，避免重新引入完整 categorical 層。
+
+     不要混淆為「categorical 復辟」：這是 semantic 互動 token 從 brand color
+     擴展到所有作為 bg 的色相，跟 --primary-hover 同邏輯、同層級。
+     ───────────────────────────────────────────────────────────────── */
+  --blue-hover:           var(--color-blue-5);
+  --blue-active:          var(--color-blue-7);
+  /* 2026-05-20 fix(codex Layer B D1 Bug 1):red 之前誤映射 deep-orange,red 跟 deep-orange 是
+     primitive 12 hue 內兩個 distinct 色相(hue 25 vs 38;lightness 0.46 vs 0.58)。red/error
+     不該共名空間 — `--error-*` semantic 自己直接指 primitive deep-orange,`--red-*` hue
+     interaction 必指 primitive red。 */
+  --red-hover:            var(--color-red-5);
+  --red-active:           var(--color-red-7);
+  --deep-orange-hover:    var(--color-deep-orange-5);
+  --deep-orange-active:   var(--color-deep-orange-7);
+  --orange-hover:         var(--color-orange-5);
+  --orange-active:        var(--color-orange-7);
+  --amber-hover:          var(--color-amber-5);
+  --amber-active:         var(--color-amber-7);
+  --lime-hover:           var(--color-lime-5);
+  --lime-active:          var(--color-lime-7);
+  --green-hover:          var(--color-green-5);
+  --green-active:         var(--color-green-7);
+  --yellow-hover:         var(--color-yellow-5);
+  --yellow-active:        var(--color-yellow-7);
+  --turquoise-hover:      var(--color-turquoise-5);
+  --turquoise-active:     var(--color-turquoise-7);
+  --purple-hover:         var(--color-purple-5);
+  --purple-active:        var(--color-purple-7);
+  --magenta-hover:        var(--color-magenta-5);
+  --magenta-active:       var(--color-magenta-7);
+  --indigo-hover:         var(--color-indigo-5);
+  --indigo-active:        var(--color-indigo-7);
+
+  /* Inverse — solid neutral（neutral-9）背景上的內容
+     neutral 在 dark mode 反轉（近黑 → 近白），上面的文字與互動覆蓋層也要反轉
+     - --inverse-fg 對應 --foreground（文字 base）
+     - --inverse-neutral-hover/active 對應 --neutral-hover/active（互動覆蓋層）
+     - 未來擴充：--inverse-fg-secondary/muted/disabled 對齊 --fg-* 變體
+
+     ┌─ Inverse-neutral-* 數值規則（嚴格對稱）─────────────────────────┐
+     │  --inverse-neutral-* 在某 mode 的值 = --neutral-* 在「另一 mode」 │
+     │  的值。即 inverse 是 neutral 的 mode 鏡射。                       │
+     │                                                                  │
+     │  light --inverse-neutral-hover  = white @ 4% (= dark neutral-1)  │
+     │  light --inverse-neutral-active = white @ 8% (= dark neutral-2)  │
+     │  dark  --inverse-neutral-hover  = black @ 2% (= light neutral-1) │
+     │  dark  --inverse-neutral-active = black @ 4% (= light neutral-2) │
+     │                                                                  │
+     │  好處：完全對稱、重用既有 tuned values、自動繼承感知補償          │
+     └────────────────────────────────────────────────────────────────┘
+     2026-05-20 fix:raw oklch → primitive --color-white(light)/ --black-a85(dark)*/
+  --inverse-fg:               var(--color-white);
+  --inverse-neutral-hover:    var(--white-a04);
+  --inverse-neutral-active:   var(--white-a08);
+
+  /* Notification */
+  --notification:         var(--color-deep-orange-6);
+
+  /* Presence Status — 使用者線上狀態指示(Avatar 右下角 badge)
+     語義 token 而非直接用 --success / --error / --warning,因為 presence 與
+     「操作成功 / 操作錯誤 / 警告」語境不同,未來可能獨立演化(例如 brand 要
+     把 online 改成更明顯的霓虹綠)。世界級對照:Slack / Teams / Discord /
+     Linear 都有獨立的 presence namespace */
+  --status-online:        var(--color-green-6);    /* 在線(對齊 success 色相) */
+  --status-busy:          var(--color-deep-orange-6); /* 忙碌(對齊 error 色相,強烈可見) */
+  --status-away:          var(--color-yellow-6);   /* 離開(對齊 warning 色相) */
+  --status-offline:       var(--color-neutral-6-opaque);  /* 離線(neutral,弱化;2026-05-15 user 拍板 → opaque tier 對齊 --border-opaque / --surface-strong alpha-immune idiom,避免 status dot 疊在非白 bg cell 時 alpha compositing 致視覺漂移)*/
+
+  /* Border / Divider */
+  --border:               var(--color-neutral-5);  /* 元件標準邊框 */
+  --border-hover:         var(--color-neutral-6);  /* input、checkbox、radio hover 邊框 */
+  --border-opaque:        var(--color-neutral-5-opaque);  /* 視覺等同 --border (#D9D9D9 on white)但 alpha-immune。何時用:cell bg 非白 (e.g. disabled 灰底 / nested surface) 時,alpha 邊框會跟 bg compositing 致視覺位移。用此 token 維持邊框視覺一致。對齊 Ant colorBorderSecondary solid idiom。一般白底場景仍用 --border (alpha) */
+  --divider:              var(--color-neutral-4);  /* 分隔線，比 border 更淡 */
+  --ring:                 var(--primary);           /* focus ring */
+
+  /* Neutral Interactive — Default state family
+     用於 non-selected element 的互動回饋 */
+  --neutral-hover:        var(--color-neutral-1);
+  --neutral-active:       var(--color-neutral-2);
+  --bg-disabled:          var(--color-neutral-2);
+
+  /* Neutral Interactive — Selected state family
+     ─────────────────────────────────────────────────────────────
+     用於 toggle on / 持續選中 element 的互動回饋。
+
+     值與 default family 可能重疊，但語意獨立——未來若 selected
+     視覺需獨立演化（例：改用 brand tint），只需改此組不影響 default。
+
+     命名對齊既有 --inverse-neutral-* 的 compound namespace 模式：
+       namespace = neutral-selected（複合）
+       role      = hover / active
+
+     語意區分（見 color.spec.md「active vs selected」）：
+       --neutral-active  = :active 瞬間 click 回饋（transient）
+       --neutral-selected = 持續 toggle on / 長時間選中（persistent）
+
+     典型消費者：Button text variant pressed、DropdownMenu 單選項目、
+     SelectMenu 單選項目、Tab active、menu item selected。 */
+  --neutral-selected:         var(--color-neutral-2);
+  --neutral-selected-hover:   var(--color-neutral-1);
+  --neutral-selected-active:  var(--color-neutral-3);
+
+  /* Static Subtle — 靜態弱化背景(2026-05-20 v3 註解濃縮原則,SSOT 詳 color.spec.md「Static Subtle Background」段)*/
+  /* 判斷:「這元素是『還沒準備好 / 不可操作 / placeholder』嗎?」是 → muted / 否,只是視覺退後 → secondary */
+  --muted:                var(--color-neutral-2);  /* 退化 / placeholder / locked surface:Skeleton / DataTable header / Calendar 非當月 / Alert neutral / scrollbar track */
+  --secondary:            var(--color-neutral-3);  /* 存在但視覺退後一級:Tag neutral / Slider rest / Badge low / FileItem progress / ProgressBar / CircularProgress / Steps fillBg */
+
+  /* Scrollbar — Lane / chrome / thumb(2026-05-09 抽 SSOT,DataTable fake + ScrollArea 共享)
+     Track 用 --muted(靜態 lane,非 disabled 元件 bg);Thumb 用 --border(中性低對比 chrome)。
+     對齊 shadcn ScrollArea(thumb=bg-border)/ MUI X DataGrid scrollbar slot / AG Grid grid theme tokens。
+     避免直接借 --bg-disabled(color.spec.md:169 語意 drift)— bg-disabled 是互動元件 disabled bg,跟 scrollbar lane 不同。 */
+  --scrollbar-track:       var(--muted);
+  --scrollbar-thumb:       var(--border);
+  --scrollbar-thumb-hover: var(--border-hover);
+
+  /* Chart categorical — 5 色類別標記（Chart 元件消費）
+     挑 step-6 確保對 surface-raised 的對比足夠,5 色差異明顯便於區分。
+     chart-1..5 固定到 primitive 而非 semantic（避免未來 brand swap 時 chart 跟著改 → 誤導 data viz）。 */
+  --chart-1:              var(--color-blue-6);
+  --chart-2:              var(--color-purple-6);
+  --chart-3:              var(--color-green-6);
+  --chart-4:              var(--color-yellow-7);
+  --chart-5:              var(--color-deep-orange-6);
+}
+
+
+/* ── ③ Dark-Only — 覆寫與 light 不同的值 ──
+   同 specificity，後面贏，蓋掉 ② 的預設值。 */
+[data-theme="dark"] {
+
+  /* Surface */
+  --canvas:               var(--color-neutral-1-opaque);
+  --surface:              var(--white-a08);
+  --surface-raised:       var(--color-neutral-3-opaque);
+  /* --surface-strong:dark mode 跟 light 同 step(neutral-7-opaque),step-7 dark 公式自動 lighter → engaged */
+  --surface-strong:       var(--color-neutral-6-opaque);
+  --surface-strong-hover: var(--color-neutral-7-opaque);
+  --overlay:              var(--black-a65);
+  --tooltip:              var(--color-neutral-5-opaque);
+
+  /* Semantic hover/active 方向反轉（dark: hover=step-7, active=step-5）
+     subtle 和 text 不需要覆寫——primitives 已在 dark mode 處理
+     （step-1 用 alpha 公式，step-7 用 lighter 公式） */
+  --primary-hover:        var(--color-blue-7);
+  --primary-active:       var(--color-blue-5);
+  --info-hover:           var(--color-blue-7);
+  --info-active:          var(--color-blue-5);
+  --error-hover:          var(--color-deep-orange-7);
+  --error-active:         var(--color-deep-orange-5);
+  --success-hover:        var(--color-green-7);
+  --success-active:       var(--color-green-5);
+  --warning-hover:        var(--color-yellow-7);
+  --warning-active:       var(--color-yellow-5);
+
+  /* Hue interaction tokens — 同樣的方向反轉(hover 永遠較亮、active 永遠較暗)
+     2026-05-20 fix(codex Layer B D1):red 改指 primitive red(非 deep-orange)+ 補 deep-orange /
+     orange / amber / lime 4 個 missing hue interaction(per primitive 12 hue full coverage)*/
+  --blue-hover:           var(--color-blue-7);
+  --blue-active:          var(--color-blue-5);
+  --red-hover:            var(--color-red-7);
+  --red-active:           var(--color-red-5);
+  --deep-orange-hover:    var(--color-deep-orange-7);
+  --deep-orange-active:   var(--color-deep-orange-5);
+  --orange-hover:         var(--color-orange-7);
+  --orange-active:        var(--color-orange-5);
+  --amber-hover:          var(--color-amber-7);
+  --amber-active:         var(--color-amber-5);
+  --lime-hover:           var(--color-lime-7);
+  --lime-active:          var(--color-lime-5);
+  --green-hover:          var(--color-green-7);
+  --green-active:         var(--color-green-5);
+  --yellow-hover:         var(--color-yellow-7);
+  --yellow-active:        var(--color-yellow-5);
+  --turquoise-hover:      var(--color-turquoise-7);
+  --turquoise-active:     var(--color-turquoise-5);
+  --purple-hover:         var(--color-purple-7);
+  --purple-active:        var(--color-purple-5);
+  --magenta-hover:        var(--color-magenta-7);
+  --magenta-active:       var(--color-magenta-5);
+  --indigo-hover:         var(--color-indigo-7);
+  --indigo-active:        var(--color-indigo-5);
+
+  /* Inverse — dark mode 反轉（深字 + 黑色透明 overlay）
+     overlay 值為 light mode neutral-* 的鏡射（black @ 2% / 4%）
+     2026-05-20 fix:raw oklch → primitive --black-a85(既有 alpha token,L46)*/
+  --inverse-fg:               var(--black-a85);
+  --inverse-neutral-hover:    var(--black-a02);
+  --inverse-neutral-active:   var(--black-a04);
+
+  /* Chart — dark mode 用 step-5（較淡）提升對 dark surface 的可讀度 */
+  --chart-1:                  var(--color-blue-5);
+  --chart-2:                  var(--color-purple-5);
+  --chart-3:                  var(--color-green-5);
+  --chart-4:                  var(--color-yellow-5);
+  --chart-5:                  var(--color-deep-orange-5);
+}
+
+
+/* ── Tailwind Utility Bridge ── */
+@theme inline {
+
+  /* Canvas / Surface */
+  --color-canvas:                var(--canvas);
+  --color-surface:               var(--surface);
+  --color-surface-raised:        var(--surface-raised);
+  --color-surface-strong:        var(--surface-strong);
+  --color-surface-strong-hover:  var(--surface-strong-hover);
+
+  /* Foreground */
+  --color-foreground:            var(--foreground);
+  --color-on-emphasis:           var(--on-emphasis);
+
+  /* Primary */
+  --color-primary:               var(--primary);
+
+  /* Secondary / Muted */
+  --color-secondary:             var(--secondary);
+  --color-muted:                 var(--muted);
+
+  /* Status */
+  --color-info:                  var(--info);
+  --color-error:                 var(--error);
+  --color-success:               var(--success);
+  --color-warning:               var(--warning);
+  --color-warning-foreground:    var(--warning-foreground);
+  --color-notification:          var(--notification);
+
+  /* Presence Status(Avatar badge) */
+  --color-status-online:         var(--status-online);
+  --color-status-busy:           var(--status-busy);
+  --color-status-away:           var(--status-away);
+  --color-status-offline:        var(--status-offline);
+
+  /* Hover / Active */
+  --color-primary-hover:         var(--primary-hover);
+  --color-primary-active:        var(--primary-active);
+  --color-info-hover:            var(--info-hover);
+  --color-info-active:           var(--info-active);
+  --color-error-hover:           var(--error-hover);
+  --color-error-active:          var(--error-active);
+  --color-success-hover:         var(--success-hover);
+  --color-success-active:        var(--success-active);
+  --color-warning-hover:         var(--warning-hover);
+  --color-warning-active:        var(--warning-active);
+
+  /* Subtle */
+  --color-info-subtle:           var(--info-subtle);
+  --color-primary-subtle:        var(--primary-subtle);
+  --color-error-subtle:          var(--error-subtle);
+  --color-success-subtle:        var(--success-subtle);
+  --color-warning-subtle:        var(--warning-subtle);
+
+  /* Text on subtle bg（step-7，不隨 dark mode 反轉） */
+  --color-info-text:             var(--info-text);
+  --color-error-text:            var(--error-text);
+  --color-success-text:          var(--success-text);
+  --color-warning-text:          var(--warning-text);
+
+  /* Inverse — solid neutral surface 上的內容 */
+  --color-inverse-fg:                var(--inverse-fg);
+  --color-inverse-neutral-hover:     var(--inverse-neutral-hover);
+  --color-inverse-neutral-active:    var(--inverse-neutral-active);
+
+  /* Neutral Interaction — Default state */
+  --color-neutral-hover:             var(--neutral-hover);
+  --color-neutral-active:            var(--neutral-active);
+  --color-disabled:                  var(--bg-disabled);
+
+  /* Neutral Interaction — Selected state family */
+  --color-neutral-selected:          var(--neutral-selected);
+  --color-neutral-selected-hover:    var(--neutral-selected-hover);
+  --color-neutral-selected-active:   var(--neutral-selected-active);
+
+  /* Surface Utility */
+  --color-overlay:               var(--overlay);
+  --color-tooltip:               var(--tooltip);
+  --color-divider:               var(--divider);
+
+  /* Chart categorical（Chart 元件消費;data viz 用） */
+  --color-chart-1:               var(--chart-1);
+  --color-chart-2:               var(--chart-2);
+  --color-chart-3:               var(--chart-3);
+  --color-chart-4:               var(--chart-4);
+  --color-chart-5:               var(--chart-5);
+
+  /* Text / Icon levels */
+  --color-fg-secondary:          var(--fg-secondary);
+  --color-fg-muted:              var(--fg-muted);
+  --color-fg-disabled:           var(--fg-disabled);
+
+  /* Border / Ring */
+  --color-border:                var(--border);
+  --color-border-hover:          var(--border-hover);
+  --color-ring:                  var(--ring);
+
+  /* Branding */
+  --color-brand:                 var(--brand);
+}

package/src/tokens/elevation/overlay-geometry.ts

@@ -0,0 +1,13 @@
+/**
+ * Overlay geometry SSOT — Radix prop number constants(non-CSS-var,JS-side single source).
+ *
+ * Why JS const not CSS var:Radix `sideOffset` / `collisionPadding` 接 number prop,
+ * 不接 `var(--...)`。改值要動 5+ primitive default = 假 SSOT。本檔抽 const,
+ * primitive default 統一 import → 改值只動一處全部聯動。
+ *
+ * Canonical source:`elevation.spec.md` § 浮層間距 sideOffset。
+ */
+
+export const OVERLAY_SIDE_OFFSET = 8
+
+export const OVERLAY_COLLISION_PADDING = 8

package/src/tokens/layoutSpace/layoutSpace.css

@@ -0,0 +1,36 @@
+/* Layout Space Tokens — md 為預設，lg 透過 attribute 覆寫 */
+
+:root {
+  --layout-space-loose:  16px;
+  --layout-space-tight:  12px;
+  --layout-space-bottom: 48px; /* intentionally fixed — same in md and lg density (see spec) */
+
+  /* Item-level label ↔ description gap — typography mode aware(2026-04-23)
+     理論基礎:gap 由 **typography mode**(label + description 的 font-size / line-height 組合)決定。
+     同 mode 全 DS 永遠同 gap;不同 mode 可不同值。架構支援 per-mode 獨立調整。
+     目前 4 mode 都 2px(視覺統一 tight 間距)— 未來可獨立調整不牽動其他 mode。
+     Primary consumer:<ItemContent mode={...}> primitive,自動挑對應 token。
+     備註:本 DS「配對」(uiSize.spec.md)專指 Tag↔Field 等**元件 size 配對**,
+     跟本 token 表達的「label + desc typography 組合」不同概念,勿混淆。 */
+  --item-gap-label-desc-reading:     2px;  /* reading:    body(14/1.5)    + body(14/1.5) — SelectionItem sm-md / Switch sm-md / DescriptionList / item-anatomy reading row */
+  --item-gap-label-desc-reading-lg:  2px;  /* reading-lg: body-lg(16/1.5) + body(14/1.5) — Dialog / Sheet / Empty / FileUpload / Coachmark / NameCard / SelectionItem lg / Switch lg */
+  --item-gap-label-desc-scanning:    2px;  /* scanning:   body(14/1.3)    + caption(12/1.3) — FileItem compact+rich / MenuItem sm-md / Steps sm-md */
+  --item-gap-label-desc-scanning-lg: 2px;  /* scanning-lg:body-lg(16/1.3) + body(14/1.3) — MenuItem lg / Steps lg */
+}
+
+[data-layout-space="lg"],
+[data-density="lg"] {
+  --layout-space-loose:  24px;
+  --layout-space-tight:  16px;
+  --layout-space-bottom: 48px; /* intentionally fixed — same in md and lg density (see spec) */
+}
+
+/* 2026-04-22:md reset selector — subtree 宣告 `data-density="md"` / `data-layout-space="md"`
+   時必須能 reset 回 md default(對齊 uiSize md reset rationale,Meta-Pattern M3 Portal
+   subtree context drift) */
+[data-layout-space="md"],
+[data-density="md"] {
+  --layout-space-loose:  16px;
+  --layout-space-tight:  12px;
+  --layout-space-bottom: 48px;
+}

package/src/tokens/motion/motion.css

@@ -0,0 +1,30 @@
+/**
+ * Motion tokens — hover delay tier system.
+ *
+ * 2026-05-18 ship per user 拍板 #3A(3-tier hover delay token + 確保命名世界級)。
+ *
+ * Naming convention:
+ *   --hover-delay-{tier}
+ *
+ * Tier semantics 對齊 world-class consensus(see motion.spec.md「世界級對照」段):
+ *   - plain  → passive hint  | Tooltip 文字提示    | 500ms  | Material 3 / Apple HIG / shadcn-Radix default 主流共識
+ *   - rich   → rich preview  | HoverCard / NameCard | 700ms  | 含 fetch / multi-section,避免列表掃視誤觸發
+ *   - close  → universal exit| 全部關閉延遲          | 200ms  | UX research consensus accidental-hover 容錯
+ *
+ * 2026-05-20 user 拍板「太快很容易干擾人」+ B 選項(plain 500 / rich 700):
+ *   - plain 200 → 500ms:對齊 Material 3 plain tooltip 500ms + Apple HIG ~500ms + shadcn-Radix default 500ms
+ *     主流共識(MUI 100ms / Ant 100ms 是 fast-tier 例外);200ms 偏快會打擾滑過列表的 user
+ *   - rich 300 → 700ms:HoverCard 含 fetch + multi-section(NameCard avatar / actions),
+ *     需 user「真停留」才觸發;300ms 列表掃視易觸發 N 次 fetch
+ *   - close 200ms 維持:close delay ≤ open delay UX 共識(user 誤滑出可回來)
+ *
+ * Rationale 命名:不用 component name(`tooltip` 太特定)、不用純數字(`delay-200` 用值不用語意)、
+ * 不用孤立縮寫(`hd-fast` 跨人不可讀)。`plain` / `rich` / `close` 對齊 Material rich-tooltip 公開文件 +
+ * DS 既有 `compact / rich` mode 詞彙一致(per `# 命名與語言一致性` 命名 3 test)。
+ */
+
+:root {
+  --hover-delay-plain: 500ms;
+  --hover-delay-rich: 700ms;
+  --hover-delay-close: 200ms;
+}

package/src/tokens/motion/motion.ts

@@ -0,0 +1,17 @@
+/**
+ * Motion tokens — JS mirror of `motion.css` for Radix/JS API consumers.
+ *
+ * Radix primitive props(`delayDuration` / `openDelay` / `closeDelay`)期望 number ms,
+ * 不認 CSS var。本 file 是 motion.css 對應 number value 鏡像;改值必同步兩處(或加 lint)。
+ *
+ * SSOT: `motion.css` + `motion.spec.md`。
+ */
+
+/** 純文字提示(Tooltip)— passive hint。2026-05-20 200→500ms 對齊 Material 3 / Apple HIG / shadcn-Radix 主流 */
+export const HOVER_DELAY_PLAIN_MS = 500
+
+/** 內容預覽(HoverCard / NameCard)— rich preview。2026-05-20 300→700ms 避免列表掃視誤觸發 fetch */
+export const HOVER_DELAY_RICH_MS = 700
+
+/** 通用關閉延遲(所有 hover overlay)— accidental-hover 容錯 */
+export const HOVER_DELAY_CLOSE_MS = 200