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

package/src/tokens/categorical-color.ts

@@ -0,0 +1,164 @@
+/**
+ * categorical-color.ts — Categorical 色相 SSOT(2026-06-04 codify)
+ *
+ * Tag / Avatar / Calendar 等「以色相做分類標籤」的元件,色彩 variant **一律消費此 SSOT**。
+ * 目的:**variant 名 == primitive 色相名,1:1,零 offset** —— 根治「red variant 接到 deep-orange」
+ * 這類 categorical-vs-semantic 混淆(2026-06-04 user 抓:red = 品牌紅 hue-25〔--brand #DF3232 同族〕
+ * ≠ deep-orange hue-38 ≠ semantic --error〔= deep-orange〕。三者完全無關)。
+ *
+ * 世界級對照:
+ * - Ant Design Tag preset colors —— 用原始色相名(red/orange/green/blue…)做 categorical labeling
+ *   (https://ant.design/components/tag/)。本 DS Tag/Avatar 採此模型。
+ * - Atlassian Color 原則 —— **categorical(裝飾)色 vs semantic(狀態)色必須分離**
+ *   (https://atlassian.design/foundations/color):categorical `red` 用 `--color-red-*`,跟 semantic
+ *   `--error`(= deep-orange)無關;把 error 色拿來當 categorical 標籤 = 反 pattern。
+ *
+ * ⚠️ Tailwind v4 掃描限制:class 字串**必須以字面形式出現在被掃描的 source**(本檔在 src/,會被掃),
+ * 不可用 runtime function 拼字串(否則 `bg-[var(--color-orange-1)]` 不被生成 → silent 失效)。
+ * 故本 SSOT 以**字面 const map** 提供;consumer `import` 後索引(cva 列 key 取值,保 VariantProps 型別)。
+ *
+ * 互動 state(solid dismiss hover/active)用 semantic `--{hue}-hover` / `--{hue}-active`
+ * (dark-mode 方向 pre-computed,**不可**用 primitive step-5,否則 dark mode 反向)。12 色相皆已定義。
+ *
+ * **加色相**:加進 `CATEGORICAL_HUES` + 下列 5 個 map 各補一行字面值(key X 用 `--color-X-*`,1:1)。
+ * **機械防線**:`scripts/categorical-color-invariants.mjs` I1(current required CI / deterministic audit chain)強制 map 的 key X 的值含 `--color-X-`(名實一致,禁 offset;原引 hook 名不存在,2026-07-04 修)。
+ */
+
+/** 12 個 categorical 色相。⚠️ 順序 = **categorical 指派序**(圖表系列鄰色最大區辨:blue→green→deep-orange→yellow→red…),**非** primitives.css 檔內宣告序 — 兩者本就不同,map 以名為 key 故功能無涉;**禁**為「對齊」重排(重排 = 圖表系列換色 = 視覺 breaking)。 */
+export const CATEGORICAL_HUES = [
+  'blue',
+  'green',
+  'deep-orange',
+  'yellow',
+  'red',
+  'orange',
+  'amber',
+  'lime',
+  'turquoise',
+  'indigo',
+  'purple',
+  'magenta',
+] as const
+
+export type CategoricalHue = (typeof CATEGORICAL_HUES)[number]
+
+/** neutral 不是色相(無 hue),用 secondary/foreground + neutral-9 solid,各 consumer 自處理(不在下列 map)。 */
+export type CategoricalColor = CategoricalHue | 'neutral'
+
+/** subtle 模式 class:step-1 底 + step-7 字。key X 一律對 `--color-X-*`(1:1)。 */
+export const CAT_SUBTLE: Record<CategoricalHue, string> = {
+  blue: 'bg-[var(--color-blue-1)] text-[var(--color-blue-7)]',
+  green: 'bg-[var(--color-green-1)] text-[var(--color-green-7)]',
+  'deep-orange': 'bg-[var(--color-deep-orange-1)] text-[var(--color-deep-orange-7)]',
+  yellow: 'bg-[var(--color-yellow-1)] text-[var(--color-yellow-7)]',
+  red: 'bg-[var(--color-red-1)] text-[var(--color-red-7)]',
+  orange: 'bg-[var(--color-orange-1)] text-[var(--color-orange-7)]',
+  amber: 'bg-[var(--color-amber-1)] text-[var(--color-amber-7)]',
+  lime: 'bg-[var(--color-lime-1)] text-[var(--color-lime-7)]',
+  turquoise: 'bg-[var(--color-turquoise-1)] text-[var(--color-turquoise-7)]',
+  indigo: 'bg-[var(--color-indigo-1)] text-[var(--color-indigo-7)]',
+  purple: 'bg-[var(--color-purple-1)] text-[var(--color-purple-7)]',
+  magenta: 'bg-[var(--color-magenta-1)] text-[var(--color-magenta-7)]',
+}
+
+/**
+ * solid 模式 class:step-6 底 + on-emphasis 配對文字。
+ * 文字色依「step-6 底亮度」分桶(WCAG ≥3:1 大粗字門檻,2026-06-04 user「以最低為原則」):
+ *   - 夠深的色底 → `text-on-emphasis`(白):blue / deep-orange / red / indigo / purple / magenta
+ *   - 太亮的色底 → `text-on-emphasis-dark`(深):yellow / amber / orange / lime / turquoise(白字連 3:1 都不過;turquoise 2026-07-16 dark 色相修正後 L=0.68 白字 2.77 → 切深字,兩 mode 5.65/6.47 全過)
+ *   - ★ green 例外:白字 2.47 連 3:1 都不過,但 user 拍板維持白字(綠底白字慣見觀感)= documented exception。
+ * 對比為 oklch→相對亮度實測(scripts/categorical-color-invariants.mjs 機械驗,green 列 exempt)。
+ */
+export const CAT_SOLID: Record<CategoricalHue, string> = {
+  blue: 'bg-[var(--color-blue-6)] text-on-emphasis',
+  green: 'bg-[var(--color-green-6)] text-on-emphasis', // ★白字 documented exception(實測 2.47 < 3:1)
+  'deep-orange': 'bg-[var(--color-deep-orange-6)] text-on-emphasis',
+  yellow: 'bg-[var(--color-yellow-6)] text-on-emphasis-dark',
+  red: 'bg-[var(--color-red-6)] text-on-emphasis',
+  orange: 'bg-[var(--color-orange-6)] text-on-emphasis-dark',
+  amber: 'bg-[var(--color-amber-6)] text-on-emphasis-dark',
+  lime: 'bg-[var(--color-lime-6)] text-on-emphasis-dark',
+  turquoise: 'bg-[var(--color-turquoise-6)] text-on-emphasis-dark',
+  indigo: 'bg-[var(--color-indigo-6)] text-on-emphasis',
+  purple: 'bg-[var(--color-purple-6)] text-on-emphasis',
+  magenta: 'bg-[var(--color-magenta-6)] text-on-emphasis',
+}
+
+/** solid 互動(dismiss hover/active)— semantic dark-mode-aware token。 */
+export const CAT_INTERACT: Record<CategoricalHue, { hover: string; active: string }> = {
+  blue: { hover: 'var(--blue-hover)', active: 'var(--blue-active)' },
+  green: { hover: 'var(--green-hover)', active: 'var(--green-active)' },
+  'deep-orange': { hover: 'var(--deep-orange-hover)', active: 'var(--deep-orange-active)' },
+  yellow: { hover: 'var(--yellow-hover)', active: 'var(--yellow-active)' },
+  red: { hover: 'var(--red-hover)', active: 'var(--red-active)' },
+  orange: { hover: 'var(--orange-hover)', active: 'var(--orange-active)' },
+  amber: { hover: 'var(--amber-hover)', active: 'var(--amber-active)' },
+  lime: { hover: 'var(--lime-hover)', active: 'var(--lime-active)' },
+  turquoise: { hover: 'var(--turquoise-hover)', active: 'var(--turquoise-active)' },
+  indigo: { hover: 'var(--indigo-hover)', active: 'var(--indigo-active)' },
+  purple: { hover: 'var(--purple-hover)', active: 'var(--purple-active)' },
+  magenta: { hover: 'var(--magenta-hover)', active: 'var(--magenta-active)' },
+}
+
+/** Avatar style 物件用:subtle / solid 的 raw token { bg, text }(非 class)。 */
+export const CAT_SUBTLE_TOKENS: Record<CategoricalHue, { bg: string; text: string }> = {
+  blue: { bg: 'var(--color-blue-1)', text: 'var(--color-blue-7)' },
+  green: { bg: 'var(--color-green-1)', text: 'var(--color-green-7)' },
+  'deep-orange': { bg: 'var(--color-deep-orange-1)', text: 'var(--color-deep-orange-7)' },
+  yellow: { bg: 'var(--color-yellow-1)', text: 'var(--color-yellow-7)' },
+  red: { bg: 'var(--color-red-1)', text: 'var(--color-red-7)' },
+  orange: { bg: 'var(--color-orange-1)', text: 'var(--color-orange-7)' },
+  amber: { bg: 'var(--color-amber-1)', text: 'var(--color-amber-7)' },
+  lime: { bg: 'var(--color-lime-1)', text: 'var(--color-lime-7)' },
+  turquoise: { bg: 'var(--color-turquoise-1)', text: 'var(--color-turquoise-7)' },
+  indigo: { bg: 'var(--color-indigo-1)', text: 'var(--color-indigo-7)' },
+  purple: { bg: 'var(--color-purple-1)', text: 'var(--color-purple-7)' },
+  magenta: { bg: 'var(--color-magenta-1)', text: 'var(--color-magenta-7)' },
+}
+// 同 CAT_SOLID 的文字分桶(白 / 深),raw token 版供 Avatar style 物件用。green = ★白字 exception。
+export const CAT_SOLID_TOKENS: Record<CategoricalHue, { bg: string; text: string }> = {
+  blue: { bg: 'var(--color-blue-6)', text: 'var(--on-emphasis)' },
+  green: { bg: 'var(--color-green-6)', text: 'var(--on-emphasis)' }, // ★白字 documented exception
+  'deep-orange': { bg: 'var(--color-deep-orange-6)', text: 'var(--on-emphasis)' },
+  yellow: { bg: 'var(--color-yellow-6)', text: 'var(--on-emphasis-dark)' },
+  red: { bg: 'var(--color-red-6)', text: 'var(--on-emphasis)' },
+  orange: { bg: 'var(--color-orange-6)', text: 'var(--on-emphasis-dark)' },
+  amber: { bg: 'var(--color-amber-6)', text: 'var(--on-emphasis-dark)' },
+  lime: { bg: 'var(--color-lime-6)', text: 'var(--on-emphasis-dark)' },
+  turquoise: { bg: 'var(--color-turquoise-6)', text: 'var(--on-emphasis-dark)' },
+  indigo: { bg: 'var(--color-indigo-6)', text: 'var(--on-emphasis)' },
+  purple: { bg: 'var(--color-purple-6)', text: 'var(--on-emphasis)' },
+  magenta: { bg: 'var(--color-magenta-6)', text: 'var(--on-emphasis)' },
+}
+
+/** Calendar event tile:subtle 底 + hover step-2(1:1)。 */
+export const CAT_EVENT: Record<CategoricalHue, string> = {
+  blue: 'bg-[var(--color-blue-1)] text-[var(--color-blue-7)] hover:bg-[var(--color-blue-2)]',
+  green: 'bg-[var(--color-green-1)] text-[var(--color-green-7)] hover:bg-[var(--color-green-2)]',
+  'deep-orange': 'bg-[var(--color-deep-orange-1)] text-[var(--color-deep-orange-7)] hover:bg-[var(--color-deep-orange-2)]',
+  yellow: 'bg-[var(--color-yellow-1)] text-[var(--color-yellow-7)] hover:bg-[var(--color-yellow-2)]',
+  red: 'bg-[var(--color-red-1)] text-[var(--color-red-7)] hover:bg-[var(--color-red-2)]',
+  orange: 'bg-[var(--color-orange-1)] text-[var(--color-orange-7)] hover:bg-[var(--color-orange-2)]',
+  amber: 'bg-[var(--color-amber-1)] text-[var(--color-amber-7)] hover:bg-[var(--color-amber-2)]',
+  lime: 'bg-[var(--color-lime-1)] text-[var(--color-lime-7)] hover:bg-[var(--color-lime-2)]',
+  turquoise: 'bg-[var(--color-turquoise-1)] text-[var(--color-turquoise-7)] hover:bg-[var(--color-turquoise-2)]',
+  indigo: 'bg-[var(--color-indigo-1)] text-[var(--color-indigo-7)] hover:bg-[var(--color-indigo-2)]',
+  purple: 'bg-[var(--color-purple-1)] text-[var(--color-purple-7)] hover:bg-[var(--color-purple-2)]',
+  magenta: 'bg-[var(--color-magenta-1)] text-[var(--color-magenta-7)] hover:bg-[var(--color-magenta-2)]',
+}
+
+/** Calendar all-day accent:左側 step-6 實心條。 */
+export const CAT_ACCENT: Record<CategoricalHue, string> = {
+  blue: 'border-l-[3px] border-[var(--color-blue-6)]',
+  green: 'border-l-[3px] border-[var(--color-green-6)]',
+  'deep-orange': 'border-l-[3px] border-[var(--color-deep-orange-6)]',
+  yellow: 'border-l-[3px] border-[var(--color-yellow-6)]',
+  red: 'border-l-[3px] border-[var(--color-red-6)]',
+  orange: 'border-l-[3px] border-[var(--color-orange-6)]',
+  amber: 'border-l-[3px] border-[var(--color-amber-6)]',
+  lime: 'border-l-[3px] border-[var(--color-lime-6)]',
+  turquoise: 'border-l-[3px] border-[var(--color-turquoise-6)]',
+  indigo: 'border-l-[3px] border-[var(--color-indigo-6)]',
+  purple: 'border-l-[3px] border-[var(--color-purple-6)]',
+  magenta: 'border-l-[3px] border-[var(--color-magenta-6)]',
+}

