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

package/src/patterns/resize-handle/resize-handle.stories.tsx

@@ -0,0 +1,71 @@
+// @story-baseline: none — primitive 用 minimal scenario showcase visual + cursor + a11y
+import type { Meta, StoryObj } from '@storybook/react'
+import * as React from 'react'
+import { ResizeHandle } from './resize-handle'
+
+const meta: Meta<typeof ResizeHandle> = {
+  title: 'Design System/Patterns/Resize Handle',
+  component: ResizeHandle,
+  parameters: { layout: 'centered' },
+}
+export default meta
+
+type Story = StoryObj<typeof ResizeHandle>
+
+// Demo:DataTable「訂單金額」欄頭右緣的 resize handle(spec 首要 consumer 場景)
+const ColumnDemo: React.FC<{ isResizing?: boolean; disabled?: boolean }> = ({ isResizing, disabled }) => (
+  <div className="relative inline-block bg-surface border border-divider px-[var(--layout-space-loose)] py-2 w-[200px]">
+    <span className="text-body font-medium">訂單金額</span>
+    <ResizeHandle
+      direction="horizontal"
+      position="end"
+      isResizing={isResizing}
+      disabled={disabled}
+      aria-label="拖曳調整欄寬"
+    />
+  </div>
+)
+
+export const Default: Story = {
+  name: '預設',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ColumnDemo />
+      <p className="text-caption text-fg-secondary">滑鼠移到右邊緣時,游標變成左右拖拉樣式,分隔線顏色加深提示可以拖拉</p>
+    </div>
+  ),
+}
+
+export const Dragging: Story = {
+  name: '拖拉中',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ColumnDemo isResizing />
+      <p className="text-caption text-fg-secondary">拖拉進行中時,整條分隔線變成主色高亮,讓使用者清楚知道正在調整尺寸</p>
+    </div>
+  ),
+}
+
+export const Disabled: Story = {
+  name: '禁用',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ColumnDemo disabled />
+      <p className="text-caption text-fg-secondary">停用時不顯示拖拉游標,輔助技術也會忽略此元件,分隔線維持原本的灰色</p>
+    </div>
+  ),
+}
+
+export const Vertical: Story = {
+  name: '垂直方向',
+  render: () => (
+    <div className="relative bg-surface border border-divider px-[var(--layout-space-loose)] py-2 w-[300px] h-[120px]">
+      <span className="text-body">查詢結果面板</span>
+      <ResizeHandle
+        direction="vertical"
+        position="end"
+        aria-label="拖曳調整面板高度"
+      />
+    </div>
+  ),
+}

package/src/story-governance/category-matrix.json

