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

package/src/patterns/resize-handle/resize-handle.spec.md

@@ -15,14 +15,14 @@ benchmark:
 
 ## 定位
 
-**Drag-to-resize 視覺 + a11y 共同 primitive**——統一 column resize / sidebar drag-resize / row resize / panel resize 的命中區、cursor、視覺 line、a11y attributes。
+**Drag-to-resize 視覺共同 primitive**——統一 column resize / sidebar drag-resize / row resize / panel resize 的命中區、cursor 與視覺 line。
 
 **消費者(計畫)**:
 - DataTable column resize(目前自畫 — Phase 2 migrate)
 - Sidebar drag-resize(目前無 — Phase 3 enable)
 - AppShell Aside drag-resize(目前無 — Phase 4 enable)
 
-**不耦合 drag math** — consumer 自管 width state(TanStack `header.getResizeHandler()` / 手刻 pointer math / `useResizeObserver` 各種路徑)。本 primitive only ship 視覺 + cursor + a11y。
+**不耦合 drag math** — consumer 自管 width state(TanStack `header.getResizeHandler()` / 手刻 pointer math / `useResizeObserver` 各種路徑)。本 primitive only ship 視覺 + cursor，且固定 aria-hidden。
 
 **Layout Family**:N/A(self-contained primitive,非 row-layout family member)。
 
@@ -38,24 +38,27 @@ benchmark:
   position="end"           // | "start"
   isResizing?: boolean     // consumer 自管 drag state
   disabled?: boolean       // consumer 自決 resizable opt-in
-  aria-label="拖曳調整欄寬" // 必傳
   showLine?: boolean       // default true,false = consumer paint own line
   lineInsetStart?: string  // line start inset(eg. var(--table-cell-py))
   lineInsetEnd?: string    // line end inset
