@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/ds-canonical/references/principle-dim-map.json

@@ -0,0 +1,515 @@
+{
+  "_meta": {
+    "purpose": "Explicit semantic mapping: principle (M-rule / trait / hook) → audit dim cover",
+    "ssot": ".claude/memory/feedback_audit_preflight_全盤查.md + design-system-audit/SKILL.md",
+    "updated": "2026-05-18",
+    "version": "1.0",
+    "_principle": "禁 heuristic match;每原則必 explicit dim list。新原則加入必同 commit 加 entry,違 = hook BLOCK"
+  },
+  "mRules": {
+    "M1": {
+      "name": "SSOT consumption 視覺決策前必查",
+      "dims": [],
+      "note": "governance-only;審 spec 寫 SSOT 段落 by ssot-consultation.md;無獨立 audit dim"
+    },
+    "M2": {
+      "name": "3rd-party DOM verify",
+      "dims": [],
+      "note": "runtime discipline;無 mechanical dim"
+    },
+    "M3": {
+      "name": "Portal 逃逸 subtree theme",
+      "dims": [],
+      "note": "historical-bugs only;考慮加 dim Group N+ Portal-theme check"
+    },
+    "M4": {
+      "name": "_Group fieldCtx 隔離",
+      "dims": [
+        34
+      ],
+      "note": "Dim 34 disabled state precedence 隱含驗 group context"
+    },
+    "M5": {
+      "name": "State 疊加 spec coverage",
+      "dims": [
+        7
+      ],
+      "note": "Spec Rule B 邊界案例"
+    },
+    "M6": {
+      "name": "Stakeholder gate 強制進階稽核",
+      "dims": [
+        11,
+        23
+      ],
+      "note": "Tier-1 gate via component-quality-gate skill chain"
+    },
+    "M7": {
+      "name": "新 skill cross-check 既有 Meta-Principle",
+      "dims": [],
+      "note": "governance-only"
+    },
+    "M8": {
+      "name": "Cross-component canonical 必 world-class benchmark",
+      "dims": [
+        23
+      ],
+      "note": "Dim 23 benchmark cite"
+    },
+    "M9": {
+      "name": "Predicate 4 題自測",
+      "dims": [
+        22
+      ],
+      "note": "D6e predicate audit protocol"
+    },
+    "M10": {
+      "name": "Proactive exhaustive scan",
+      "dims": [],
+      "note": "由 /scan-similar-bugs skill cover + Phase 0.5 preflight DS-wide enforce"
+    },
+    "M11": {
+      "name": "7 題 interactive state walk",
+      "dims": [],
+      "note": "runtime discipline pre-present;無 audit dim"
+    },
+    "M12": {
+      "name": "Binary strict rule benchmark + invariant test",
+      "dims": [
+        23
+      ],
+      "note": "Dim 23 benchmark + propose-options 4-Q"
+    },
+    "M13": {
+      "name": "User 第 2 次提 → 截圖 verify",
+      "dims": [],
+      "note": "runtime discipline"
+    },
+    "M14": {
+      "name": "對話結論 AUTO integrate 5-layer",
+      "dims": [],
+      "note": "governance pipeline;由 ensure-canonical / codify-principle skill cover"
+    },
+    "M15": {
+      "name": "Product UI flow visual-audit coverable",
+      "dims": [],
+      "note": "考慮加 dim 47:檢查 stakeholder-facing OpenSnapshot story 存在"
+    },
+    "M16": {
+      "name": "Standalone gap canonical",
+      "dims": [
+        21
+      ],
+      "note": "Group H 連續 item list gap"
+    },
+    "M17": {
+      "name": "SSOT 可傳播 (token / primitive / utility)",
+      "dims": [
+        32
+      ],
+      "note": "Dim 32 filter operator + 通用 SSOT 消費隱含全 audit 中"
+    },
+    "M18": {
+      "name": "Propose-time 4-Q gate",
+      "dims": [],
+      "note": "propose-options skill;runtime discipline"
+    },
+    "M19": {
+      "name": "Trigger phrase auto-pipeline",
+      "dims": [],
+      "note": "ensure-canonical skill"
+    },
+    "M20": {
+      "name": "AI 自問 best-practice + 自動 self-improve",
+      "dims": [],
+      "note": "stop hook self-audit;runtime discipline"
+    },
+    "M21": {
+      "name": "新元件抽象前 prop variant test",
+      "dims": [
+        33
+      ],
+      "note": "Dim 33(b) premature abstraction"
+    },
+    "M22": {
+      "name": "Benchmark claim 必 inline cite",
+      "dims": [
+        23,
+        33
+      ],
+      "note": "Dim 23 + Dim 33(d) benchmark cite check"
+    },
+    "M23": {
+      "name": "DS-internal canonical 優先 external",
+      "dims": [
+        33
+      ],
+      "note": "Dim 33(e) DS-first"
+    },
+    "M24": {
+      "name": "Disabled > muted state precedence",
+      "dims": [
+        34
+      ],
+      "note": "Group N Dim 34"
+    },
+    "M25": {
+      "name": "Overlay scroll chain invariant",
+      "dims": [
+        35
+      ],
+      "note": "Group N Dim 35"
+    },
+    "M26": {
+      "name": "Behavior decision propose 前 WebFetch 3 source",
+      "dims": [],
+      "note": "runtime discipline;補強建議加 dim 48 cite freshness check"
+    },
+    "M28": {
+      "name": "Solo git ops grep canonical",
+      "dims": [],
+      "note": "governance-only;hook check_solo_workflow"
+    },
+    "M29": {
+      "name": "DS anchor preflight grep spec.md",
+      "dims": [],
+      "note": "runtime discipline;codex-collab Step 0.1"
+    },
+    "M30": {
+      "name": "Wrapper schema extends primitive",
+      "dims": [],
+      "note": "hook check_wrapper_primitive_schema_drift;考慮加 dim 49 DS-wide scan"
+    },
+    "M31": {
+      "name": "Codex collab 5-step canonical",
+      "dims": [],
+      "note": "codex-collab skill + hook;runtime"
+    },
+    "M32": {
+      "name": "Audit script pixel-quantified",
+      "dims": [],
+      "note": "hook check_pixel_quantified_audit;對 audit scripts 自身,不對 component"
+    },
+    "_retired": {
+      "M27": "2026-05-15 → folded into M23(c)(framework prop name conflict child)",
+      "M33": "2026-05-22 → folded into M20(AI self-correction sub-rule)",
+      "M34": "2026-05-22 → folded into M7(rule-authoring hygiene sub-rule)",
+      "M35": "2026-05-22 → folded into M23(d)(nearest same-purpose canonical sub-rule)"
+    }
+  },
+  "traits": {
+    "isInternal": {
+      "dims": [
+        44
+      ],
+      "note": "Group O Dim 44"
+    },
+    "isOverlay": {
+      "dims": [
+        31
+      ],
+      "note": "Group M Dim 31 overlay body"
+    },
+    "hasSizes": {
+      "dims": [
+        13,
+        23,
+        29,
+        45
+      ],
+      "note": "anatomy SizeMatrix + trait-based + mechanical output"
+    },
+    "hasVariants": {
+      "dims": [
+        13,
+        23,
+        29,
+        45
+      ],
+      "note": "anatomy ColorMatrix + trait-based"
+    },
+    "hasInteractiveStates": {
+      "dims": [
+        13,
+        29
+      ],
+      "note": "anatomy StateBehavior"
+    },
+    "isStructural": {
+      "dims": [],
+      "note": "考慮加 dim 50 structural-element scan"
+    },
+    "isInputLike": {
+      "dims": [
+        26,
+        34,
+        37
+      ],
+      "note": "Dim 26 dual-mode + Field state machine"
+    },
+    "isMatrixHeavy": {
+      "dims": [
+        13
+      ],
+      "note": "anatomy matrix completeness"
+    },
+    "isSelectionSingle": {
+      "dims": [
+        26,
+        34
+      ],
+      "note": "Field dual-mode"
+    },
+    "isSelectionMulti": {
+      "dims": [
+        26,
+        32,
+        34
+      ],
+      "note": "Field + filter SSOT"
+    },
+    "hasActions": {
+      "dims": [
+        38
+      ],
+      "note": "Dim 38 inline-action gap"
+    }
+  },
+  "hooks": {
+    "app_shell_primary_header_consistency": {
+      "dims": [
+        56
+      ],
+      "note": "Phase 5 AppShell global header consistency(2026-05-23 entry add per audit-preflight gap)"
+    },
+    "benchmark_citation": {
+      "dims": [
+        23
+      ]
+    },
+    "canonical_propagation": {
+      "dims": [
+        5,
+        16,
+        30
+      ],
+      "note": "1 hook 3 invariant"
+    },
+    "codex_collab_5step": {
+      "dims": [],
+      "note": "governance/runtime only,not visible audit"
+    },
+    "datatable_invariants": {
+      "dims": [],
+      "note": "考慮加 dim 51 DataTable canonical full-scan"
+    },
+    "field_controls_contracts": {
+      "dims": [
+        26,
+        34,
+        37
+      ]
+    },
+    "field_family_invariants": {
+      "dims": [
+        34,
+        35,
+        36,
+        37
+      ]
+    },
+    "file_size_budget": {
+      "dims": [],
+      "note": "governance-only"
+    },
+    "naming_and_abstraction": {
+      "dims": [
+        14,
+        17,
+        33
+      ]
+    },
+    "opacity_token_usage": {
+      "dims": [
+        5
+      ]
+    },
+    "pattern_invariants": {
+      "dims": [
+        22,
+        35,
+        38,
+        39
+      ]
+    },
+    "peoplepicker_ssot_drift": {
+      "dims": [
+        37
+      ],
+      "note": "Dim 37 Field state machine SSOT 涵蓋 PeoplePicker trigger render / placeholder / overflow 等 SSOT-bearing API 屬 Field family scope;hook 為 write-time pre-warning,本 dim batch verify 既有 consumer"
+    },
+    "select_all_canonical": {
+      "dims": [
+        17,
+        32
+      ],
+      "note": "Dim 17 SSOT propagation + Dim 32 filter SSOT consumption canonical 涵蓋 — `multi-select-ordering` primitive 屬 SSOT consumer propagation(per Ant Transfer + Table rowSelection grep 證據,Layer A + Codex M31 Round 4 共識,2026-05-16)。Hook write-time pre-warning,Dim 17/32 batch verify 既有 Select All consumer 是否 import primitive 而非自刻 `options.map(v).onValueChange` reset"
+    },
+    "pixel_quantified_audit": {
+      "dims": [],
+      "note": "對 audit scripts 自身,not component"
+    },
+    "propose_plain_chinese": {
+      "dims": [],
+      "note": "governance-only"
+    },
+    "solo_workflow": {
+      "dims": [],
+      "note": "governance-only"
+    },
+    "story_invariants": {
+      "dims": [
+        11,
+        12,
+        13,
+        23,
+        24,
+        25,
+        28,
+        29,
+        40,
+        41
+      ]
+    },
+    "substantive_edit_approval_preflight": {
+      "dims": [],
+      "note": "governance-only"
+    },
+    "wrapper_primitive_schema_drift": {
+      "dims": [],
+      "note": "考慮加 dim 52 wrapper-extends scan"
+    },
+    "audit_post_report_validator": {
+      "dims": [],
+      "note": "2026-05-17 ship;governance-only — validates `/design-system-audit` final report quality(NO-SAMPLE / 46-dim coverage / audit-prompts.md coverage / @benchmark-unverified-blanket debt drift),emit prune-chain-trigger signal。不屬 component scope"
+    },
+    "tailwind_token_registry": {
+      "dims": [
+        47
+      ],
+      "note": "2026-05-17 升級(原 opacity_token_usage 擴):讀 packages/design-system/src/tokens/utility-registry.json SSOT,擋 leading-N / tracking-* / gap-px|0.5|1.5 / w-fraction / text-(xs|sm|...) / font-(thin|light|...) / rounded-(xl|2xl|3xl) 等 untracked utility"
+    },
+    "tab_lg_chrome_header_equal": {
+      "dims": [
+        52
+      ],
+      "note": "2026-05-17 ship(Header canonical W3 token alignment):parse uiSize.css + globals.css 對等 assert(不 CSS alias 因 scope 不同)。對應 patterns/header-canonical/header-canonical.spec.md W3 + M31 codex 比稿 Step 5 共識"
+    },
+    "header_with_tabs_border": {
+      "dims": [
+        52
+      ],
+      "note": "2026-05-17 ship(Header canonical W1 border ownership):header 含 Tabs 必標 withTabs prop 讓 paint delegate;違反 = 雙線 BLOCKER。對應 patterns/header-canonical/header-canonical.spec.md W1 + GitHub Primer PageHeader auto-suppress 模式"
+    },
+    "chrome_header_handcraft": {
+      "dims": [
+        52
+      ],
+      "note": "2026-05-17 ship(Header canonical Layer 3 ChromeHeader consumption):production chrome header 自刻 h-chrome-header-height+border-b 簽名 → soft P1 warn,Phase 3 後升 P0 BLOCKER。對應 patterns/header-canonical/header-canonical.spec.md Layer 3 + M30 wrapper extends primitive"
+    },
+    "spec_class_drift": {
+      "dims": [
+        53
+      ],
+      "note": "2026-05-17 ship(audit Dim 53 reverse drift):spec.md 寫「固定 h-NN/寫死/硬寫」keyword 但對應 tsx 已消費 token → soft P1 warn。互補既有 forward direction(spec-to-code),起因 Phase 1 抓不到 FileViewer h-14 spec drift"
+    },
+    "audit_sample_escape": {
+      "dims": [],
+      "note": "2026-05-17 ship(audit canonical infra,non-component scope):PreToolUse Agent 攔截 dispatch prompt 含「sample evidence allowed / heavy agent needed / top N」escape clause → BLOCKER。Mechanical enforce NO-SAMPLE invariant。起因 user verbatim「你他媽是不是又再搞抽樣」,Dim 24/25/40-43/45/46/48 sub-agent 多次 sampled"
+    },
+    "main_branch_workbench": {
+      "dims": [],
+      "note": "2026-05-17 ship(Solo-work canonical infra,M28 sub-rule):PreToolUse Edit/Write 偵測 current branch=main + edit production code(packages/design-system/src/src/app/src/explorations)+ 近 5 條 user msg 無 branch-trigger keyword → BLOCKER。補 R1(2nd branch)R2(PR)R3(push main)沒抓的「main-as-workbench」case。起因 user verbatim 2026-05-17「不是只有我說 push 到 main 才真的會 push 到 main 嗎」,本 session AI 整個 deep audit 都在 main 上 edit。escape:doc-only(spec.md) / CLAUDE_BYPASS_MAIN_WORKBENCH=1"
+    },
+    "dim_count_drift": {
+      "dims": [],
+      "note": "2026-05-18 ship(audit SSOT integrity infra,non-component scope):PreToolUse Edit/Write 攔 chain skill / spec / rule / CLAUDE.md hardcode 具體 audit dim 數字(53 dim / 46-dim / N audit dimensions),強制 design-system-audit/SKILL.md `## The N audit dimensions` 為 SSOT,deep-audit-cross-codex 等 chain skill 自動繼承。Allowlist:SSOT file 自己 / invariant doc 引用(SSOT/禁/forbidden/example/hardcode keyword 同行)。起因 user 2026-05-18「deep-audit-cross-codex 應該要確保其中的 design system deep audit 跟 design-system-audit deep 是 ssot」"
+    },
+    "propose_pre_grep_verify": {
+      "dims": [],
+      "note": "2026-05-18 ship(M18 Q0 Pre-ASK self-verify governance infra):PreToolUse Edit/Write planning/reports/handoff *.md 偵測 propose keyword(請拍板 / 等你拍板 / 決策 N / 我推 A/B/C / 選項)但 content 無 file:line cite 證據 → P1 stderr warn。Escape:檔頭 <!-- @propose-pre-verified --> 含 rationale。起因 2026-05-18 Sheet/inline-action/SurfaceBody 三題 propose 給 user 拍板,grep 後 0 個真 gap;user verbatim「不是老早就跟你說過要我決策前請先基於我們所有的檔案包括設計原則包括 ssot 包括所有實作代碼,自主自動驗證這些問題是否真的是問題」"
+    }
+  },
+  "newDims_2026_05_17": {
+    "_principle": "Codex M31 共識:World-class tier dims 47-51,對齊 Atlassian/Carbon/Ant/Polaris/Material UI/Material Web/Apple HIG",
+    "47": {
+      "name": "Tailwind utility registry compliance",
+      "ssot": "packages/design-system/src/tokens/utility-registry.json",
+      "hook": "tailwind_token_registry"
+    },
+    "48": {
+      "name": "Unused / orphan token detector",
+      "ssot": "tokens/**/*.spec.md 消費者 段 cross-verify",
+      "hook": "TBD"
+    },
+    "49": {
+      "name": "a11y axe-core 自動 + WCAG contrast ratio",
+      "ssot": "Storybook a11y addon + axe-core CI",
+      "hook": "TBD"
+    },
+    "50": {
+      "name": "Bundle size budget per component",
+      "ssot": "package.json size-limit + per-component manifest",
+      "hook": "TBD"
+    },
+    "51": {
+      "name": "Theme / density visual matrix",
+      "ssot": "visual-audit Layer B + baseline snapshot",
+      "hook": "visual-audit Layer A chain"
+    },
+    "52": {
+      "name": "Header canonical cross-family invariants(W1-W6)",
+      "ssot": "patterns/header-canonical/header-canonical.spec.md",
+      "hook": "tab_lg_chrome_header_equal + header_with_tabs_border + chrome_header_handcraft"
+    },
+    "53": {
+      "name": "Code-to-spec reverse drift check",
+      "ssot": ".claude/skills/design-system-audit/SKILL.md Group P",
+      "hook": "spec_class_drift",
+      "note": "新加(2026-05-17):反向 grep tsx hardcoded class → 對應 spec.md 是否仍寫舊值。Phase 1 漏抓 FileViewer h-14 spec drift 升 dim,對齊 Layer A own Phase 0 全掃 + codex 共識"
+    }
+  },
+  "auditOnlyGaps": {
+    "_principle": "本節列「user mission 真實 gap」— 屬 visible audit 範疇但無 dim cover,需新增 dim",
+    "candidates": [
+      {
+        "id": "M3 Portal theme",
+        "proposedDim": "Dim 47 Portal subtree theme integrity DS-wide"
+      },
+      {
+        "id": "M15 OpenSnapshot",
+        "proposedDim": "Dim 48 Stakeholder flow OpenSnapshot coverage"
+      },
+      {
+        "id": "M26 cite freshness",
+        "proposedDim": "Dim 49 Benchmark cite WebFetch freshness (release 級)"
+      },
+      {
+        "id": "M30 wrapper extends",
+        "proposedDim": "Dim 50 Wrapper schema extends primitive DS-wide"
+      },
+      {
+        "id": "M32 audit pixel",
+        "proposedDim": "audit script self-test;不屬 component scope,保留 hook layer"
+      },
+      {
+        "id": "trait:isStructural",
+        "proposedDim": "Dim 51 Structural element 規格"
+      },
+      {
+        "id": "hook:datatable_invariants",
+        "proposedDim": "Dim 52 DataTable canonical full-scan"
+      }
+    ]
+  }
+}