@@ -0,0 +1,132 @@
+{
+  "_doc": "Storybook 分類治理 SSOT(2026-06-05 RFC P1)。每個 DS 單元屬哪 category + 每 category 該守什麼 storybook 規矩。消費者:storybook-config(runtime sidebar order)+ governance scripts/hooks(稽核)+ /story-writing(產生器)。改規矩只改這裡。",
+  "_decisionTree": [
+    "1. 是原子設計值(色/字/間距/圓角/陰影)? → token",
+    "2. 沒有可 render 的件,只是『怎麼組多個元件解決情境』的指南? → pattern",
+    "3. 是 fork consumer 的 app scaffold? → template",
+    "4. end-user 直接 import 來用(在 root barrel 前門 export + spec frontmatter 無 internal 旗標)? → component",
+    "5. 其餘(spec frontmatter 標 internal 旗標 / 只被 DS 內部 wrap 消費、不在 root 前門) → internal"
+  ],
+  "categories": {
+    "token": {
+      "goal": "全 DS 設計決策的單一來源",
+      "titlePrefix": "Design System/Tokens",
+      "titleParts": 3,
+      "visibility": "public",
+      "sidebarOrder": 1,
+      "requiredStories": "swatch",
+      "renderDemo": "swatch",
+      "autodocs": true,
+      "anatomyDiagram": "n/a",
+      "propsApiTable": false,
+      "stateComboMatrix": "n/a",
+      "a11yTabTest": "exempt",
+      "visualRegression": "swatch",
+      "usageDoDont": "thin",
+      "codeSnippet": "token",
+      "responsiveRtlDensity": "swatch",
+      "contentUxWriting": "n/a",
+      "openSnapshotCoverable": "n/a",
+      "traitShape": false,
+      "classification": "n/a-css",
+      "rootBarrel": "n/a",
+      "universalGuard": true
+    },
+    "component": {
+      "goal": "可直接 render、end-user 直接用的 public 建構塊",
+      "titlePrefix": "Design System/Components",
+      "titleParts": 4,
+      "visibility": "public",
+      "sidebarOrder": 2,
+      "requiredStories": "three-layer",
+      "renderDemo": "required",
+      "autodocs": true,
+      "anatomyDiagram": "required",
+      "propsApiTable": true,
+      "stateComboMatrix": "required",
+      "a11yTabTest": "required",
+      "visualRegression": "full",
+      "usageDoDont": "required",
+      "codeSnippet": "single",
+      "responsiveRtlDensity": "conditional",
+      "contentUxWriting": "conditional",
+      "openSnapshotCoverable": "required",
+      "traitShape": true,
+      "classification": "mechanical=public",
+      "rootBarrel": "include",
+      "universalGuard": false
+    },
+    "pattern": {
+      "goal": "跨元件『如何組合解決情境』的指南 blueprint(非單一 render 件)",
+      "titlePrefix": "Design System/Patterns",
+      "titleParts": 3,
+      "visibility": "public",
+      "sidebarOrder": 3,
+      "requiredStories": "guidance",
+      "renderDemo": "composed-example",
+      "autodocs": true,
+      "anatomyDiagram": "n/a",
+      "propsApiTable": false,
+      "stateComboMatrix": "n/a",
+      "a11yTabTest": "per-example",
+      "visualRegression": "composed",
+      "usageDoDont": "core",
+      "codeSnippet": "composed",
+      "responsiveRtlDensity": "composed",
+      "contentUxWriting": "guidance",
+      "openSnapshotCoverable": "composed",
+      "traitShape": false,
+      "classification": "guidance-no-component",
+      "rootBarrel": "n/a",
+      "universalGuard": true
+    },
+    "internal": {
+      "goal": "只被 DS 內部其他元件 wrap/compose 的 primitive",
+      "titlePrefix": "Design System/Internal",
+      "titleParts": 4,
+      "visibility": "filtered",
+      "sidebarOrder": 5,
+      "requiredStories": "reference",
+      "renderDemo": "reference-only",
+      "autodocs": false,
+      "anatomyDiagram": "optional",
+      "propsApiTable": true,
+      "stateComboMatrix": "optional",
+      "a11yTabTest": "required",
+      "visualRegression": "full",
+      "usageDoDont": "thin",
+      "codeSnippet": "import-note",
+      "responsiveRtlDensity": "conditional",
+      "contentUxWriting": "thin",
+      "openSnapshotCoverable": "required",
+      "traitShape": "optional",
+      "classification": "mechanical=internal",
+      "rootBarrel": "exclude",
+      "universalGuard": false
+    },
+    "template": {
+      "goal": "fork consumer 的 app scaffold(消費端起手式)",
+      "titlePrefix": "Apps",
+      "titleParts": "apps",
+      "visibility": "consumer",
+      "sidebarOrder": 9,
+      "requiredStories": "app-scenario",
+      "renderDemo": "app",
+      "autodocs": false,
+      "anatomyDiagram": "n/a",
+      "propsApiTable": false,
+      "stateComboMatrix": "n/a",
+      "a11yTabTest": "per-example",
+      "visualRegression": "opt",
+      "usageDoDont": "n/a",
+      "codeSnippet": "scaffold",
+      "responsiveRtlDensity": "consumer",
+      "contentUxWriting": "n/a",
+      "openSnapshotCoverable": "n/a",
+      "traitShape": false,
+      "classification": "scaffold",
+      "rootBarrel": "n/a",
+      "universalGuard": true
+    }
+  }
+}

package/src/story-governance/category-matrix.ts