package/src/tokens/color/color.spec.md

@@ -1,8 +1,8 @@
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; 已驗證 claim 於原句 inline 附 @benchmark-cited URL(本檔為 token spec,無 YAML frontmatter benchmark list)。 -->
 
 # Color 設計原則
 
-> **Foundational SSOT rationale**(2026-04-24 approved,cap 1000 — 2026-05-22 raised 800→1000 per /knowledge-prune deep audit + CLAUDE.md「foundational SSOT 例外 ≤ 800-1200」range):
+> **Foundational SSOT rationale**(2026-04-24 approved,cap 1000 — 2026-05-22 raised 800→1000 per /knowledge-prune deep audit + `AGENTS.md`「行數預算」的 foundational SSOT 例外 ≤ 800-1200 range):
 > Token 系統 SSOT,涵蓋 primitive / semantic 兩層色彩架構、disabled 兩策略、Hover/Active 公式推導、新增語意色相 4-step 流程、neutral interaction 雙 family、nested theme。跨 30+ 元件消費,改一 token 影響全 DS。218 行語義色定義是純 token structural canonical 無法 reference out;不可拆不失原則。
 
 ## 架構流派定位
@@ -67,11 +67,13 @@ Semantic token 直接指向 primitive（無中間層）。
 | Badge 層級（high/medium） | **Semantic**（`--info`、`--info-subtle`、`--info-text`） | 代表「資訊狀態」，不是操作 |
 | 錯誤訊息、驗證錯誤 | **Semantic**（`--error`） | 代表「系統出了問題」 |
 