package/ds-canonical/references/props-naming.md

@@ -0,0 +1,45 @@
+# 元件 Props 命名 — 詳細對照表
+
+`.claude/rules/ui-development.md`「元件 Props 命名」的詳細展開(callback / Badge / icon canonical)。
+
+## 關閉 / 移除類 callback canonical(按語意分層,不合併)
+
+四個名稱各有語意,不可替換:
+
+| Callback | 語意 | 典型元件 | 世界級對照 |
+|----------|------|---------|-----------|
+| `onClose` | **關閉 overlay session** — 浮層關閉回背景 | Dialog / Sheet / Popover / FileViewer / HoverCard | React Aria `onClose` / Material `DialogProps.onClose` |
+| `onDismiss` | **通知被忽略** — 暫時訊息被關,不影響流程 | Alert / Notice / Toast / Coachmark | Polaris `Toast.onDismiss` / iOS `dismiss()` |
+| `onRemove` | **從集合移除 item** — parent collection 狀態變化 | PeoplePicker / Combobox multi-select tag / Tag(in list) | Material `Chip.onDelete` / React Aria `onRemove` |
+| `onClear` | **欄位內容清空** — value 設 empty,元件不關 | Input / Select / Combobox / DatePicker clear | Ant `allowClear` + `onClear` / Polaris `clearButton` |
+
+**禁止**:用同一名 cover 多語意(`onClose` 同時表達 Tag 的 `onRemove`)。spec 寫 callback 時必明示哪一類。
+
+## Badge 類 prop 名 canonical(按放置,不按「是 badge」籠統命名)
+
+Badge 在不同 anchor 有兩種截然不同視覺 / 語意,prop 名區分:
+
+| Prop | 用途 | 典型 anchor | Badge 型態 |
+|------|------|------------|----------|
+| `badge` | **Pill 內 inline badge** — label 右側 flex | Button(有 label)/ Tab item / Chip | inline count |
+| `overlayBadge` | **疊視覺重心** — absolute 於 icon/avatar 角 | iconOnly Button / pure Icon | top-right count overlay |
+| `badgeCount`(Avatar 專用) | count overlay,內部用 `<Badge variant="critical">`,貼 avatar 右上 | Avatar | overlay but Avatar 語意 |
+| `status`(Avatar 專用) | **非 Badge** — SVG presence dot,貼右下 | Avatar | presence indicator |
+
+**禁止**:同 prop 名兼 inline + overlay。世界級 Material `BadgedBox`(overlay)vs `Chip.label`(inline)分開;Ant `<Badge overflowCount>` vs `<Tag>` 分開。
+
+**禁止組合**:有 label 的 Button / Chip 疊 `overlayBadge`(badge 飄到 chrome 邊緣遠離 icon 語義) → 計數改用 `badge` inline。詳 `badge.spec.md`「Overlay 適用元件 canonical」。
+
+## 常用 icon canonical
+
+| 語義 | Icon | 反例 |
+|------|------|------|
+| 溢出選單 / 更多動作 | **`MoreVertical`** | ❌ `MoreHorizontal`(row 內水平排 icon 跟水平動作按鈕群視覺混淆,縱向三點更明確) |
+| 路徑收合(Breadcrumb ellipsis)| `MoreHorizontal` | 唯一保留 `MoreHorizontal` — 沿路徑方向省略,非 overflow menu |
+| 關閉(Close / Dismiss)| `X` | ❌ `XCircle`(error status,語義衝突) |
+| 成功 / 完成 | `Check` / `CircleCheck` | — |
+| 失敗 / 錯誤 | `XCircle` | — |
+| 警告 / 提醒 | `TriangleAlert` | — |
+| 資訊 / 說明 | `Info` | — |
+
+**世界級對照**:Linear / Notion / GitHub / Figma 全部用 vertical 3-dots 作 overflow;horizontal 3-dots 專給 path/truncation(Breadcrumb / text ellipsis)。

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/rules/ui-development.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`(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)