@@ -0,0 +1,55 @@
+// category-matrix.ts — Storybook 分類治理 typed SSOT wrapper(2026-06-05 RFC P1)。
+//
+// 單一來源(SSOT):每個 DS 單元屬哪 category + 每 category 該守什麼 storybook 規矩。
+// 資料在 category-matrix.json(governance .mjs 腳本直接讀);本檔提供 typed 介面 + 決策樹 resolver
+// 給 runtime 消費者(storybook-config sidebar order / 未來 docs 產生器)。改規矩只改 .json。
+//
+// 對應 RFC .claude/planning/2026-06-05-storybook-category-taxonomy-rfc.md §10-11。
+
+import matrixData from './category-matrix.json'
+
+export type Category = 'token' | 'component' | 'pattern' | 'internal' | 'template'
+
+export interface CategoryRule {
+  goal: string
+  titlePrefix: string
+  titleParts: number | string
+  visibility: 'public' | 'filtered' | 'consumer'
+  sidebarOrder: number
+  requiredStories: string
+  renderDemo: string
+  autodocs: boolean
+  anatomyDiagram: string
+  propsApiTable: boolean
+  stateComboMatrix: string
+  a11yTabTest: string
+  visualRegression: string
+  usageDoDont: string
+  codeSnippet: string
+  responsiveRtlDensity: string
+  contentUxWriting: string
+  openSnapshotCoverable: string
+  traitShape: boolean | string
+  classification: string
+  rootBarrel: string
+  universalGuard: boolean
+}
+
+export const CATEGORY_MATRIX = matrixData.categories as Record<Category, CategoryRule>
+
+// 決策樹 resolver:由 folder path + frontmatter.isInternal 機械判 category。
+// 對應 json._decisionTree;token/template 先判(folder 強訊號),再 isInternal,再 patterns/components。
+export function resolveCategory(opts: { path: string; isInternal?: boolean }): Category {
+  const p = opts.path.replace(/\\/g, '/')
+  if (p.includes('/tokens/')) return 'token'
+  if (p.includes('/apps/')) return 'template'
+  if (opts.isInternal) return 'internal'
+  if (p.includes('/components/Internal/')) return 'internal'
+  if (p.includes('/patterns/')) return 'pattern'
+  if (p.includes('/components/')) return 'component'
+  return 'internal'
+}
+
+export function ruleFor(opts: { path: string; isInternal?: boolean }): CategoryRule {
+  return CATEGORY_MATRIX[resolveCategory(opts)]
+}

package/src/styles/base.css

@@ -0,0 +1,92 @@
+/* @qijenchen/design-system/styles/base — consumer runtime CSS SSOT
+ *
+ * Why(2026-05-29 fix:ds-product-template storybook 字體 drift,user「請你追根究底去解決」授權):
+ *   `styles/tokens` is the single consumer import. It must include the runtime CSS
+ *   needed by shipped DS components: base element styles plus custom utilities
+ *   backed by DS-owned keyframes.
+ *
+ *   本檔抽出 base 層為單一 SSOT:DS `src/globals.css` + consumer 都 import,字體/reset 永不 drift。
+ *   codex 2026-05-29 dual-track 共識 option (a)。
+ *
+ * 用法(consumer,放在 tokens import 之後):
+ *   @import '@qijenchen/design-system/styles/tokens';
+ *   @import '@qijenchen/design-system/styles/base';
+ */
+
+/* lucide 全域 stroke width — DS-wide icon 預設 1.75(比 lucide 原廠 2 輕一階的整體風格)。
+   ⚠️ 必須限定 [stroke-width="2"](= 沒被 component 顯式覆寫的 icon):
+   2026-06-12 修 — 原寫法 `.lucide { ... }` 無條件蓋掉所有 explicit strokeWidth prop
+   (CSS class > SVG presentation attribute),導致 Checkbox/Switch/Steps/PeoplePicker
+   的小尺寸 stroke 補償(strokeWidth 3 / 2.5)自 2026-04-08 起從未真正渲染
+   (rendered DOM 驗證:attr=3 但 computed=1.75px,實畫 0.80px vs 設計 1.50px)。
+   限定後:lucide 預設(attr=2)→ 1.75;顯式 prop(3 / 2.5 / 1.75)→ attribute 直接生效。
+   補償值 SSOT → .claude/references/ui-dev-rules.md「小尺寸 icon stroke 補償」 */
+.lucide[stroke-width='2'] {
+  stroke-width: 1.75;
+}
+
+@layer base {
+  *,
+  ::before,
+  ::after {
+    box-sizing: border-box;
+    border-color: var(--color-neutral-5);
+  }
+
+  body {
+    background-color: var(--canvas);
+    color: var(--foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--ring);
+    outline-offset: 2px;
+  }
+
+  /* Button pointer cursor(Tailwind v4 移除 v3 的 button cursor,補回符合 UX 直覺) */
+  button:not(:disabled),
+  [role="button"]:not(:disabled) {
+    cursor: pointer;
+  }
+}
+
+/* Radix Collapsible height animation — consumed by TreeView. */
+@keyframes collapsible-down {
+  from { height: 0; }
+  to { height: var(--radix-collapsible-content-height); }
+}
+
+@keyframes collapsible-up {
+  from { height: var(--radix-collapsible-content-height); }
+  to { height: 0; }
+}
+
+@utility animate-collapsible-down {
+  animation: collapsible-down 150ms ease-out;
+}
+
+@utility animate-collapsible-up {
+  animation: collapsible-up 150ms ease-out;
+}
+
+/* Radix Accordion height animation — Radix exposes a different content-height var. */
+@keyframes accordion-down {
+  from { height: 0; }
+  to { height: var(--radix-accordion-content-height); }
+}
+
+@keyframes accordion-up {
+  from { height: var(--radix-accordion-content-height); }
+  to { height: 0; }
+}
+
+@utility animate-accordion-down {
+  animation: accordion-down 200ms ease-out;
+}
+
+@utility animate-accordion-up {
+  animation: accordion-up 200ms ease-out;
+}