-**注意**：「red」語義色（`--error`）實際對應的 primitive 色相是 `deep-orange`。Tag / Avatar 的 `red` variant 使用 `--color-deep-orange-*` primitive。
+**注意（categorical `red` vs semantic `--error` vs primitive `deep-orange` 三者獨立）**：
+- `--error` = `--color-deep-orange-6`（primitive `deep-orange`，hue 38）—— semantic 狀態色,用於錯誤訊息。
+- Tag / Avatar / Calendar 的 categorical `red` variant = `--color-red-*`（品牌紅家族 hue 25,與 `--brand` `#DF3232` 同族）。
+- **三者無映射關係**：categorical `red`（hue 25）≠ `deep-orange`（primitive hue 38）≠ `--error`（semantic = deep-orange）。categorical 色相 1:1 對 `--color-{hue}-*`,零 offset（SSOT `tokens/categorical-color.ts`)。2026-06-04 修正原「red variant 接 deep-orange」offset。
 
 Tailwind utility 透過 `@theme inline` 橋接 semantic token，元件寫 `bg-primary` 或 `bg-error` 即可。Tag / Avatar 使用 CSS 變數任意值（`bg-[var(--color-blue-6)]`）。
 
-
 ## Surface 分層（非常重要）
 
 | Token / Utility     | 用途 | 說明 |
@@ -82,7 +84,6 @@ Tailwind utility 透過 `@theme inline` 橋接 semantic token，元件寫 `bg-pr
 
 `bg-surface-raised` 必須不透明，避免底層內容透出。
 
-
 ## 文字 / Icon 層級
 
 | Utility            | 用途 |
@@ -95,11 +96,8 @@ Tailwind utility 透過 `@theme inline` 橋接 semantic token，元件寫 `bg-pr
 文字色一律使用 neutral alpha token，疊加在任何背景都能維持對比。
 弱化 icon hover 後變 `text-fg-secondary`。
 
-
-
 ## Disabled 狀態
 
-
 disabled 元件內的所有子元素必須呈現 disabled 狀態:
 
 | 元素類型 | Disabled 處理 |
@@ -115,12 +113,12 @@ disabled 元件內的所有子元素必須呈現 disabled 狀態:
 
 ### 兩種 disabled 策略:何時用哪個
 
-系統有**兩種** disabled 視覺處理方式,判準是「**顏色是否是 semantic state 的唯一視覺載體**」:
+系統有**兩種** disabled 視覺處理方式,判準是「**顏色是否是 semantic state 的主視覺載體**」:
 
 | 策略 | 何時用 | 消費者 | 做法 |
 |---|---|---|---|
-| **灰階 token swap** | State 由形狀 / 位置 / icon / 文字 等**非顏色載體**承載,顏色只是美學 | Button、Checkbox、Input、Slider、Tag | 每個元素換到 disabled 對應的灰階 token(`bg-disabled` / `text-fg-disabled` / `border-fg-disabled` 等) |
-| **`opacity-disabled`** | State **完全只靠顏色區分**(形狀在 on/off 之間沒有差異),灰階化會丟失 state 辨識 | **Switch** | Root 層套 `opacity-disabled`,保留原有顏色身分,透過透明度均勻降級 |
+| **灰階 token swap** | State 由形狀 / 位置 / icon / 文字 等**非顏色載體**承載,顏色只是美學 | Button、Checkbox、Input、Slider、Tag | 每個元素換到 disabled 對應的灰階 token(`bg-disabled` / `text-fg-disabled` / `bg-border` 等) |
+| **`opacity-disabled`** | State **主要靠顏色區分**(殘餘線索如 thumb 位移 / 小 icon 在灰階低對比下太弱),灰階化會使 state 辨識大幅下降 | **Switch** | Root 層套 `opacity-disabled`,保留原有顏色身分,透過透明度均勻降級 |
 
 **具體判準(寫新元件時問自己)**:
 1. 在 disabled 狀態下,使用者需要辨識的 state 資訊是什麼?
@@ -135,14 +133,16 @@ disabled 元件內的所有子元素必須呈現 disabled 狀態:
 
 ### Disabled 視覺階層公式(多元素元件參考)
 
-多元素互動元件(Slider、Progress、複合 Input 等)在 disabled 狀態常需要 3–4 階灰階深度來分層:
+多元素互動元件(Slider、Progress、複合 Input 等)在 disabled 狀態常需要 2–3 階灰階深度來分層:
 
 ```
-底層背景 (n-2)  <  中層填充 (n-5)  <  輪廓邊框 (n-6)  <  文字 (n-7+)
-bg-muted          bg-border         border-fg-disabled     text-fg-disabled
+底層背景 (n-2)  <  中層填充 / 輪廓 (n-5)        <  文字 (n-6)
+bg-muted          bg-border / border-border       text-fg-disabled
 ```
 
