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

package/ds-canonical/references/scenario-definition.md

@@ -0,0 +1,146 @@
+# Scenario Definition — Monorepo 2-Scenario Architecture(SSOT)
+
+> **2026-05-29 ship**:本 file 為 Scenario A / Scenario B 定義 + 互動方式 + verify checkpoints 的**唯一 SSOT**。所有 skill / hook / spec / CLAUDE.md 文字 reference 此 file,**不重述定義**(per user「無多餘重複 SSOT」directive)。
+
+> **設計起源**:user 2026-05-29 verbatim「實際上會有兩種場景,一種是直接 fork ds repo 用的一種是 fork template repo 用的使用者,兩種情境都要確保完整沒有斷點又能確保 SSOT」+ codex r5 synthesize verdict(8 gap fix)。
+
+## 1. 兩 Scenario 定義
+
+### Scenario A — Direct fork DS repo
+
+**用戶**:DS 共同維護者 / 想看 DS source 一起改 DS + 寫 product 的人
+**入口**:fork `ajenchen/design-system` GitHub repo
+**他拿到**:DS source(`packages/design-system/`)+ 治理(`.claude/`)native readable + scaffold(`apps/template/`)+ scripts
+**DS 取得方式**:`packages/*` npm workspace link(local resolution)
+**Governance 取得**:`.claude/` 直接讀,**不需 `/plugin install`**(他有 source)
+**E2E 流程**:`fork → npm install → claude → npm run create-app order-dashboard → npm install(workspace re-link)→ npm run storybook → git push`
+**禁**:edit `packages/design-system/src/**` 沒 user approval(`check_substantive_edit_approval_preflight.sh` 攔)
+
+### Scenario B — Fork published template repo
+
+**用戶**:純做產品 / 不需看 DS source 的人
+**入口**:`ajenchen/ds-product-template` GitHub「Use this template」(該 repo 內容 = mirror artifact,**非 SSOT**,by 自動 mirror workflow auto-generate from DS repo)
+**他拿到**:scaffold + 治理 via C-prime committed-config(.claude hooks + SessionStart preamble 注入)+ DS + 治理本體 via npm
+**DS 取得方式**:`@qijenchen/design-system` npm registry(`^X.Y.Z`)
+**Governance 取得**:committed `.claude/settings.json`(dispatcher hooks + fail-open bootstrap)+ SessionStart 注入 npm-current preamble;本體在 npm `ds-canonical/fork`(`npm install` / `npm run sync-all` 同步)。**不需 /plugin install**(雲端不可靠 #62174/#63028)
+**E2E 流程**:`fork → npm install(治理本體隨 npm + committed hook 自動生效,免 plugin)→ claude → npm run setup:netlify(Netlify env var 設 STORYBOOK_BASIC_AUTH = user:password,免費機制走 edge function basic-auth)→ npm run create-app order-dashboard → npm install → npm run storybook → git push`
+**禁**:import `@qijenchen/design-system/src/**` 或 `/dist/**`(`lint:imports` 攔)
+
+## 2. SSOT Architecture
+
+```
+ajenchen/design-system (DS repo) ── SSOT ───────────────────────────┐
+├── packages/design-system/       ← DS library source                │
+├── apps/template/                ← Product app seed                 │
+├── scripts/                      ← Shared workflow scripts          │
+│   ├── create-app.mjs            ← copy apps/template → apps/<name> │
+│   ├── setup-netlify-access.mjs                                      │
+│   ├── build-published-template-mirror.mjs ← mirror builder         │
+│   └── (4 other consumer scripts)                                    │
+├── .devcontainer/                ← Codespaces cloud-dev path        │
+├── .storybook/main.ts            ← globs sharedStoryGlobs + apps/** │
+├── .claude/                      ← Governance(skills/hooks/rules)   │
+├── template/ds-product-template/ ← Consumer-specific scaffold       │
+│   ├── CLAUDE.md / README.md     ← Scenario B onboarding docs       │
+│   ├── .storybook/main.ts        ← apps-only glob(no DS internal)  │
+│   ├── package.json              ← consumer workspaces + npm deps   │
+│   └── (.github / .gitignore / .npmrc / netlify.toml / docs / ...)  │
+└── .github/workflows/                                                │
+    └── mirror-to-published-template.yml ← auto sync on push main    │
+                                                                      │
+                              ↓ (workflow + CROSS_REPO_TOKEN PAT)    │
+                                                                      │
+ajenchen/ds-product-template (published repo) ← Mirror artifact ─────┘
+(Scenario B fork users land here via「Use this template」)
+```
+
+## 3. Mirror Workflow Chain(Scenario B 自動同步)
+
+**Trigger**:DS push main + template-affecting paths(per `.github/workflows/mirror-to-published-template.yml`):
+- `apps/template/**`
+- `scripts/create-app.mjs` + `scripts/setup-netlify-access.mjs` + `scripts/check-plugin-installed.mjs` + `scripts/build-published-template-mirror.mjs`
+- `.devcontainer/**`
+- `template/ds-product-template/**`
+- `package.json`
+
+**Build**:`scripts/build-published-template-mirror.mjs` 用 ALLOWLIST(non denylist,per codex r5)+ transform:
+- Flatten `template/ds-product-template/*` → mirror root
+- Transform `package.json`:`workspaces=["apps/*"]` + DS dep `^X.Y.Z`
+- Transform `apps/template/package.json`:`@qijenchen/design-system: "*"` → `^X.Y.Z`
+- 4 integrity scans:DS source residue / secret leak / Storybook glob / package dep
+
+**Push**:`workflow + CROSS_REPO_TOKEN PAT(user one-time setup,workflow 印中文指引若 missing)` force-push to `ajenchen/ds-product-template` main
+
+## 4. Test Cases(Claude 19 + codex 18 union → 20 canonical)
+
+### Scenario A(6 cases)
+
+| # | Test | Verify cmd |
+|---|---|---|
+| A1 | Workspace link resolution(apps/template DS dep `*` → packages/design-system local)| `jq '.dependencies' apps/template/package.json` |
+| A2 | DS source edit attempt → approval-preflight hook BLOCKER + 中文訊息 | `echo '{...}' \| bash .claude/hooks/check_substantive_edit_approval_preflight.sh` |
+| A3 | `.claude/` native readable(無需 /plugin install)| `ls .claude/{skills,hooks,rules}/` |
+| A4 | `npm run create-app <name>` → `apps/<name>/` 從 `apps/template/` 複製 + story title patched `Apps/<name>/...` | run + ls + grep |
+| A5 | DS root `npm run storybook` 含 DS internal stories + `apps/**` stories,namespace 不撞 | grep `.storybook/main.ts` stories glob + 跑 storybook |
+| A6 | Workspaces 含 `apps/*` | `jq '.workspaces' package.json` |
+
+### Scenario B(7 cases,via mirror artifact)
+
+| # | Test | Verify cmd |
+|---|---|---|
+| B1 | Mirror artifact npm deps `^X.Y.Z`(not workspace `*`)| `jq '.dependencies' /tmp/mirror/package.json` |
+| B2 | Mirror 0 DS source(`packages/design-system/src/` 不存在)| `! -d /tmp/mirror/packages/design-system` |
+| B3 | Mirror workspaces apps-only | `jq '.workspaces' /tmp/mirror/package.json` |
+| B4 | Mirror `.storybook/main.ts` apps-only glob | grep stories |
+| B5 | Mirror 含 `check-plugin-installed.mjs` + `setup-netlify-access.mjs` + `create-app.mjs` | ls /tmp/mirror/scripts/ |
+| B6 | C-prime committed 治理(免 plugin):`npm install` 後 `ds-canonical/fork` 本體就位 + SessionStart 注入設計紀律 preamble + dispatcher 跑 fork hooks;既有 fork `sync-all` 移除 obsolete plugin-era hook | `node scripts/test-fork-governance.mjs` + `node scripts/dogfood-prepublish-verify.mjs` |
+| B7 | `npm run create-app` 同 Scenario A | run + ls |
+
+### Mirror integrity(7 cases)
+
+| # | Test | Verify cmd |
+|---|---|---|
+| M1 | Trigger on DS push main with template-affecting paths(workflow path filter)| workflow log |
+| M2 | DS source residue scan 0 leak(8 paths checked)| build script integrity scan 1 |
+| M3 | Secret leak scan 0 leak(6 paths checked)| build script integrity scan 2 |
+| M4 | Storybook glob apps-only(no `../packages/**`)| build script integrity scan 3 |
+| M5 | package.json workspaces apps-only + DS dep transformed | build script integrity scan 4 |
+| M6 | `apps/template/package.json` DS dep `*` → `^X.Y.Z` | build script auto transform |
+| M7 | Force-push idempotent(reproducible)| `node scripts/build-published-template-mirror.mjs --out=/tmp/x` 多次 = 相同 output |
+
+## 5. Verify Checkpoints — 後續增刪改 reference 此 SSOT
+
+任何 future edit:
+- 動 `apps/template/` → 影響兩 scenario 的 seed,測 A4 + B7
+- 動 `scripts/{create-app,setup-netlify-access,check-plugin-installed,...}.mjs` → 測 A4 + B5 + mirror integrity scan
+- 動 `.storybook/main.ts`(DS root)→ 測 A5
+- 動 `template/ds-product-template/.storybook/main.ts` → 測 B4 + M4
+- 動 mirror script `build-published-template-mirror.mjs` → 重跑 4 integrity scans + M2-M5
+- 動 mirror workflow `.yml` → workflow_dispatch dry-run
+
+## 6. Cross-references(其他 file 該 pointer 到本 SSOT,不重述定義)
+
+| File | Reference type |
+|---|---|
+| `.claude/skills/deep-audit-cross-codex/SKILL.md` Phase 0 cwd detection | 已 reference(2-mode based on cwd structure)|
+| `.claude/skills/design-system-audit/SKILL.md` dim 83 | 該砍重述部分,改 pointer here |
+| DS root `CLAUDE.md` task nav row「建產品 / 開新 product app」 | 該 pointer here |
+| `template/ds-product-template/CLAUDE.md` `# Fork-and-go onboarding` 段 | 該 pointer here for Scenario B specifics |
+| `template/README.md` 命名 SSOT 段 | 該 pointer here for 3-layer naming |
+
+## 7. Anti-pattern(永久 ban)
+
+- ❌ Scenario A 文件叫 user `/plugin install`(他有 .claude/ native)
+- ❌ Scenario B 文件假設 user 看得到 `packages/design-system/src/`
+- ❌ Mirror 用 denylist `rm -rf packages/design-system/src`(per codex「太 narrow 會漏 governance/log/planning leak」)
+- ❌ Mirror 漏 CROSS_REPO_TOKEN secret 時 silent succeed(必 fail + 印中文指引)
+- ❌ `apps/template/package.json` DS dep `"beta"` 字串(Gap 3,scenario A workspace resolution vs scenario B npm version 行為不同)
+- ❌ DS root `.storybook/main.ts` 漏 `apps/**` glob(Scenario A 看不到自己 product apps)
+- ❌ Mirror `.storybook/main.ts` 含 `../packages/**` glob(Gap 4,published mirror 不該 leak DS trait grid)
+
+## 8. 對齊上游 canonical
+
+- CLAUDE.md 6 mindset 全 + meta-patterns 31 M-rules + 治理 8-home + 自主執行 7 軸 + 命名 SSOT 3-test(per deep-audit-cross-codex SKILL.md「上游 canonical 全繼承」段 2026-05-29)
+- M17 SSOT 鐵律(本 file 就是 example:single canonical home,其他 file pointer)
+- M19 trigger phrase auto-pipeline + M28 solo-work canonical
+- 命名 SSOT 3 層(per `template/README.md`「命名 SSOT」段)

package/ds-canonical/references/spec-rules.md

@@ -0,0 +1,58 @@
+# Spec 規則 — 詳細展開
+
+`.claude/rules/spec-rules.md` 的詳表。主章留核心原則,本檔放 SSOT 判斷 + 邊界案例 scope default + 禁止清單。
+
+## SSOT 結構規則
+
+跨元件比較由**一個 spec own 完整內容,其他 spec 用一行 pointer 指回**。
+
+**何時需要 SSOT(深度比較)**:
+- 多維度分析(如「與 X 的分界」分多個角度)
+- 情境對照表 > 3 rows
+- 涉及另一元件的內部機制 / 權衡
+
+**何時不需要(本地引用即可)**:
+- 「何時不用」表格一行帶過(「改用 X」+ 原因)— 兩側並存不會漂移
+- 「相關」links section 列出
+- 只描述自己元件的 props / variants / state
+
+**Ownership 判斷順序**:
+1. 通用預設元件 own(Select owns vs RadioGroup、Input owns vs NumberInput — 通用者是 fallback)
+2. 一側 spec 明顯更深 / 另一側薄 wrapper → 深側 own(Tabs owns vs SegmentedControl)
+3. 兩側對等都需要 → 按字母序決定 anchor
+
+**執行規則**:
+- Own 方寫深度 section;被指方寫一行 pointer(**reciprocal 必須存在,不可單向**)
+- Pointer 必須明確指出 anchor spec + section 名稱
+- 本專案目前的 SSOT anchors:
+  - Tabs vs SegmentedControl → `tabs.spec.md`「Tabs 與 SegmentedControl 的分界」
+  - Select vs RadioGroup → `select.spec.md`「與 RadioGroup 的分界」
+  - Checkbox vs Switch → `checkbox.spec.md`「與 Switch 的分界」
+  - HoverCard vs Tooltip → `hover-card.spec.md`「與 Tooltip 的分界」
+  - Row primitives 共用 → `patterns/element-anatomy/item-anatomy.spec.md`
+  - Field Controls 共用 → `components/Field/field-controls.spec.md`
+
+**禁止事項**:
+- ❌ 兩 spec 都寫完整對照(保證漂移)
+- ❌ 建孤立 `xxx-selection.spec.md` / `xxx-comparison.spec.md` 承載比較 — 世界級 DS 都把比較放元件 spec 內
+- ❌ 單向指向(A → B,B 沒指回 A)
+- ❌ Pointer 只說「見 X spec」不說 section 名稱
+
+## 邊界案例覆蓋(Scope 預設 — 減少重複)
+
+適用狀態必須有明確說明 — disabled / loading / empty、dark mode / density、icon-only。不適用則明文「本元件無 X 狀態」,不沉默省略。
+
+**Scope 預設**:
+- **Field 家族**(Input / NumberInput / DatePicker / Select / Combobox / LinkInput / Textarea / Switch / Slider / SegmentedControl / Checkbox / RadioGroup)→ 直接寫「Mode / disabled / readonly 詳 `field-controls.spec.md`」
+- **Dark mode**:元件靠 semantic token 切換(無自訂 palette)→ 「Dark mode 由 semantic token 自動處理(見 `color.spec.md`)」
+- **Density**:元件用 `--field-height-*` / `--layout-space-*` → 「Density 由 token 自動切換」
+- **純 wrapper**(無互動狀態,如 Separator / Skeleton / CircularProgress / ProgressBar)→ 「本元件無互動狀態」一行帶過
+
+元件特有(non-inherit)狀態必展開寫;繼承自 family / token 的行為 pointer 即可。
+
+## spec.md 與 .tsx 職責分離
+
+- spec 只記錄設計原則(「為什麼」「何時用」)— 讓 AI 能舉一反三推導邊緣情況
+- 可程式化規則(具體 token class / pixel 值 / 條件邏輯)寫進 `.tsx`
+- 判斷標準:「這條規則能直接變成 code 嗎?」能 → .tsx;不能、需要人類判斷 → spec
+- 可推導的值用 `calc()` / 公式表達,不硬寫結果(例:divider 內縮 = `(行高 - 文字行高) / 2`)

package/ds-canonical/references/ssot-consultation.md

@@ -0,0 +1,63 @@
+# SSOT 消費 canonical — 完整對照 + 反例
+
+CLAUDE.md `# SSOT 消費 canonical` 的詳表 + 反例。主章留核心 + pointer,本檔放大對照表 + 禁止清單 + tsx 註解模板。
+
+## 視覺決策 → 必查清單(完整)
+
+| 決策 | 必查的 SSOT 家 |
+|------|---------------|
+| **元件選擇**(這該用哪個既有元件?)| `ls packages/design-system/src/components/` + `ls packages/design-system/src/patterns/` + 近親元件 spec |
+| **Token / 值**(padding / gap / height / color)| 對應 `tokens/{name}/spec.md` + `tokens/README.md` |
+| **Padding / spacing**(chrome vs 元件內 vs 精確幾何)| `.claude/references/ui-dev-rules.md`「Padding source 分層規則」+ `tokens/layoutSpace/layoutSpace.spec.md` |
+| **Row / item 結構**(prefix / content / suffix slot)| `patterns/element-anatomy/item-anatomy.spec.md`(Family 1+2 SSOT) |
+| **連續 item list wrapper gap** | `patterns/element-anatomy/item-anatomy.spec.md`「連續 item 貼邊合法性」— 公式:permanent standalone card/pill → 必 gap;permanent flush / transparent → 0 gap。元件專屬 gap 值 + mixed 混合情境決策表查該元件 spec「List wrapper canonical」節 |
+| **視覺容器 breathing**(自建或 override 帶 bg/border/shadow 的 div)| `patterns/element-anatomy/element-anatomy.spec.md`「視覺容器 breathing invariant」— 有視覺邊界容器必有 inner padding。責任在父容器,子元件 w-full responsive 不變 |
+| **Label ↔ Description gap**(2px)| Token `--item-gap-label-desc` + Primitive `<ItemContent>` — 改 token 一處 → 全 DS 同步。Consumer 2 擇 1:(a) token:`mt-[var(--item-gap-label-desc)]`(b) primitive:`<ItemContent label description descriptionTone>`。偏離必 spec 明文 rationale |
+| **Dismiss / inline action / overflow menu**| `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss 按鈕 canonical」+「Inline Action 設計規格」+「常用 icon canonical」 |
+| **按鈕排列 / 群組 / 分隔**| `patterns/action-bar/action-bar.spec.md` |
+| **Header 高度 / chrome padding**| `tokens/uiSize/uiSize.spec.md`(`--chrome-header-height`)+ `tokens/layoutSpace/layoutSpace.spec.md` |
+| **Chrome header 選型**(fixed-h vs padding-based)| `tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」— decision tree + 8 家世界級對照 + checklist |
+| **Header 跨家族視覺契約**(border / padding / withTabs / dismiss size 連動)| `patterns/header-canonical/header-canonical.spec.md` — SSOT for chrome + overlay header 兩家族;含 withTabs 6 lockstep rules(W1 border auto-suppress / W2 padding align / W3 tabs size 對應 / W4 flush stack / W5 md future tier / W6 default sm)|
+| **Overlay chrome dismiss / unbounded button**| `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical v5」 |
+| **Overlay title size**(modal 16 vs non-modal 14)| `patterns/overlay-surface/overlay-surface.spec.md`「Overlay title typography canonical」 |
+| **Form field gap**| `components/Field/field.spec.md` +「layoutSpace 規則 3:跟 block 相鄰 = tight,inline ↔ inline = loose」 |
+| **Icon 選擇 / 尺寸**| `.claude/rules/ui-development.md`「元件 Props 命名」「Icon canonical」+ `ui-dev-rules.md`「Icon size 來源分層規則」 |
+| **浮層 header / body / footer**| `patterns/overlay-surface/overlay-surface.spec.md` |
+| **Scrollbar / 滾動**| `components/ScrollArea/scroll-area.spec.md` +「horizontal-overflow pattern」 |
+| **Variant / prop 命名**| 既有元件 `variant=` 值 grep + `# 命名與語言一致性`「命名必過三重 test」 |
+| **State 視覺**(selected / disabled / hover)| `patterns/element-anatomy/item-anatomy.spec.md`「選擇 / 狀態視覺規則」 |
+
+## 強制 Checklist — 新 tsx 檔 top-of-file 註解
+
+新元件 / 新 feature 的 tsx 開頭**必須**有註解段落:
+
+```tsx
+/**
+ * {Component} — {定位一句話}
+ *
+ * ── 定位 ──
+ * {...}
+ *
+ * ── 實作基礎 ──
+ * 消費:{List components / primitives used}
+ * 對應 pattern:{patterns/xxx}
+ *
+ * ── 消費的 SSOT ──
+ * - components: [Button, Input, ItemInlineAction, ...]
+ * - patterns: [item-anatomy, action-bar, overlay-surface]
+ * - tokens: [--layout-space-loose, --chrome-header-height, --field-height-md]
+ * - spec refs: {近親 spec 清單}
+ */
+```
+
+Hook `check_ssot_consultation.sh`(retired;改靠 mindset #2 + `check_canonical_propagation.sh`)(原 Write 新 tsx 到 `packages/design-system/src/components/` 或 `src/explorations/` → 若檔內無上述註解區 → warn 要求補齊)。
+
+## 禁止:隱性自創
+
+下列行為等同自創(就算沒宣告新命名):
+- 自寫 `h-14` / `h-12` 等 chrome 高度(應用 `--chrome-header-height` token)
+- 自寫 `gap-3` 當 toolbar 按鈕群 gap(應查 `patterns/action-bar` canonical)
+- 自寫 `<button aria-label="Close"><X /></button>` 作 dismiss(應用 `ItemInlineAction`)
+- 自寫 Row `<div><Icon /><span>label</span><Button /></div>`(應用 `<MenuItem>` + slot)
+- 自訂 Input `variant="custom-name"` 未先 grep 既有 variant 值
+- 在 Toolbar 用 `<input className="bg-transparent border-0 ...">`(應用 `<Input variant="bare">` 若既有;無 → Ambiguity Protocol)

package/ds-canonical/references/ssot-index.md

@@ -0,0 +1,40 @@
+# SSOT Index — High-risk interface ownership map
+
+**Purpose**:per codex round 5 (e) — 設計提案前必查本 index 找 owner,再 grep spec verify。
+避免 round 1-4 反覆「沒查就提案 → 提錯 owner → user 糾 → 再來」的 loop。
+
+**Usage**:
+1. 動視覺 / 結構前 → grep 本 file 找該 interface 是否列管
+2. 命中 → 跳 owner spec 查 canonical sentence + 看 conflicting code 嗎?
+3. 沒命中 → grep `*.spec.md` 找 anchor,**找到後加進本 index**(防下次再漏)
+
+## High-risk interfaces(active divergence / past trap)
+
+| Interface | Owner spec | Canonical sentence | Drift status | Last divergence event |
+|---|---|---|---|---|
+| **DataTable body cell internal indicator**(display endAction / clear / edit indicator)| `data-table.spec.md`「Body cell internal」row + `inline-action.spec.md`「DataTable body cell internal」row | 「Body cell internal = Field family endAction(自動繼承)」「Field display 元件已對齊」 | ✅ aligned:2026-05-09 D-path retired — `getEditIndicator(colType)` parallel system 移除,indicator authority 移交 Field naked-display `showDisplayEndIcon` opt-in,cellEl 不再 render parallel indicator(見 data-table.tsx「D-path retired」註解)| 2026-05-08 round 5 → 2026-05-09 resolved |
+| **Field naked variant state ring**(hover / focus / open / error)| `field-wrapper.tsx` cva compoundVariants(v13.3)+ `field.spec.md`「focus dominates」段 | 「SSOT 在 field-wrapper.tsx 三 compoundVariant — 改一處全 control + cell + variant 跟動」 | ✅ aligned(2026-05-08 D path canary 違反後 revert)| 2026-05-08 round 4(D path canary 違反 SSOT,已 revert `f0faab9`)|
+| **Row prefix/suffix slot**(`<ItemPrefix>` / `<ItemSuffix>`)| `patterns/element-anatomy/item-anatomy.spec.md:175+190` | 「row prefix/suffix slot 必走 patterns/element-anatomy L1 primitive」「`h-[1lh] shrink-0 flex items-center` 普世正確」 | ✅ aligned(hook `check_pattern_invariants.sh` C.4 enforce)| — |
+| **Inline action gap**(ItemInlineAction sibling spacing)| `patterns/element-anatomy/inline-action.spec.md`「多個 inline action 間距」段 | 「inline-action 跟 sibling gap 必 = `gap-2`(8px)」 | ✅ aligned(hook C.2 enforce)| — |
+| **Drag visual**(drop indicator / drag overlay)| `lib/drag-visual.ts`(2026-05-06 v14.5)+ `tree-view.spec.md:265` | 「TreeView 是 DS 內最早 codified 的 drag canonical,DataTable row drag + column reorder 都 inherit via drag-visual.ts SSOT module」 | ✅ aligned | — |
+| **Color tokens**(primitive vs semantic)| `tokens/color/color.spec.md`(架構流派定位)+ `tokens/color/semantic.css` | 「禁 primitive 色名作 utility,用 semantic alias」 | ✅ aligned(hook D.3 enforce)| — |
+| **Layout space**(region/element + 親疏三級)| `tokens/layoutSpace/layoutSpace.spec.md` v6(原 memory `feedback_layout_v6_canonical.md` 已 retire)| 「region/element + bounded/unbounded + 親疏三級」 | ✅ aligned(2026-05-01 flush variant retire)| 2026-05-01 |
+| **DataTable scroll**(3-region synced + cross-OS scrollbar)| `data-table.spec.md:245-251` | 「center body 用 native overflow-x-auto(非 ScrollArea),pinned column 三 region 同步」 | ✅ aligned(v15.13 interim CSS parity for Windows Bug H,deferred ScrollArea full migration)| 2026-04-30 / 2026-05-07 |
+| **Cell display vs edit content position**(picker offset)| `field.spec.md`「Layout Family 4」段 + `data-table.spec.md`「Body cell internal」row | 「Field control display + edit 共用同 wrapper geometry」 | ⚠ partial:DataTable cell 場景已對齊(D-path `showDisplayEndIcon` opt-in 走 Field naked-display);standalone `mode="display"` 仍 bare-span(documented deferral,見 select.tsx 檔頭 `@renderer-symmetry-allow`)| 2026-05-07~08 round 1-5 → 2026-05-09 D-path 部分解決 |
+| **Field state machine focus dominates**(v13.3)| `field-wrapper.tsx` cva compoundVariants + `field.spec.md`「focus dominates」段 + `check_field_family_invariants.sh` A.3 | 「focus dominates everything;naked 不寫平行 outline ring」 | ✅ aligned;hook A.3 enforce | 2026-05-06 v9-v13.3 5 round refinement |
+| **Solo dev workflow**(1 chat = 1 branch / Netlify gate / squash merge)| `feedback_solo_dev_workflow.md` + CLAUDE.md「Git solo-work canonical」 | 「1 chat = 1 working branch;Netlify preview = user gate;『push / OK』trigger 才 merge main」 | ✅ aligned(M28 + hook `check_solo_workflow.sh`)| 2026-05-08 M28 codify |
+| **Wrapper-vs-primitive schema unify**(SelectOption / MenuItemProps 等)| `SelectMenu/select-menu.tsx` SelectMenuOption + `Combobox/combobox.tsx` extends + `PeoplePicker/people-picker.tsx` extends | 「wrapper API schema 必 `extends primitive`,wrapper 內部 mapping 必 forward 全 primitive surface field(M30)」 | ✅ aligned(2026-05-10 Round 1 commit `561945b` Combobox extends + forward 全 field;PeoplePicker 對齊 + hook `check_wrapper_primitive_schema_drift.sh` BLOCKER)| 2026-05-10 M30 codify |
+
+## How to maintain
+
+- 新 interface 第一次 surface → 加進本 index
+- 新 divergence 發現 → 加 row + 標 ⚠ DRIFT
+- Drift 解決 → 改 ✅ aligned
+- 重大 round 結束 → 跑 audit Dim 38 反 grep verify
+
+## 與 hook 關係
+
+- `check_ds_anchor_preflight.sh`(live,soft warn)— 偵測編 Field / DataTable / patterns code 時 stderr 提醒「先 grep ssot-index.md」
+- `check_field_family_invariants.sh` A.3 — 機械化 enforce v13.3 SSOT
+- `check_pattern_invariants.sh` C.4 — 機械化 enforce row slot SSOT
+- `check_canonical_propagation.sh` E.2 — 機械化 enforce L3 primitive import

package/ds-canonical/references/story-baseline-registry.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "./story-baseline-registry.schema.json",
+  "_meta": {
+    "purpose": "Anti-drift registry for stories wrap既有 primitive(Sidebar / ChromeHeader / DataTable / Dialog / Sheet / Popover)— machine-readable canonical archetype。Hook `check_story_invariants.sh R8` reads this(not grep spec.md / not憑 Claude judgment)to enforce nearest same-purpose canonical usage(per codex Layer B D4 2026-05-20)。新增 primitive entry 必先寫 baseline + helper list + antiPatterns regex + variantRules。",
+    "owner": ".claude/references/story-baseline-registry.json",
+    "consumed_by": [
+      ".claude/hooks/check_story_invariants.sh#R8(story_archetype_registry)",
+      ".claude/skills/story-writing/SKILL.md#Phase-0.0(load registry + read baseline + produce diff table)"
+    ],
+    "rollout": "ship as warn mode first;確認 zero existing violation → 升 P0 BLOCKER"
+  },
+  "components": {
+    "Sidebar": {
+      "baseline": "packages/design-system/src/components/Sidebar/sidebar.stories.tsx#IconCollapse",
+      "requiredHelpers": [
+        "WorkspaceBrand",
+        "MAIN_NAV",
+        "SidebarHeader",
+        "SidebarFooter"
+      ],
+      "antiPatterns": [
+        {
+          "id": "sidebar-header-simplified-span",
+          "regex": "<SidebarHeader[^>]*>[[:space:]]*<span",
+          "severity": "block",
+          "rationale": "SidebarHeader 必 wrap WorkspaceBrand-like ItemAvatar block(per sidebar.stories#IconCollapse baseline);simplified <span> mock = drift"
+        },
+        {
+          "id": "sidebar-menu-button-inline-icon",
+          "regex": "<SidebarMenuButton[^>]*>[^<]*<[A-Z][a-zA-Z]+[[:space:]]+className=\"size-",
+          "severity": "block",
+          "rationale": "SidebarMenuButton 必用 startIcon prop + tooltip prop;children inline icon = drift"
+        },
+        {
+          "id": "sidebar-header-subtitle-second-line",
+          "regex": "<SidebarHeader[^>]*>[[:space:]]*<div[^>]*flex-col",
+          "severity": "block",
+          "rationale": "SidebarHeader brand 必單行(Fixed-h chrome 不可成長,sidebar.spec.md SidebarHeader 段 2026-06-12 明文)。flex-col 直接子層 = logo name 下加副標的結構簽名 — shadcn TeamSwitcher demo prior 滲漏;plan/org 資訊歸 workspace switcher dropdown row,非常駐 header"
+        },
+        {
+          "id": "sidebar-footer-two-line",
+          "regex": "<SidebarFooter[^>]*>.{0,400}(text-xs|leading-tight)",
+          "severity": "block",
+          "rationale": "SidebarFooter user 區必單行(名字 only;職稱/email 等身份資訊歸 ItemAvatar hoverCard 的 ProfileCard,sidebar.stories.tsx UserFooter canonical)。shadcn nav-user 的「name + email text-xs 兩行」是強 LLM 先驗,且 text-xs 違反 chrome typography canonical(sidebar.spec『chrome 內 text 一律 text-body-lg』);400 字元窗限制 greediness"
+        }
+      ]
+    },
+    "DataTable": {
+      "baseline": "packages/design-system/src/components/DataTable/data-table.stories.tsx#WithBulkActions",
+      "toolbar": {
+        "requiredHelpers": [
+          "Popover",
+          "PopoverTrigger",
+          "PopoverContent",
+          "Input"
+        ],
+        "filterPanel": "DataTableFilterPanel",
+        "sortManager": "DataTableSortManager",
+        "buttonCanonical": {
+          "variant": "text",
+          "size": "sm",
+          "iconOnly": true,
+          "pressed": "required(state expression)",
+          "rationale": "per codex D2 verdict 2026-05-20 + action-bar.spec.md narrow scope:dense always-visible toolbar = low visual weight + pressed/chips/badges 顯示 state;tertiary 只用 standalone/labeled context"
+        }
+      },
+      "antiPatterns": [
+        {
+          "id": "datatable-toolbar-tertiary-filter-sort",
+          "regex": "startIcon=\\{(Filter|ArrowUpDown)\\}[^>]*variant=\"tertiary\"|variant=\"tertiary\"[^>]*startIcon=\\{(Filter|ArrowUpDown)\\}",
+          "severity": "block",
+          "rationale": "DataTable toolbar filter/sort 必 variant=text(per data-table.stories#WithBulkActions L998 canonical)"
+        },
+        {
+          "id": "datatable-toolbar-button-with-label",
+          "regex": "startIcon=\\{(Filter|ArrowUpDown)\\}[^>]*>[^<]+(篩選|排序|Filter|Sort)[^<]*</Button>",
+          "severity": "block",
+          "rationale": "DataTable toolbar 必 iconOnly(per WithBulkActions L998 canonical),不掛 label"
+        },
+        {
+          "id": "datatable-toolbar-no-popover-wrap",
+          "regex": "startIcon=\\{(Filter|ArrowUpDown)\\}(?![\\s\\S]*?(DataTableFilterPanel|DataTableSortManager))",
+          "severity": "warn",
+          "rationale": "DataTable toolbar filter/sort button 必包在 Popover 內,內含真 DataTableFilterPanel / DataTableSortManager primitive"
+        }
+      ]
+    },
+    "ChromeHeader": {
+      "baseline": "packages/design-system/src/components/Sidebar/sidebar.stories.tsx#IconCollapse (PageContent helper)",
+      "requiredStructure": "SidebarTrigger + h1.text-body-lg.font-medium 緊鄰 gap-2",
+      "antiPatterns": [
+        {
+          "id": "chromeheader-span-flex-1",
+          "regex": "<ChromeHeader[^>]*>.{0,160}<span[[:space:]]+className=\"[^\"]*flex-1[^\"]*\">",
+          "severity": "block",
+          "rationale": "ChromeHeader title 該用 <h1 className=\"text-body-lg font-medium\"> 緊鄰 SidebarTrigger,不該用 <span flex-1> 撐空間造成 toggle + title 巨大間距"
+        },
+        {
+          "id": "chromeheader-subtitle-second-line",
+          "regex": "<(ChromeHeader|PageHeader)[^>]*>[[:space:]]*<div[^>]*flex-col",
+          "severity": "block",
+          "rationale": "Chrome 家族永遠 single-row(header-canonical.spec.md:47,剛性 --chrome-header-height);title 下加副標/description = LLM 先驗回填(Polaris Page subtitle / Tailwind UI page heading 先驗),頁面說明文字歸 content 區,非 chrome。flex-col 直接子層 = 兩行結構簽名"
+        }
+      ]
+    }
+  }
+}

package/ds-canonical/references/structural-token-retention.md

@@ -0,0 +1,42 @@
+# 結構性保留 token canonical(audit Dim 48 SSOT,2026-05-17 codified)
+
+某些 token 看起來「0 consumer」但屬**結構性保留**,不該 retire。**Sub-agent 跑 audit Dim 48 抓 0-consumer candidate 時必先過此 table,屬下列 6 類則 retract finding(不列為 violation)**。
+
+## 6 類結構性保留(對齊 Radix Color / Atlassian @atlaskit/tokens / Polaris polaris-tokens 三家共識)
+
+| 類別 | Examples | 保留 rationale |
+|---|---|---|
+| **1. Radix-style palette completeness** | `--color-{blue,deep-orange,orange,amber,yellow,lime,green,turquoise,indigo,purple,magenta}-{3,4,5,8,9,10}` / `--white-a{12,15,25,45,65,85}` / `--color-red-{1..10}`(red palette 因 semantic 重映射 deep-orange 而不直接消費)| Radix Color idiom 必 12 步階完整,即使目前只消費 step-{1,2,6,7} 給 Tag/Avatar,中間步階保留供未來 hue scale 擴充 / hue calibration 對照。Retire = 破壞 palette 完整契約,新加 hue 時需重新訂全套 |
+| **2. Forward-looking consumer reservation** | `--brand` / `--color-brand` | 預留給 consumer-layer(`src/app` / product UI)消費的品牌色 token。DS 本身不消費,跟 `--primary`(DS UI accent)分層。Retire = 未來產品做品牌頁時要重補 token + spec |
+| **3. Tailwind bridge alias to semantic state SOP** | `--color-status-{online,busy,away,offline}` / `--color-inverse-neutral-{hover,active}` | `@theme inline` bridge 讓 `bg-status-online` 類 utility 可用,即使現有 code 走 `var(--status-online)` direct(NameCard.tsx / Avatar.tsx / Tag.tsx 實際消費 underlying token 非 alias)。Bridge 是 future-proof Tailwind class consumption,retire = 限縮使用方式。（2026-06-04:原 `--color-warning-foreground` 已移除——改名 `--on-emphasis-dark`,white/dark on-fill 配對見 color.spec.md）|
+| **4. State SOP 5 件套** | `--info-active / --success-active / --warning-active / --primary-text` 等 | semantic state 5 件套(base / hover / active / subtle / text)結構完整性,即使現有 active variant 無 consumer,保留供未來互動 state 擴充 |
+| **5. Type scale completeness** | `--font-h1-size` / `--font-h4-size` 等 typography utility | Type scale 12-tier completeness,即使現有 production 只用 h2/h3/h5,h1/h4/h6 預留供 marketing / hero / drawer title 等場景 |
+| **6. Elevation dark-mode pair** | `--elevation-100-hover / --elevation-200-hover` | `primitives.css:236,238,419,421` light + dark 雙模式各自定義 → 結構性 dual-tier,retire 會破 dark mode visual contract |
+
+## Retire criteria 真實 strict(只有以下才 retire)
+
+- 真實 0 consumer + **0 forward-looking reservation** + **0 dark-mode pair** + **0 palette completeness role**
+- 對齊 Radix Color / Atlassian `@atlaskit/tokens` / Polaris polaris-tokens 三家 retire 政策共識
+
+## Sub-agent 強制 triple-verify before propose retire
+
+對每 candidate retire token,sub-agent 必 verify 3 layer:
+
+1. **`grep -rn var(--TOKEN_NAME)` DS-wide**(含 `packages/design-system/src/**` + `src/app/**` + `src/explorations/**`)— 抓 direct `var()` consumption
+2. **`grep -rn "TOKEN_NAME"` 排除 css/spec.md 定義 + template literal usage**(eg. `\`h-table-row-${size}\``)— 抓動態 utility class generation
+3. **Cross-check 上 6 類**:屬任一 → retract finding,**不列 retire candidate**
+
+**任一 layer 顯示「有 consumer / 屬結構保留」→ 從 retire report 中拿掉**(不要送 user 拍板浪費時間)。
+
+## Audit Dim 48 false-positive 經驗(2026-05-17,user 抓教訓)
+
+Sub-agent 用 narrow grep(只看 utility class hit,沒看 `var()` direct + template literal + dark mode override + forward-looking)抓 58 個 retire candidate;Layer A own re-verify 後 100% 為 false positive(全是結構性保留)。
+
+User verbatim 2026-05-17:「每次抓出的問題你他媽要給我基於我們所有的檔案包括設計原則去再三確認到底是不是問題,避免明明就不是問題卻一直要我決策浪費我的時間」。
+
+本檔 codify 後類似 audit 跑時自動辨識結構性保留 token,不再誤判。
+
+## 引用
+
+- `tokens/color/color.spec.md`「結構性保留 token canonical」(pointer 段)
+- `.claude/skills/design-system-audit/SKILL.md` Dim 48(sub-agent prompt 必 cite 本檔)

package/ds-canonical/references/tailwind-gotchas.md

@@ -0,0 +1,87 @@
+# Tailwind 使用完整陷阱對照(從 CLAUDE.md 拆出)
+
+`.claude/rules/ui-development.md`「Tailwind 5 條核心」段保留最精要 rules 和一行 bug anchor;完整範例、完整禁止清單、每條 bug 的詳細歷史在本檔。
+
+---
+
+## Tailwind v4 任意值:CSS variable 必須用 `var()` 包覆
+
+**必須寫 `w-[var(--foo)]`,不能寫 `w-[--foo]`**。Tailwind v4 對任意值裡的 CSS variable 處理改了——舊的 `[--foo]` shorthand **不會自動包 `var()`**,會被當成 custom property declaration,整個 class **靜默失效**(不報錯,但完全沒效果)。
+
+**曾經發生的 bug**:Sidebar 從 shadcn 複製的 `w-[--sidebar-width]` 在 8 個位置寬度全失效,sidebar 寬度變成 content fallback 導致主內容被蓋住。
+
+```tsx
+// ❌ 錯(v4 失效)
+<div className="w-[--sidebar-width] min-w-[--sidebar-width-min]" />
+
+// ✅ 對
+<div className="w-[var(--sidebar-width)] min-w-[var(--sidebar-width-min)]" />
+```
+
+**自我檢查**:若 CSS var 相關寬高看起來怪怪的,先 `grep '\[--[a-z]'` 在 src 裡找有沒有漏網的 shorthand 語法。
+
+---
+
+## 圓角對應表
+
+| Utility class   | 值                         |
+|----------------|---------------------------|
+| `rounded-md`   | 4px(--radius-md)    |
+| `rounded-lg`   | 8px(--radius-lg)    |
+| `rounded-full` | 9999px(--radius-full)|
+
+---
+
+## tailwind-merge 自訂 utility 註冊(技術陷阱)
+
+新增任何 `text-*`、`bg-*`、`border-*`、`ring-*` 自訂 utility 後,**必須到 `lib/utils.ts` 顯式註冊到正確的 group**(font-size / text-color 等)。否則 tailwind-merge 會用 heuristic 猜分組,把不衝突的 class 誤判為衝突並 strip 掉。
+
+**曾發生的 bug**:`text-body`(font-size)和 `text-fg-secondary`(color)被誤判同組,description 失去 font-size。
+
+**診斷法**:`cn()` 後某個 class 消失 → 99% 是 tailwind-merge 誤判 → 去 `lib/utils.ts` 註冊。
+**逃生艙**:inline style + CSS variable(`style={{ fontSize: 'var(--font-body-size)' }}`)。
+
+---
+
+## 何時可以 / 不可以用 Tailwind utility
+
+### 核可清單(我們的元件 code 可以直接用)
+
+| 類別 | 允許 utility | 備註 |
+|------|-------------|------|
+| **Layout / Flex / Grid** | `flex`, `grid`, `items-*`, `justify-*`, `gap-*`, `p-*`, `m-*`, `w-*`, `h-*`, `min-*`, `max-*` 等 Tailwind 預設 | spacing scale `p-4` / `gap-2` 等都 OK |
+| **Display / Position** | `block`, `hidden`, `absolute`, `relative`, `z-*` | |
+| **我們 DS 自訂 token utility** | `bg-surface-raised`, `text-foreground`, `text-fg-secondary`, `text-fg-muted`, `border-border`, `border-divider`, `text-body`, `text-caption`, `h-field-*`, `rounded-md` 等 | 所有 semantic token 對應的 utility |
+| **CSS variable 任意值** | `shadow-[var(--elevation-200)]`, `h-[var(--field-height-md)]` 等 | **必須 `var()` 包覆**,不能 `[--foo]` shorthand |
+
+### 禁止清單
+
+| 類別 | 為什麼禁止 | 改用 |
+|------|----------|------|
+| `shadow-sm/md/lg/xl/2xl` | 繞過 elevation token 系統,沒跟 dark mode 調整聯動 | 用 `shadow-[var(--elevation-N)]` 其中 N ∈ `{100, 200}`(+`-hover` 變體;per elevation.spec.md tier;2026-05-31 修:無 300)|
+| 硬寫色值 `#xxx`, `rgb(...)`, `bg-red-500` | 繞過 semantic token,dark mode / brand swap 會斷 | 對應 semantic token |
+| Tailwind 預設 typography `text-xs/sm/base/lg` | 我們有自己的 `text-caption/body/body-lg/h1/h2` 系統 | 用我們的 typography token |
+| 硬寫 px 值 `w-[48px]` 當有 token | 失去 token 關聯,改值時零散處要一起改 | 對應 token 或 calc() |
+
+---
+
+## shadcn compat aliases — 不給我們元件用
+
+`semantic.css` 的「shadcn Compat Aliases」段(`--popover`, `--popover-foreground`, `--muted-foreground`, `--accent`, `--accent-foreground` 等)**只是 `npx shadcn add X` 複製貼上時的安全網**,讓 shadcn 原生 className 不會因找不到 CSS variable 而 fallback。
+
+**我們自己 design-system 的元件 code 禁止直接使用這些 alias**:
+
+| 禁止(shadcn alias) | 必用(我們的 token) |
+|--------------------|--------------------|
+| `bg-popover` | `bg-surface-raised` |
+| `text-popover-foreground` | `text-foreground` |
+| `text-muted-foreground` | `text-fg-muted` |
+| `bg-accent` | `bg-neutral-hover` |
+| `text-accent-foreground` | `text-foreground` |
+| `bg-muted` | 這個是我們核可的 token(neutral-2 subtle bg),**不是** shadcn alias,OK 用 |
+
+**原則**:shadcn 原生 utility 只在 shadcn 自動生成的檔案**暫時**存在(作遷移緩衝);任何人類編輯或新增的元件 code 都必須用我們的 direct token。**用 shadcn alias = 設計 bug**,優先改為 direct token。
+
+**為什麼**:shadcn alias 是「臨時橋」讓 shadcn add 不炸;我們有自己 design opinion 後直接用 own token,保持 DS 單一真實來源。允許 shadcn alias 進我們的 code = 慢慢讓 shadcn 命名污染回流,DS 自主性退化。
+
+**曾經發生的 bug**:Popover.tsx / Command.tsx 保留 shadcn template 的 `bg-popover`, `text-popover-foreground`, `text-muted-foreground`, `bg-accent`, `text-accent-foreground` 多處,2026-04-18 session 時 audit 發現統一遷移為 direct token(`bg-surface-raised` / `text-foreground` / `text-fg-muted` / `bg-neutral-hover`)。hook `lib/_token_hygiene.sh`(由 `post_edit_dispatcher.sh` source)現已自動攔截此類回流(Check 1 shadcn alias)。