-  onPointerDownCapture?: (e: React.PointerEvent) => void  // consumer 接 drag math
+  // …其餘 DOM 事件(onPointerDownCapture / onPointerDown / onTouchStart 等)非自有 typed prop
 />
 ```
 
+上方為自有(own)props。drag handler(`onPointerDownCapture` / `onPointerDown` / `onTouchStart` 等)**非本元件 bespoke typed prop**,而是經 `ResizeHandleProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'role' | 'aria-label' | 'aria-orientation' | 'aria-hidden'>` 的 `...restProps` spread 透傳到底層 `<span>`(與 `onClick` / `onPointerMove` 等 generic DOM 事件同 status)。上述四個 ARIA props 由 primitive 固定為誠實的純 pointer decoration 契約，consumer 不可覆寫。consumer 接 drag math 即透過這些透傳事件,本 primitive 不耦合。
+
 **direction**:
-- `horizontal`(拖左右)→ `cursor: col-resize` + `aria-orientation="vertical"`(separator 軸垂直於 drag)
-- `vertical`(拖上下)→ `cursor: row-resize` + `aria-orientation="horizontal"`
+- `horizontal`(拖左右)→ `cursor: col-resize`
+- `vertical`(拖上下)→ `cursor: row-resize`
 
 **position**:`end` 命中區在右(horizontal)/ 底(vertical)— column right edge / sidebar right edge 典型;`start` 左 / 上 — 罕用。
 
 ## 視覺 canonical(對齊 DataTable v11)
 
+取值依據:7px 命中區 / 1px line 非自創——來自下方「世界級對照細節」5 家共識(hit zone 7-8px fingertip-friendly / 1px line non-intrusive)+ DataTable v11 已 ship 的既有 canonical(本 primitive 抽取自它,M17)。
+
 - **命中區**:7px 寬(horizontal)/ 高(vertical),`-3px` outward offset 跨 boundary 抓得到
-- **Visual line**:1px,positioned `right-[3px]` / `bottom-[3px]`,default full-extent
+- **Indicator**:消費既有 DataTable resize indicator contract，預設覆蓋完整可調整邊；確切 thickness / offset 與 source utility 由 `resize-handle.tsx` 擁有
   - **idle**:`bg-divider`
   - **disabled**:`bg-divider`(無 hover affordance)
   - **hover**:`bg-[var(--border-hover)]`(via `group/resize` selector)
@@ -65,9 +68,8 @@ benchmark:
 
 ## a11y
 
-- **`role="separator"`** + **`aria-orientation`** + **`aria-label`**:對齊 WAI-ARIA「separator widget」pattern(MDN: separator role)
-- 鍵盤導覽 future Phase: Arrow keys 微調 + Enter 顯式 commit(consumer Phase 2+ 補)
-- `disabled` 時不掛 role / orientation / label(語意正確 — disabled separator 不該為 a11y tree 入口)
+- 固定 `aria-hidden="true"`:目前只有 pointer hit target / visual line，沒有 focus、`aria-valuenow/min/max`、`aria-controls` 或 Arrow-key 行為，不能冒充 WAI-ARIA separator/window-splitter widget。
+- consumer 若把 resize 作為必要功能，必須另提供 keyboard-operable 等價控制；完整 splitter widget 需由新元件一次擁有 value、controls 與鍵盤 contract，不能在本 visual primitive 上零碎加 ARIA。
 
 ## 何時用 / 何時不用
 
@@ -78,6 +80,13 @@ benchmark:
 - Image crop 邊界(專用 `<ImageCropTool>` 領域)
 - Splitter pane (`resizable-panes` style)— 雙端 drag with linked state(future 評估抽 `<SplitPane>` 上層 primitive 消費本 handle)
 
+## 邊界案例
+
+- **Disabled**:仍渲染 1px line(`bg-divider`,無 hover affordance),但無 cursor、無 `select-none`;所有狀態皆固定從 accessibility tree 隱藏。
+- **拖到 min / max 卡住**:primitive 不持 width state(不耦合 drag math),邊界 clamp 與卡住回饋由 consumer 的 resize handler 管;`isResizing` 期間 line 維持 `bg-primary` 不另示警。
+- **同列多 handle 並存**(多欄 column resize):各 handle 為獨立 `<span>`,無互相協調;`-3px` outward offset 使相鄰欄命中區可能相接,先命中者(DOM 順序 / pointer target)收事件,衝突仲裁屬 consumer drag math。
+- **RTL**:全域明定 LTR-only；本元件使用 physical `left/right` 定位，不提供 RTL 鏡像。
+
 ## Roadmap(用 user 既有的 v2 framing)
 
 | Phase | Scope | Status |
@@ -94,16 +103,16 @@ Phase 2-4 需獨立 RFC + 各別 user approval,本 spec 只 ship Phase 1 + 鎖
 | DS / Library | 命中區 | Line | Cursor | a11y |
 |---|---|---|---|---|
 | **AG Grid** | 7-8px | 1px primary on drag | col-resize | role="separator" |
-| **Material X-DataGrid** | `MuiDataGrid-iconSeparator` 8px | 1px hairline | col-resize | aria-label "Resize column" |
+| **Material X-DataGrid** | column-separator(resize 命中區)~8px | 1px hairline(`MuiDataGrid-iconSeparator` 是純裝飾分隔 icon,非命中區也非 a11y 來源)| col-resize | aria-label "Resize column" | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 | **Notion(column / sidebar)** | ~6-8px | 1px line | col-resize | (DOM-only,無 role)|
 | **VS Code** | 8px(activity bar)| bg highlight on drag | col-resize | aria-label "Resize" |
 | **Figma** | 8px | 1px line | col-resize | role separator |
 
-共識:7-8px hit zone / 1px line / cursor 對應 direction / role="separator" + aria-label。本 primitive 7px hit zone + 全對齊。
+視覺共識是 7-8px hit zone / 1px line / cursor 對應 direction；各產品 a11y contract 不一致。本 primitive 只收斂視覺，不把未實作的 splitter behavior 偽裝成 separator。
 
 ## 禁止事項
 
 - ❌ 自畫 resize handle 視覺(`<div className="cursor-col-resize">`)— 必消費本 primitive
 - ❌ 直接給 ResizeHandle 加 drag state hook(eg. `useColumnResize`)— drag math 是 consumer concern,不污染 primitive
 - ❌ Phase 2/3/4 不走 RFC + user approval 自動 migrate — Audit-vs-execute 分權違反
-- ❌ 重新發明 a11y attributes — `role="separator"` + `aria-orientation` + `aria-label` SSOT 不可漂移
+- ❌ 在本 pointer-only primitive 加 `role="separator"` / `aria-*value*`——完整 splitter 語意必須連同 keyboard/value/controls 一次實作

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

@@ -0,0 +1,73 @@
+// @story-baseline: none — primitive 用 minimal scenario showcase visual + cursor
+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',
+  tags: ['autodocs'],
+  component: ResizeHandle,
+  parameters: {
+    layout: 'centered',
+    docs: { description: { component: '可調整面板尺寸的拖曳把手，提供方向、游標與可操作區的一致基礎。當 split pane 或側欄允許使用者調整寬高時使用，不作一般分隔線。' } },
+  },
+}
+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}
+    />
+  </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"
+      />
+    </div>
+  ),
+}

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

@@ -2,11 +2,11 @@ import * as React from 'react'
 import { cn } from '@/lib/utils'
 
 /**
- * ResizeHandle — pattern primitive for drag-to-resize visual + a11y(2026-05-21 v1 ship per
+ * ResizeHandle — pattern primitive for drag-to-resize visual hit target(2026-05-21 v1 ship per
  * user「style 難道不用跟 data table column resize 維持 ssot」+「都照你建議做」approval)。
  *
  * ── 定位 ──
- * 統一所有 drag-resize affordance 的視覺 / cursor / 命中區 / a11y attributes。
+ * 統一所有 drag-resize affordance 的視覺 / cursor / 命中區。
  * Consumer 自管 drag math(TanStack column resize / Sidebar drag-resize / Aside drag-resize
  * 各有不同 width state pathway,本 primitive 不耦合)。
  *
@@ -32,13 +32,16 @@ import { cn } from '@/lib/utils'
  * - Figma left panel resize(8px hit zone + 1px line)
  *
  * 統一共識:hit zone ≥ 7px(fingertip-friendly)/ 1px visual line(non-intrusive)/
- * hover affordance(stronger line) / drag feedback(primary highlight) /
- * a11y `role="separator"` + `aria-orientation` + 描述性 aria-label。
+ * hover affordance(stronger line) / drag feedback(primary highlight)。
+ *
+ * 本 primitive 目前只有 pointer drag visual/hit target，沒有 keyboard/value/controls contract；
+ * 因此固定從 accessibility tree 隱藏，不冒充 WAI-ARIA separator/window-splitter widget。
  */
-export interface ResizeHandleProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'role'> {
+export interface ResizeHandleProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'role' | 'aria-hidden' | 'aria-label' | 'aria-orientation'> {
   /**
    * Drag 方向。`horizontal` = 拖拉左右(column resize / sidebar width);
-   * `vertical` = 拖拉上下(row resize / panel height)。決定 cursor + aria-orientation。
+   * `vertical` = 拖拉上下(row resize / panel height)。決定 cursor。
    */
   direction: 'horizontal' | 'vertical'
   /**
@@ -53,11 +56,9 @@ export interface ResizeHandleProps extends Omit<React.HTMLAttributes<HTMLSpanEle
   isResizing?: boolean
   /**
    * 是否禁用拖拉。consumer 透過 col / panel 的 resizable flag 決定。
-   * 禁用時不 render cursor + 不 attach a11y role。
+   * 禁用時不 render cursor；元件所有狀態皆固定 aria-hidden。
    */
   disabled?: boolean
-  /** a11y 描述性 label。consumer 必傳(eg. 「拖曳調整欄寬」/「拖曳調整側欄寬度」)。 */
-  'aria-label': string
   /**
    * 是否畫 visual line(1px divider)。`false` = consumer 已 paint(eg. DataTable panel
    * boundary col by panel-r 接管,不重複)。Default `true`。
@@ -82,7 +83,6 @@ export interface ResizeHandleProps extends Omit<React.HTMLAttributes<HTMLSpanEle
  *   position="end"
  *   isResizing={header.column.getIsResizing?.()}
  *   disabled={!isResizable}
- *   aria-label="拖曳調整欄寬"
  *   onPointerDownCapture={(e) => {
  *     e.stopPropagation()
  *     header.getResizeHandler?.()(e.nativeEvent)
@@ -96,7 +96,6 @@ export interface ResizeHandleProps extends Omit<React.HTMLAttributes<HTMLSpanEle
  *   direction="horizontal"
  *   position="end"
  *   isResizing={isDragging}
- *   aria-label="拖曳調整側欄寬度"
  *   onPointerDown={startDrag}
  * />
  * ```