-每階至少差 1 個 primitive step,使用者掃視時才能分清四個層。Slider 的 disabled 就是這個公式:track(底)< range(填充)< thumb border(輪廓)< label(文字)。
+每階至少差 1 個 primitive step,使用者掃視時才能分清層次。Slider 的 disabled 就是這個公式:track(底,n-2)< range 填充 = thumb 邊框(n-5,**同色**——「Range 色 = Thumb border 色」invariant,thumb 邊框是 range 的視覺延續,不論 state 永遠同色,詳 slider.tsx 註解)< label 文字(n-6)。
+
+> 2026-06-12 修:本段原寫 4 階公式、輪廓層用 `border-fg-disabled`(n-6)、文字層標 n-7+——三者皆與 code 不符(`border-fg-disabled` 全 code 零使用且違反下方規則 3「border-* 一律從 border family 選」;`--fg-disabled` 實為 n-6;slider.tsx 的 range/thumb 邊框同色是刻意設計,曾踩 thumb 融入 track 的同色融色 bug)。對齊 code 真實。
 
 ### ⚠️ fg token 不可當 bg 用(跨 family 借用是 smell)
 
@@ -159,10 +159,7 @@ Semantic token 按**載體類型**分成四個 family,**family 之間的 token
 
 > **Case**:Slider disabled 的 Range(填充段)一開始寫成 `bg-fg-disabled`。理由:`--fg-disabled`(neutral-6)剛好是我想要的「比 track 深但比文字淺」的灰度。但 `--fg-disabled` 語意是「**disabled 文字的前景色**」,拿來當 bg 等於借 fg token 當 bg 用。
 >
-> **問題**:
-> 1. **語意矛盾**:consumer 讀 code 時 `bg-fg-disabled` 會困惑「這到底是 bg 還是 fg」
-> 2. **耦合未來變動**:未來若微調 `--fg-disabled`(例如從 n-6 改成 n-7 讓 disabled 文字更可讀),Slider range 會被迫一起變,但它不是文字、不需要文字可讀性的約束
-> 3. **缺乏單一來源的 bg token**:應該存在一個「disabled 狀態的中層填充色」的 bg token(如果沒有,要新增一個 semantic alias,而不是借 fg)
+> **問題**:(1)**語意矛盾**——consumer 讀 `bg-fg-disabled` 會困惑這是 bg 還是 fg;(2)**耦合未來變動**——微調 `--fg-disabled`(如 n-6→n-7 提高 disabled 文字可讀)會被迫連動 range,但 range 非文字、無文字可讀性約束;(3)**缺單一來源 bg token**——應存在「disabled 中層填充」bg token(沒有就新增 semantic alias,不是借 fg)
 >
 > **修正**:改用 `bg-border`(neutral-5)。`--border` 屬於 Border family,語意是「視覺分隔線 / 容器邊框 / 階層分隔的視覺元件」——跟 range 的「填充視覺指示器」角色接近,且 family 對得上(非文字的視覺填充類)。
 
@@ -174,9 +171,9 @@ Semantic token 按**載體類型**分成四個 family,**family 之間的 token
 
 **唯一合法例外**:`--foreground` 偶爾用在 `bg-foreground`(暗色填充)表達「inverse surface」(例如 Tooltip 深底)——但這是 inverse namespace 的設計意圖,有專門的 `--inverse-*` token family 處理,不是隨便借。一般元件不該 `bg-foreground`。
 
-
 ## Icon 色彩原則
 
+Icon 色彩 canonical 的 SSOT 住 `patterns/element-anatomy/item-anatomy.spec.md`「Icon 色彩原則」——核心規則:icon 代表內容/類別 → 與 label 同色;icon 純指示方向 → `fg-muted`;disabled 統一 `fg-disabled`。本檔不重述(Rule-of-3 pointer)。
 
 ## 語義色
 
@@ -195,6 +192,8 @@ Semantic token 按**載體類型**分成四個 family,**family 之間的 token
 <a className="text-primary hover:text-primary-hover">查看詳情</a>
 ```
 
+**連結 hover = 換色(`text-primary-hover`),不用底線** —— `text-primary hover:underline` 偏離 canonical。真元件 Breadcrumb / Button / RadioGroup 已遵循。**例外:`LinkInput` 是「外部連結值」顯示,刻意保留 hover 底線作為「可點開連結」affordance(見 `link-input.spec.md`),非 violator**。story 導覽連結由 `check_story_invariants.sh` R10 機械防 drift(P1 warn,豁免 `// @link-style-allow:`)。
+
 ### Status
 
 狀態色表達系統回饋，代表「系統在告訴你什麼」，不用於互動操作。
@@ -221,14 +220,16 @@ Semantic token 按**載體類型**分成四個 family,**family 之間的 token
 <Progress className="bg-primary" value={60} />
 ```
 
+**機械強制**:此規則對 status 元件(ProgressBar / CircularProgress / Steps / Calendar today)由 `scripts/status-color-invariant.mjs` 鎖住(release-preflight chain),回潮 `--primary` 即 fail。2026-06-05 user 拍板把這 4 個元件的 progress/step/in-progress 填色從 `--primary` 全遷 `--info`(同色 blue-6 零視覺差,語義正確 + brand-swap 安全)。
+
 每個語義色的 bridge 同時產出 `bg-xxx`、`text-xxx`、`border-xxx` 三組 utility，視場景選用。
 
 - warning 的文字色取決於底色：
 
   | 底色 | 文字色 | 原因 |
   |------|--------|------|
-  | `bg-warning`（yellow-6，滿版） | `text-warning-foreground`（`black-a85`，深色） | 黃色亮度高，白字對比不足，必須用深色 |
-  | `bg-warning-subtle`（淡黃） | `text-[yellow-7]`（step-7） | subtle 底色夠淺，深一階的黃色文字可辨識（見「文字色 Step 原則」） |
+  | `bg-warning`（yellow-6，滿版） | `text-on-emphasis-dark`（`black-a85`，深色） | 黃色亮度高，白字對比不足，必須用深色（通用亮底深字 token，非 warning 專屬；定義見下「`--on-emphasis` / `--on-emphasis-dark` 配對」段） |
+  | `bg-warning-subtle`（淡黃） | `text-warning-text`（semantic，= `--color-yellow-7` step-7） | subtle 底色夠淺，深一階的黃色文字可辨識（見「文字色 Step 原則」）；Notice / Alert code 消費的即是此 semantic utility，不硬寫 primitive 色名 |
 
 ### Indicator — Notification
 
@@ -242,13 +243,39 @@ Semantic token 按**載體類型**分成四個 family,**family 之間的 token
 <span className="bg-notification text-white">3</span>   // badge 計數
 ```
 