package/src/styles/tokens.css

@@ -33,3 +33,14 @@
 @import './../tokens/radius/radius.css';
 @import './../tokens/opacity/opacity.css';
 @import './../tokens/motion/motion.css';
+
+/* Non-token CSS (patterns/ + components/) containing token/runtime declarations
+   or component-internal styles — auto-detected by generator scan. Per 2026-05-27
+   root-cause fix: src/globals.css 已 import for DS internal, 但 consumer-facing
+   tokens.css aggregator 必須也包含, 不然 consumer 拿不到 → 跑版。 */
+@import './../components/DataTable/data-table.css';
+@import './../patterns/header-canonical/header-canonical.css';
+
+/* Base layer — body typography(font-family var(--font-sans))+ reset + focus + button cursor。
+   必在 token 之後(依賴 token vars)。Consumer `@import tokens` 一次拿到。SSOT: styles/base.css。 */
+@import './base.css';

package/src/tokens/README.md

@@ -1,5 +1,7 @@
 # tokens/ Charter
 
+> **跨 family canonical SSOT** → `token-system.spec.md`(5-layer 架構 / 命名 family-scoped 規則 / token vs hardcode 判斷 / co-location rationale)。每個 family spec.md 只 codify 自家具體規則,本 README 列 family 居住地圖,SSOT 集中在 `token-system.spec.md` 避免 drift。
+
 ## 這裡只收:design token 定義 + spec + stories
 
 每個 token 類別一個 folder:
@@ -14,7 +16,9 @@
 
 ## 當前居民
 
-`color/` / `typography/` / `uiSize/` / `layoutSpace/` / `density/` / `elevation/` / `radius/` / `opacity/`
+`color/` / `typography/` / `uiSize/` / `layoutSpace/` / `density/` / `elevation/` / `radius/` / `opacity/` / `motion/`
+
+例外居民:`categorical-color.ts` 住 tokens/ 根層(非 folder)— `CATEGORICAL_HUES` 的 TypeScript SSOT,由 `color/color.spec.md` 指認(Tag / Avatar 等 categorical 色相消費)。
 
 ## Consumer scope:public vs internal token(2026-05-17 codified)
 
@@ -22,8 +26,9 @@
 |---|---|---|
 | `color/` / `typography/` / `radius/` / `elevation/` / `opacity/` / `layoutSpace/` / `density/` | **Public** — consumer-layer(`src/app` / `src/explorations`)直接消費 | UI 開發者寫 `text-body` / `bg-primary` / `--layout-space-loose` 等 |
 | `uiSize/`(`--field-height-*` / `--tab-height-*` / `--table-row-*` / `--tree-indent-*`)| **Internal primitive** — DS 內部 component 消費,consumer 不直接用 | Button / Input / Tabs / DataTable / TreeView 等 primitive 內部消費;consumer 用 `<Button size="sm">` 不用 `h-[var(--field-height-sm)]` |
+| `motion/`(`--hover-delay-*`)| **Internal primitive** — DS overlay 元件內部消費,consumer 不直接用 | Tooltip / HoverCard / Avatar / OverflowIndicator 的 hover open / close delay;consumer 用元件預設,不直接讀 token |
 
-**Internal token 規則**(`uiSize/` 適用):
+**Internal token 規則**(`uiSize/` / `motion/` 適用):
 - **不必補 Storybook stories**(consumer 不直接看;審查 grep 結果:`src/app` + `src/explorations` 0 個檔案直接消費 uiSize token,2026-05-17 verified)
 - 但仍有 `.spec.md` codify family / 命名 / 派生公式
 - 出現在 consumer-layer code = anti-pattern(該用 component prop 不該 raw token)

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)。
+ * **機械防線**:`check_categorical_color_1to1.sh` 強制 map 的 key X 的值含 `--color-X-`(名實一致,禁 offset)。
+ */
+
+/** 12 個 categorical 色相(順序對齊 primitives.css / Storybook color token 列)。 */
+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 / turquoise / indigo / purple / magenta
+ *   - 太亮的色底 → `text-on-emphasis-dark`(深):yellow / amber / orange / lime(白字連 3:1 都不過)
+ *   - ★ 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',
+  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)' },
+  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)]',
+}