@@ -117,7 +116,6 @@ export const ResizeHandle = React.forwardRef<HTMLSpanElement, ResizeHandleProps>
     ref,
   ) => {
     const isHorizontal = direction === 'horizontal'
-    const ariaOrientation = isHorizontal ? 'vertical' : 'horizontal'  // separator's axis is perpendicular to drag
 
     // 命中區用 inline style 而非 Tailwind arbitrary values(避免 Tailwind v4 JIT 對新增 arbitrary
     // class 在 dev mode 不更新 stylesheet 的 quirk;7px 是 primitive constant 非 token,inline 妥當)。
@@ -162,17 +160,14 @@ export const ResizeHandle = React.forwardRef<HTMLSpanElement, ResizeHandleProps>
           ...(position === 'end' ? { bottom: 3 } : { top: 3 }),
         }
 
-    // 抽 aria-label / style 由我們管,其他 ...props 不重複
-    const { 'aria-label': ariaLabel, style: extraStyle, ...restProps } = props
+    const { style: extraStyle, ...restProps } = props
     return (
       <span
         ref={ref}
-        role={disabled ? undefined : 'separator'}
-        aria-orientation={disabled ? undefined : ariaOrientation}
-        aria-label={disabled ? undefined : ariaLabel}
+        {...restProps}
+        aria-hidden="true"
         style={{ ...hitZoneStyle, ...extraStyle }}
         className={cn('group/resize', !disabled && 'select-none', className)}
-        {...restProps}
       >
         {showLine && (
           <span

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,99 @@
+/* @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 → packages/design-system/ds-canonical/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;
+  }
+
+  /* 文字反白 — 底色 token 化(--text-selection;SSOT = color.spec.md「Highlight」段)。
+     只動底色、不動字色:半透明品牌藍疊在原字色下,反白後文字對比 ≥4.5:1 由驗收量測保證
+     (MDN ::selection 對比要求)。 */
+  ::selection {
+    background-color: var(--text-selection);
+  }
+
+  /* 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

@@ -25,6 +25,9 @@
 
    ═══════════════════════════════════════════════════════════════════════ */
 
+/* Overlay 進出場動畫 utilities(tw-animate-css;7 浮層消費)*/
+@import "tw-animate-css";
+
 @import './../tokens/color/primitives.css';
 @import './../tokens/color/semantic.css';
 @import './../tokens/typography/typography.css';
@@ -33,3 +36,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/`(`--motion-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)
@@ -38,8 +43,8 @@
 | 疑似要放這但其實不是 | 實際應去 | 為什麼 |
 |-------------------|---------|--------|
 | 元件消費 token 的 code | `../components/{Name}/` | token 被 consume,不在 token home 寫 consumer |
-| cross-cutting design rule(如「何時用 semantic token vs primitive」)| `.claude/rules/ui-development.md`「Token 命名 4 條硬規則」 | 系統級 rule,不只關某個 token |
-| shadcn compat alias 遷移規則 | `.claude/rules/ui-development.md`「Tailwind 5 條核心」 | 技術陷阱屬 UI 開發 |
+| cross-cutting design rule(如「何時用 semantic token vs primitive」)| `packages/design-system/ds-canonical/rules/ui-development.md`「Token 命名 4 條硬規則」 | 系統級 rule,不只關某個 token |
+| shadcn compat alias 遷移規則 | `packages/design-system/ds-canonical/rules/ui-development.md`「Tailwind 5 條核心」 | 技術陷阱屬 UI 開發 |
 
 ## 新增 token 的 criteria
 
@@ -50,4 +55,4 @@
 
 ## 建立前必 Read
 
-`.claude/rules/ui-development.md`「Token 命名 4 條硬規則」+ 對應 family 的 spec(如 `color/color.spec.md`)。
+`packages/design-system/ds-canonical/rules/ui-development.md`「Token 命名 4 條硬規則」+ 對應 family 的 spec(如 `color/color.spec.md`)。