+### Highlight — 文字反白與搜尋配對
+
+| Token | Utility | 值 | 用途 |
+|-------|---------|------|------|
+| `--text-selection` | `bg-text-selection` | blue-5 @ 30% 半透明 | 文字反白(`::selection`)底色;全域樣式住 `styles/base.css`,只動底色不動字色 |
+| `--search-match` | `bg-search-match` | amber-3 | 頁內搜尋(Ctrl+F 類)**所有配對**的行內底色 |
+| `--search-match-current` | `bg-search-match-current` | amber-5(dark:amber-4) | 配對中**目前這一筆**(find 游標所在) |
+
+設計依據(2026-08-28 拍板):
+
+- **反白必半透明**:對齊 VS Code theme-color 對 selection 類 token 的鐵律「The color must not be opaque so as not to hide underlying decorations」(https://code.visualstudio.com/api/references/theme-color);反白後文字須維持對比 ≥ 4.5:1(https://developer.mozilla.org/en-US/docs/Web/CSS/::selection)
+- **搜尋雙檔制**是編輯器/瀏覽器普世慣例:VS Code `editor.findMatchBackground`(「Color of the current search match」)與 `editor.findMatchHighlightBackground`(「Color of the other search matches」)兩 token 分立;琥珀/黃族底色 = 瀏覽器原生 find 慣例
+- **對階**:amber-3 / -5 對齊 Radix scale 語意 step 3 =「UI element background」/ step 5 =「Active / Selected UI element background」(https://www.radix-ui.com/colors/docs/palette-composition/understanding-the-scale);行內 highlight 鐵約束 = 文字保持原色可讀 → 底色停留亮階(≤ step 5)
+- **為何字尾是 `-current` 不是 `-active`**:`-active` 在本系統 = 按壓語意且映射第 7 階(`--amber-active` = amber-7,見「互動狀態推導」),同字不同映射會破壞一致性;`current` 取自 VS Code 官方描述原詞
+- **Dark**:`--text-selection` / `--search-match` 由 primitive 階梯公式自動反轉(1–5 變深)免 override;`--search-match-current` **需降一階覆寫 amber-4**——數學驗收(oklch→sRGB→WCAG)dark amber-5 配白字對比 3.03 過不了 4.5,amber-4 = 5.89 ✓ 且與 amber-3 區辨 1.86 優於 light 的 1.31。全組量測:light 反白 11.41 / amber-3 12.21 / amber-5 9.82;dark 反白 13.04 / amber-3 10.97 / amber-4 5.89(皆 ≥ 4.5)
+
+```tsx
+<mark className="bg-search-match text-inherit">報表</mark>          // 一般配對
+<mark className="bg-search-match-current text-inherit">報表</mark>  // 目前這一筆
+```
+
+禁止:
+
+- ❌ `<mark>` 用 UA 預設黃 — 必套 `bg-search-match`(或 `-current`)+ `text-inherit`
+- ❌ 搜尋配對語意裸用 `--color-amber-3/5` — 必經 semantic token(未來調色只動一處)
+- ❌ `--search-match-current` 借給按壓 / 持續選中場景 — 那是 `--neutral-active` / `--neutral-selected` 家族的域;`--text-selection` 亦禁借給資料列選取
+
 ### Identity — 品牌
 
 | Token | 用途 |
 |-------|------|
 | `--brand` | 品牌色，固定色 #DF3232，兩主題相同 |
 
-
 ### Primitive 色票與 Tag / Avatar 的消費
 
 Tag、Avatar 等需要多色區分的場景（專案標籤、團隊分類等）直接消費 primitive token。消費端自行決定色彩用途。
@@ -262,32 +289,32 @@ Tag、Avatar 等需要多色區分的場景（專案標籤、團隊分類等）
 | step-6 | solid 背景（全色填充） | `--color-blue-6` |
 | step-7 | subtle 文字、dismiss active（solid 模式） | `--color-blue-7` |
 
-可用色相：blue、deep-orange、green、yellow、turquoise、purple、magenta、indigo。
+可用 categorical 色相（12 個，SSOT `tokens/categorical-color.ts` `CATEGORICAL_HUES`）：blue、green、deep-orange、yellow、red、orange、amber、lime、turquoise、indigo、purple、magenta。Tag / Avatar / Calendar event 三者共用此組,每個色相 variant 名 1:1 對 `--color-{hue}-*`（零 offset）。
 
-**注意**：Tag / Avatar 的 `red` variant 使用 primitive `deep-orange`（`--color-deep-orange-*`）。
+**注意**：categorical `red` = `--color-red-*`（品牌紅 hue 25),與 primitive `deep-orange`（hue 38）及 semantic `--error`（= deep-orange）**完全無關**（見本檔頂部「消費規則」段注意事項）。
 
 **與 semantic 色的差別**：semantic 色（primary/info/error/success/warning）有固定語義，primitive 色沒有。Tag / Avatar 使用 primitive 是因為「blue」代表顏色本身，不代表「主要操作」或「資訊狀態」。
 
-### `--on-emphasis` token:飽和色底的對比文字
+### `--on-emphasis` / `--on-emphasis-dark` 配對:飽和 / 填色底的對比文字
 
-`--on-emphasis = oklch(1 0 0)`(純白,dark mode 不反轉)。用途:繪製在**飽和色底**(primitive 6 階色 / `--primary` / `--success` / `--error` 等)上的文字 / icon stroke,確保對比度。
+填色底上的文字色**依底色明暗成對**提供(世界級共識:Material `on-primary` family、Radix `--accent-contrast`、Polaris `text-{x}-on-bg-fill` —— 都是「成對 on-color token」,不是單一固定白):
 
-**為什麼獨立於 `--foreground` / `--warning-foreground` 存在**:
-- `--foreground` = neutral-9 文字色(淺色底的主文字),語義是「neutral 表面的前景」。
-- `--warning-foreground` = `--black-a85`,僅用於 warning 子場景(amber 底),非通用。
-- `--on-emphasis` = 純白(不隨 dark 反轉),語義是「任何飽和色底上都能對比出文字」,是通用 emphasis 對比。
+- `--on-emphasis = oklch(1 0 0)`(純白,dark mode 不反轉)—— 用於**夠深的飽和色底**(白字達 WCAG 門檻):primitive 6 階深色 / `--primary` / `--error` 等,及 categorical blue/deep-orange/red/indigo/purple/magenta(turquoise 2026-07-16 移入深字組)。
+- `--on-emphasis-dark = var(--black-a85)`(深字,dark mode 不反轉)—— 用於**太亮的色底**(白字對比不足):categorical **yellow / amber / orange / lime / turquoise**(turquoise 2026-07-16 dark 色相修正後加入)。
 
-**世界級對照**:Material `on-primary` / `on-secondary` family(`md.sys.color.on-primary = #fff`),Polaris `text-onEmphasis`,MUI `palette.primary.contrastText`。我們用 `--on-emphasis` 表達「不綁定到特定 emphasis 色,凡是飽和填色底都用這一個」。
+**合規門檻(2026-06-04 user 拍板「以最低為原則」)= WCAG large/bold 3:1**(solid chip / avatar 的字視為大粗字)。底色 step-6 白字達 3:1 → 用 `--on-emphasis`;不達 → 用 `--on-emphasis-dark`。
 
-**消費者**(目前):
-- Avatar color variants — blue/red/green/... 飽和底的 initials 字色
-- Steps 的 filled indicator — `completed` / `active` 狀態內的 icon 色
+**★ green documented exception**:green-6 白字實測對比 2.47(連 3:1 都不過),但 user 拍板維持白字(沿用世界級慣見的「綠底白字」按鈕觀感)→ 列為知情違反,待日後評估是否調整 green-6 本身。
 
-**不該消費的情境**:
-- ❌ 淺色底(subtle bg)用 `--on-emphasis` — 淺色底請用 `--foreground` / `--fg-secondary` 等 neutral family,對比反而不足
-- ❌ 把 `--on-emphasis` 當 bg 用 — 它是文字 token,作 bg 屬跨 family 借用
+**`--warning-foreground` 2026-06-04 移除(改名 + 不留 alias,user「以乾淨為主」)**:原 `--warning-foreground`(= black-a85)被 categorical yellow/amber 借用 = 誤名(它跟 warning 無關,本質是「亮底深字」通用概念)→ 統一改名 `--on-emphasis-dark`,**不保留 warning 專屬 token**(grep 確認無任何元件消費 `text-warning-foreground`)。warning solid surface 若需黃底深字,一律消費通用 `--on-emphasis-dark`(與其他亮色 hue 同),不再有 warning 專屬前景。
+
+**為什麼獨立於 `--foreground`**:`--foreground` = neutral-9 文字色(淺色 neutral 底的主文字);on-emphasis 配對是「飽和 / 填色底」專用,跟 neutral 表面前景語義不同(數值巧合相同也不可合併:light mode `--foreground` 是深色,混用會 break 飽和底白字)。
 
-**數值規則**:永遠 `oklch(1 0 0)`(純白)。Dark mode 的 `--foreground` 反轉為白,跟 `--on-emphasis` 數值相同但**語義獨立**——不要因數值巧合相同就合併用 `--foreground`,因為 light mode 的 `--foreground` 是深色,混用會 break 飽和底文字。
+**消費者**(目前):Avatar / Tag solid color variants、Steps filled indicator(icon 色)、Calendar today、Tooltip 等。對比由 `scripts/categorical-color-invariants.mjs` I4 機械驗(oklch→相對亮度→contrast,green exempt)。
+
+**不該消費的情境**:
+- ❌ 淺色 subtle 底(step-1)用 on-emphasis 配對 — 請用 `--foreground` / `--color-{hue}-7` family。
+- ❌ 把 on-emphasis 配對當 bg 用 — 它們是文字 token。
 
 ### `--inverse-*` namespace：inverse surface 上的內容色
 
@@ -367,7 +394,7 @@ Badge 使用語義色的 text token（`--info-text`、`--error-text`），不直
 
 **step-7 vs semantic active 的區別**：兩者在 light mode 都指向 step-7，但 dark mode 行為不同。semantic active（如 `--primary-active`）在 dark mode 反轉為 step-5（壓暗模擬按壓感），而 primitive step-7 在 dark mode 仍維持高對比方向。簡言之：active 服務於互動回饋，step-7 服務於閱讀對比，兩者目的不同，dark mode 方向相反。
 
-**例外：step-6 滿版底色（如 yellow solid）上的文字用 `--warning-foreground`（`black-a85`）**——黃色亮度極高，step-7 仍不足以提供對比，必須使用深色文字。此例外只在底色是 step-6 時觸發，step-1 subtle 底色上仍用 step-7。
+**例外：step-6 滿版底色上的「亮色 hue」文字用 `--on-emphasis-dark`（`black-a85`,深色)**——yellow / amber / orange / lime / turquoise 亮度極高,白字（`--on-emphasis`）連 WCAG 3:1 都不過,必須深色文字（見上「`--on-emphasis` 配對」段)。此例外只在底色是 step-6 時觸發,step-1 subtle 底色上仍用 step-7。（green-6 白字亦不過 3:1,但列 documented exception 維持白字。)
 
 ### Subtle 背景（淡色填充）
 
@@ -396,11 +423,8 @@ Light mode 的 step-1 使用不透明色票。Dark mode 的 step-1 在 primitive
 
 `α = 0.12 / l`：亮度越高的色相 alpha 越低，在 dark canvas 上感知亮度自動統一。所有色相用同一套公式，無需在 semantic 層額外覆寫。
 
-
-
 ## 互動狀態推導（Hover / Active）
 
-
 ### 公式
 
 Hover / active **直接引用色盤 step**，不使用獨立公式：
@@ -461,7 +485,7 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 - 跨 mode 一致的方向（dark mode 必須 swap step 號）
 - 但 Tag 的「藍」≠ semantic primary（解耦：改 primary 不應影響 Tag）
 
-直接用 primitive `--color-blue-5/-7` 不行——dark mode 公式互換會方向顛倒。所以擴展 semantic 互動 token 模式到所有 8 個非語意色相。
+直接用 primitive `--color-blue-5/-7` 不行——dark mode 公式互換會方向顛倒。所以擴展 semantic 互動 token 模式到全部 12 個 categorical 色相(SSOT `tokens/categorical-color.ts` `CATEGORICAL_HUES`)。
 
 #### 嚴格限制
 
@@ -504,7 +528,7 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 在 `primitives.css` 定義 base-6 值（只需指定 L、C、H），相對公式自動推導 1-10 階。如已存在則跳過。
 
 ```css
---color-turquoise-6: oklch(0.57 0.10 225);
+--color-turquoise-6: oklch(0.64 0.09 196);  /* light 真值(primitives.css:183);dark 另於 dark 區塊定義 */
 /* 1-5 / 7-10 自動由公式推導 */
 ```
 
@@ -575,9 +599,6 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 - [ ] 命名遵循 `--{name}` / `--{name}-{role}` 模式（不混色相名）
 - [ ] 用 `npx tsc --noEmit` 檢查零錯誤
 
-
-
-
 ## Neutral Interaction
 
 中性互動背景分成**兩個獨立的 family**，對應兩種本質不同的狀態。
@@ -601,9 +622,9 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 
 1. **讀 code 的語意清晰**：`bg-neutral-selected` 比 `bg-neutral-active` 更精準表達「這個 element 處於選中狀態」，不需要讀者在腦裡轉換語意
 2. **未來演化的安全界線**：若未來要把 click 回饋加強（例：`--neutral-active` 改成 neutral-3），selected 狀態視覺不會被意外牽動
-3. **對齊流派原則**：本系統選 Atlassian 流派（Semantic State Token），把互動狀態封裝進 semantic 層——active 和 selected 本來就是兩個語意 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+3. **對齊流派原則**：本系統選 Atlassian 流派（Semantic State Token），把互動狀態封裝進 semantic 層——active 和 selected 本來就是兩個語意 <!-- @benchmark-unverified: canonical DS source URL 未驗證(M22(d) 顯式撤回 marker) -->
 
-此原則對齊 Carbon Design System 的 `$layer-*` 族命名（`$layer-active` vs `$layer-selected`），是世界級系統處理「同值不同語意」的標準做法。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+此原則對齊 Carbon Design System 的 `$layer-*` 族命名（`$layer-active` vs `$layer-selected`），是世界級系統處理「同值不同語意」的標準做法。 <!-- @benchmark-unverified: canonical DS source URL 未驗證(M22(d) 顯式撤回 marker) -->
 
 ### Default state family
 
@@ -620,13 +641,14 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 
 ### Selected state family
 
-用於持續 toggle on / 選中 element 的互動回饋。**三件成套，對應 rest / hover / :active 三種互動態**：
+用於持續 toggle on / 選中 element 的互動回饋。**四件成套（2026-08-11 user 拍板補 `-focus`；疊加行為 owner = `item-anatomy.spec.md`「選中 × 互動疊加」格）**：
 
 | Utility | Token | 用途 |
 |---|---|---|
-| `bg-neutral-selected` | neutral-2 | 持續 selected rest |
-| `bg-neutral-selected-hover` | neutral-1 | selected 上 hover（反向變淺，暗示「可取消」） |
-| `bg-neutral-selected-active` | neutral-3 | selected 上 `:active` 深一階 click 回饋 |
+| `bg-neutral-selected` | neutral-2 | 持續 selected rest；**選中列被滑鼠 hover 時亦釘住此值不變** |
+| `bg-neutral-selected-hover` | neutral-1 | **可取消切換鈕專屬**：pressed 上 hover 反向變淺，暗示「再點會釋放」（Fluent ToggleButton 同構；Carbon/Atlassian 同名 token 是變深，本 DS 反向為切換鈕語意的有意設計——**列元件禁用本 token**） |
+| `bg-neutral-selected-focus` | neutral-3 | **鍵盤焦點／反白停在選中列** → 深一階（游標可見，WCAG 2.4.7；滑鼠 hover 不觸發） |
+| `bg-neutral-selected-active` | neutral-3 | selected 上 `:active` 深一階 click 回饋（**按壓專屬，禁借給 hover／反白**——2026-07-05 D4 曾借用，2026-08-11 糾正） |
 
 ```tsx
 // toggle button pressed 狀態
@@ -647,7 +669,6 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 - ❌ 不得用 `bg-neutral-selected` 作為 `:active` 瞬間回饋——selected 是 persistent，不是 transient
 - ❌ 不得因為目前同值就合併為一個 token——語意獨立就該獨立存在
 
-
 ## Static Subtle Background — `bg-muted` vs `bg-secondary` 使用原則(SSOT)
 
 > **2026-05-20 v3 consolidation**(per user directive「全盤查 spec 是否曾寫過具體舉一反三 + 是否有矛盾」):原 L647-678 重複 3 處場景列表 + 「status indicator drift」已移除,本段為**單一 SSOT**。
@@ -656,8 +677,8 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 
 | Token | 答 | 語意 | 典型場景(real consumer grep verified 2026-05-20) |
 |---|---|---|---|
-| `bg-muted`(neutral-2) | **是** | **靜態非互動 surface** — 退化 / placeholder / locked 視覺 | Skeleton(`skeleton.tsx:10`) / DataTable table header(`data-table.tsx:255 HEADER_BG`) / Calendar 非當月日格(`calendar.tsx:312`)/ Alert neutral(`alert.tsx:27`)/ DataTable filter-panel inner group container(`data-table-filter-panel.tsx:780`)/ tab 容器 / code block / scrollbar track(`semantic.css:353`)/ anatomy `<th>` |
-| `bg-secondary`(neutral-3) | **否,只是視覺退後一級** | **存在且微淡可辨** — 元素是正常狀態,但需要退後一級 | Tag neutral(`tag.tsx`)/ Slider rest track(`slider.tsx`)/ FileItem compact-B progress track(`file-item.tsx`)/ Badge low(`badge.tsx:28`)/ CircularProgress track(`circular-progress.tsx:151`)/ Steps fillBg(`steps.tsx:688,701`)/ ProgressBar track(`progress-bar.tsx`)|
+| `bg-muted`(neutral-2) | **是** | **靜態非互動 surface** — 退化 / placeholder / locked 視覺 | Skeleton(`skeleton.tsx:10`) / DataTable table header(`data-table.tsx:312 HEADER_BG`) / Calendar 非當月日格(`calendar.tsx:316`)/ Alert neutral(`alert.tsx:30`)/ DataTable filter-panel inner group container(`data-table-filter-group.tsx:202`,2026-07-14 拆檔自 filter-panel)/ tab 容器 / code block / scrollbar track(`semantic.css:367`)/ anatomy `<th>` |
+| `bg-secondary`(neutral-3) | **否,只是視覺退後一級** | **存在且微淡可辨** — 元素是正常狀態,但需要退後一級 | Tag neutral(`tag.tsx`)/ Slider rest track(`slider.tsx`)/ FileItem compact-B progress track(`file-item.tsx`)/ Badge low(`badge.tsx:37`)/ CircularProgress track(`circular-progress.tsx:150`)/ Steps fillBg(`steps.tsx:698,715`)/ ProgressBar track(`progress-bar.tsx`)|
 
 **判斷法**:「這個元素是『還沒準備好 / 不可操作』嗎?」
 - 是 → `bg-muted`(退化、placeholder 語意)
@@ -667,7 +688,7 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 
 **跟 `bg-neutral-hover` / `bg-neutral-active` 的區別**:neutral 系列表達**互動**狀態(hover / 選中);muted / secondary 表達**結構性的靜態層級** — 即使沒有互動,它永遠是這個顏色。
 
-**邊界 — component disabled bg 不走 muted**:Button / Input / Checkbox 等元件 disabled state 走 `--bg-disabled` semantic,不是 `--muted`(同值 neutral-2 但不同 owner — `--bg-disabled` 是 component-state token,`--muted` 是 surface-non-interactive token,per L169「同值不同語意拆 token」rule)。
+**邊界 — component disabled bg 不走 muted**:Button / Input / Checkbox 等元件 disabled state 走 `--bg-disabled` semantic,不是 `--muted`(同值 neutral-2 但不同 owner — `--bg-disabled` 是 component-state token,`--muted` 是 surface-non-interactive token,per「為什麼同值仍分兩個 token」段 rule)。**Readonly state 同理但用自己的 token `--bg-readonly`**(2026-06-10):readonly ≠ disabled(可聚焦/選取/提交,僅不可改值,per Carbon「navigable but not operable」),不借 `--bg-disabled` 名;也不走 `--muted`(readonly 是互動元件 state,非 Skeleton 類靜態 surface)。三者同值 neutral-2、owner 獨立,可分離演進。
 
 ```tsx
 <Skeleton className="h-4 w-32" />            {/* bg-muted — placeholder 語意 */}
@@ -676,20 +697,19 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 <Badge variant="low">5</Badge>                {/* bg-secondary — 小元素需更明顯底色 */}
 ```
 
-
 ## 邊框 / 分隔
 
 | Utility | Token | 用途 |
 |---------|-------|------|
 | `border-border` | neutral-5 alpha 15% | 元件標準邊框（input / Field family / standalone control)|
-| `border-border-hover` | neutral-6 alpha 25% | input、checkbox、radio 的 hover 邊框 |
+| `border-border-hover` | neutral-6 alpha 25% | input、checkbox、radio 的 hover 邊框——**未 focus 的欄位 hover 走中性、不搶藍**(2026-07-07 源碼實查:MUI text.primary / Polaris input-border-hover / Fluent NeutralStroke1Hover / Carbon・shadcn 不變 = 多數派;Ant colorPrimaryHover 藍 hover 為少數派不採,藍色保留給 focus / 選中)|
 | `border-divider` | neutral-4 alpha 9% | 分隔線（比 border 更淡)/ **table 外框 + row divider 同色**(T-junction connectivity)|
 | `border-[var(--border-opaque)]` | neutral-5 opaque | alpha-immune 變體;cell bg 非白(disabled 灰底 / nested surface)時用 |
 
-選中狀態的邊框或文字使用 hover token：
+選中狀態的邊框或文字使用 base token（2026-07-06 拍板：持續選中站 base、hover 階專屬瞬時態——Ant / Atlassian / Material 三家「瞬時弱、持續強」實錘；SSOT = semantic.css「選中狀態」段）：
 
 ```tsx
-<div className="border-primary-hover text-primary-hover" />
+<div className="border-primary text-primary" />
 ```
 
 ### T-junction connectivity 原則(2026-05-04 升 SSOT)
@@ -700,14 +720,13 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 
 **解法**:**淡化 outer border 至 divider 同色**(從 `border-border` 降到 `border-divider`)。交匯處 seamless,divider 視覺重量不變。
 
-**實作**:DataTable outer 用 `border-divider`(對齊 row 內 dividers)。對齊 Ant Design `colorBorderSecondary` idiom — Ant table 外框 + row divider 同 token。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**實作**:DataTable outer 用 `border-divider`(對齊 row 內 dividers)。對齊 Ant Design `colorBorderSecondary` idiom — Ant table 外框 + row divider 同 token。 <!-- @benchmark-unverified: canonical DS source URL 未驗證(M22(d) 顯式撤回 marker) -->
 
 **何時 outer = `--border` vs `--divider`**:
 - 元件**無 inner divider**(input / Field / Card / Dialog)→ 用 `--border`(獨立邊框,標準視覺重量)
 - 元件**有 inner divider**(Table / List with dividers)→ outer 用 `--divider`(同色,T-junction seamless)
 - 元件 cell bg **非白底**(FCG disabled cell)→ 用 `--border-opaque`(alpha-immune 變體)
 
-
 ## Utility Tokens
 
 | Token | 用途 |
@@ -727,12 +746,10 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 
 自己寫的元件優先用具體的 disabled 色彩（如 `text-fg-disabled`、`bg-[var(--bg-disabled)]`）。`opacity-disabled` 僅作為逃生艙，適用於無法逐一替換內部顏色的場景（第三方元件、複雜多層結構如 Switch）。
 
-
 ## shadcn Compat Aliases(已清除,2026-04-18)
 
 shadcn compat aliases(`bg-background` / `bg-card` / `bg-popover` / `bg-destructive` / `bg-accent` / `border-input` / `*-foreground` 等)2026-04-18 全數移除。新 code 一律用 direct token(`bg-canvas` / `bg-surface` / `bg-surface-raised` / `bg-error` / `bg-neutral-hover` / `border-border`)。`bg-secondary` + `bg-muted` 已升正式語義 token(見 Static Subtle)。
 
-
 ## Nested Theme
 
 任何容器都可以透過 `data-theme="dark"` 或 `data-theme="light"` 切換子元素的色彩語境。最常見的場景是 **Tooltip**——底色是深色，子元素需要 dark token 才可讀。
@@ -769,6 +786,15 @@ CSS 變數在定義元素上解析。`:root` 的 `--foreground: var(--color-neut
 
 容器自身的樣式（如 tooltip 的 `bg-tooltip`）不受子 div 的 `data-theme` 影響——`data-theme` 在子 div 上，只影響子元素。
 
+## 常見誤解
+
+各誤解的完整推理已在本檔對應段落,此處彙整索引:
+
+- 「`--primary` 跟 `--info` 同色所以可互換」— 語義截然不同,status 元件混入 `--primary` 即 fail(見「Status」段 + `status-color-invariant.mjs`)。
+- 「`--fg-disabled` 剛好是我要的灰,拿來當 bg」— 跨 family 借用是 smell(見「fg token 不可當 bg 用」段 Slider case)。
+- 「`bg-muted` / `bg-secondary` 都是淡灰隨便選」— 前者 = 退化 / placeholder,後者 = 正常存在但退後一級(見「Static Subtle Background」段)。
+- 「`--neutral-active` / `--neutral-selected` 同值可合併」— transient vs persistent 語意獨立(見「active vs selected」段)。
+- 「categorical `red` = `--error`」— hue 25 vs deep-orange,完全無關(見「消費規則」注意事項)。
 
 ## 禁止事項
 
@@ -793,12 +819,9 @@ SSOT → `.claude/references/structural-token-retention.md`(6 類保留 + sub-ag
 - `date-grid.spec.md`
 - `file-item.spec.md`
 - `notice.spec.md`
+- `opacity.spec.md`
 - `progress-bar.spec.md`
 - `separator.spec.md`
 - `skeleton.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `opacity.spec.md`
+- `slider.spec.md`
+- `token-system.spec.md`