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

package/ds-canonical/skills/visual-audit/SKILL.md

@@ -15,7 +15,7 @@ description: Pixel-level visual audit for design-system components based on user
 - **Carousel** prev/next 箭頭覆蓋 content
 - **Rating** 星星有多餘邊框
 - **Image viewer** 滾輪縮放跳大步(對標 Figma 該每 notch ~1.1×)
-- **Button 群 gap** 被 hover bg overflow 吃掉(CLAUDE.md 有「同 flex 列互動 slot 幾何鐵律」但缺視覺 audit gate 鎖住)
+- **Button 群 gap** 被 hover bg overflow 吃掉(`packages/design-system/ds-canonical/references/ui-dev-rules.md` 有「同 flex 列互動 slot 幾何鐵律」但缺視覺 audit gate 鎖住)
 - **FileViewer 工具列** dark mode 切換後對比跑掉
 - **FileUpload / FileItem** 沒 fill container
 
@@ -23,7 +23,7 @@ description: Pixel-level visual audit for design-system components based on user
 
 ## 兩層架構 + state coverage canonical
 
-**Layer A mechanical**(`npm run visual-audit`):截圖 + WCAG + geometry。**Layer B AI**(本 skill):合理 / 一致 / 世界級對照。**Workflow**:`npm run visual-audit` → `/visual-audit` 讀 `snapshots/report.json`。詳 → [`references/audit-architecture.md`](references/audit-architecture.md)(兩層架構 + hover / focus-visible / play() coverage roadmap)。
+**Layer A mechanical**(`npm run visual-audit`):截圖 + WCAG + geometry。**Layer B AI**(本 skill):合理 / 一致 / 世界級對照。**Workflow**:`npm run visual-audit` → `/visual-audit` 讀 `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/report.json`。詳 → [`references/audit-architecture.md`](references/audit-architecture.md)(兩層架構 + hover / focus-visible / play() coverage roadmap)。
 
 ## Skill 生態位
 
@@ -31,7 +31,7 @@ description: Pixel-level visual audit for design-system components based on user
 /design-system-audit    全 dim 深度 audit(per design-system-audit SSOT,code/spec 層,Phase 0 自建 baseline)
 /product-ui-audit       consumer UI 對 DS 消費的 6 dim audit(code 層)
 /visual-audit           pixel-level 視覺 audit(本 skill,需 screenshot)
-/component-quality-gate  合入 DS 前的 45 項 checklist(Ship phase 可 chain 本 skill)
+/component-quality-gate  合入 DS 前的 35 項 checklist(Ship phase 可 chain 本 skill)
 ```
 
 **關鍵切分**:visual-audit 只看 pixel,**不讀 code / 不改 code**。code / spec / cva 的事全部歸前兩 skill;視覺幾何對齊 / overlay 定位 / baseline / typography vertical rhythm 等「眼睛看得到、mechanical 量得出」的事才是本 skill scope。
@@ -52,27 +52,29 @@ description: Pixel-level visual audit for design-system components based on user
 - 沒有 screenshot → **本 skill 拒跑**(見 Preconditions)
 - 只要看一眼順不順 → 不做 audit(這不 mechanical)
 
-## Preconditions(硬規則)
+## Baseline 更新鐵律(2026-07-07 軌道 5 codify)
 
-**本 skill 在下列任一缺失下拒跑,回報 user 補齊後再 invoke**:
+**覆蓋任何 `infra/governance/baseline/visual/{curated,targeted}/*.png` 前,模型必 Read 新舊兩張圖並寫出「觀察到的具體差異」**。所有 provider-specific baseline compatibility path 都僅是 deterministic generated delivery/discovery projection,not authority,do not edit,禁止當 reverse SSOT 寫入。
+(diff 百分比是訊號、圖才是真相)。禁只看 pct 就 cp。錨例:2026-07-07 VR 換日 bug——釘日期後
+pct 一模一樣,只有看圖才發現 today 圈仍在真實日期(元件內部時間);FileViewer 40.3% 只有看圖
+才知道是 zoom 94→100(fit 被凍壞)非渲染炸裂。配套:roadmap 方向 7 accept-baseline workflow
+(script 化時「看圖步驟」不可省)。
 
-1. **screenshot 缺失** — user 未上傳 Storybook 或元件實際 render 的截圖
-2. **audit target 未明** — 沒指定要稽核哪個元件 / 哪個 story / 哪個頁面
-3. **容器尺寸 / viewport 未知** — screenshot 沒附上容器寬度 / viewport size / 元件 size prop,無法 mechanical 量
-4. **token 聲明未知** — 該元件 spec 沒宣告該看哪些 token(本 skill 不推測,只比對)
+## Evidence preflight(硬規則)
 
-**拒跑回報範例**:
+先從 explicit target、目前 frozen scope／changed paths、Layer-A report、story registry 與
+capture manifest 解析 audit target。缺 screenshot 時，優先用既有 Storybook／product capture
+流程自行產生；viewport、density、theme 與 size 必取自同一 capture manifest，不靠猜測或
+另問 user。元件 token 由 owning spec 與 token registry 解析。
 
-```
-本 skill 需要以下資訊才能跑,目前缺:
-- [x] screenshot(Storybook 或實際 render)
-- [ ] 稽核 target(哪個元件 / 哪個 story 或 URL)
-- [ ] 容器 / viewport 資訊(container width / density / theme)
-
-補齊後請 re-invoke /visual-audit,不要讓我用猜的跑 audit。
-```
+只有在本機／既有受治理環境確實無法取得 target 或影像，且原因是不可代理的登入、MFA、
+OAuth 或 private surface access 時，才形成 shared-governance human-only action；此時先完成
+所有其他 preflight，只回報唯一必要操作。若 owning spec 缺 token，記為 P2E governance
+evidence gap 並交 canonical owner；若補值會創造產品／UI／UX SSOT 真取捨才列 P2H。
 
-**絕不**在資訊不足下憑感覺判斷——「看起來有點歪」不是 audit,是直覺。本 skill 產出必須全部是 mechanical 可驗證的結論。
+**絕不**在 evidence 不足下憑感覺判斷——「看起來有點歪」不是 audit,是直覺。本 skill
+產出必須全部是 mechanical 可驗證的結論；無法取得的項目記為 fail-closed evidence gap，
+不能用 blanket user checkpoint 取代。
 
 ---
 
@@ -84,7 +86,7 @@ description: Pixel-level visual audit for design-system components based on user
 |---|------|---------|
 | 1 | **4 邊邊距對稱** | 容器 top / right / bottom / left padding 實測值相等(除明文 asymmetric spec 外) |
 | 2 | **垂直對稱(to-top ↔ to-bottom)** | 最外層 element 到容器頂 = 最內層 element 到容器底(DatePicker 箭頭 vs 最後排日期) |
-| 3 | **水平 gap 實際值 == gap token 宣告值** | hover bg / ring / focus outline 不可溢出 box 吃掉宣告 gap(CLAUDE.md「同 flex 列互動 slot 幾何鐵律」) |
+| 3 | **水平 gap 實際值 == gap token 宣告值** | hover bg / ring / focus outline 不可溢出 box 吃掉宣告 gap(`packages/design-system/ds-canonical/references/ui-dev-rules.md`「同 flex 列互動 slot 幾何鐵律」) |
 | 4 | **Overlay 定位(badge / popover / hover-card)** | anchor-offset / side-offset 對稱;不覆蓋 anchor 內容 |
 | 5 | **Typography baseline 對齊** | icon 與同行 text 的 baseline 對齊(非 geometric center 誤植) |
 | 6 | **Icon ↔ text gap 一致** | 同類型 row 裡所有 icon-to-text 距離相等 |
@@ -102,15 +104,12 @@ description: Pixel-level visual audit for design-system components based on user
 
 ## Workflow
 
-### Phase 0 — Setup + 拒跑 gate
+### Phase 0 — Setup + evidence gate
 
-1. 讀 CLAUDE.md 完整(最新 token / 最新 layout primitive 規則)
-2. 檢查 user 是否提供 4 項必要資訊(見 Preconditions):
-   - screenshot
-   - audit target(元件 / story / URL)
-   - 容器 / viewport 資訊
-   - 該元件對應的 spec.md path
-3. **任一缺失 → 停下,按 Preconditions 範例回報,不 proceed**
+1. 讀 `AGENTS.md` 與 `packages/design-system/ds-canonical/rules/ui-development.md`(最新 token / 最新 layout primitive 規則);provider view 只用於 discovery,不能反向當 authority
+2. 依 Evidence preflight 從 frozen scope／changed paths、Layer-A report 與 registry 定 target。
+3. 取得或自行 capture screenshot，並綁定同一份 viewport／density／theme／size manifest；
+   缺 evidence 時依上節 fail closed，不把工程查找工作轉交 user。
 4. 讀該元件的 `{name}.spec.md`——記下 spec 宣告的 token 值(e.g.「field-height-md = 36px」「gap-2 = 8px」「layout-space-loose = 16px」),作為 mechanical 對照基準
 5. Create TaskList entries(13 個 checklist item 各一)
 
@@ -130,16 +129,18 @@ description: Pixel-level visual audit for design-system components based on user
 - **不寫主觀描述**(「看起來鬆散」「感覺歪」不算 audit 結論)——只寫可 mechanical 驗證的數字 / ratio
 - **不推測 code**(「應該是 cva size 錯」不是本 skill 結論;code 的事走 `/design-system-audit`)
 - **不修 code**(本 skill 只報告,不 Edit 任何檔)
-- **超出 checklist 的視覺問題** → 記為 `額外觀察`,附 screenshot 座標 + 描述,交 user 決定要不要升級為 checklist 項
+- **超出 checklist 的視覺問題** → 記為 `額外觀察`,附 screenshot 座標 + 描述；依 shared governance authority classifier 路由：純機械 coverage／治理補強是 P2E/AUTO，只有升級會改變產品／UI／UX SSOT 且仍有真取捨才 P2H
 
 ### Phase 2 — 輸出 report(固定格式)
 
 產出檔案路徑:
 
 ```
-.claude/skills/visual-audit/output/{YYYYMMDD}-{component}-visual-audit.md
+<absolute-git-dir>/governance-runtime/evidence/visual/manual-audit/{YYYYMMDD}-{component}-visual-audit.md
 ```
 
+寫入前必須以 `node scripts/lib/governance-runtime-evidence.mjs --repo-root "$PWD" --path "visual/manual-audit/{filename}" --prepare-file` 取得經驗證的 exact destination;不得自行推導 `.git` 路徑,不得寫 provider home。
+
 **檔名規則**:同一天同元件多次跑 → 加 `-v2` / `-v3`。`{component}` 用 kebab-case(對齊專案慣例),例:`20260421-date-picker-visual-audit.md`。
 
 ### Report 格式(嚴格)
@@ -166,7 +167,7 @@ Spec 依據: {packages/design-system/src/components/{Name}/{name}.spec.md}
 - 實測: top=12px, right=12px, bottom=8px, left=12px
 - 預期: 4 邊 = layout-space-loose(16px)或 spec 明文 asymmetric
 - 差異: bottom 少 4px,且非 spec 明文例外
-- 對應規則: `.claude/rules/ui-development.md`「建立 UI 前必讀」 → layout-space token + 該元件 spec.md 第 N 段
+- 對應規則: `packages/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 → layout-space token + 該元件 spec.md 第 N 段
 - 建議修法方向(不自己改): 調整 bottom padding 對齊 layout-space-loose,或在 spec 記 rationale 為何 asymmetric
 
 ### 2. 垂直對稱
@@ -185,12 +186,12 @@ Spec 依據: {packages/design-system/src/components/{Name}/{name}.spec.md}
 - 本 report 不改 code;fix 請走 `/design-system-audit` 或直接 edit
 ```
 
-### Phase 3 — Checkpoint(必停,STOP 點)
+### Phase 3 — Read-only handoff(skill boundary，不是 user approval checkpoint)
 
-Report 寫完後**停下來**,不 auto-fix。回報 user:
+Report 寫完後，本唯讀 skill 不直接改 source；將 evidence 交回 primary context 並依 shared governance authority classifier 繼續：
 
 ```
-Visual audit 寫到 .claude/skills/visual-audit/output/{YYYYMMDD}-{component}-visual-audit.md
+Visual audit 寫到 <absolute-git-dir>/governance-runtime/evidence/visual/manual-audit/{YYYYMMDD}-{component}-visual-audit.md
 
 - PASS: N / 13
 - FAIL: M / 13
@@ -201,12 +202,13 @@ FAIL 項摘要:
 - #3 gap 吃掉: hover bg 溢出 ~4px(違反「同 flex 列幾何鐵律」)
 - ...
 
-下一步選項:
-1. 依 FAIL 清單去改 code / spec(我可以 chain 進 /design-system-audit 或手動 edit)
-2. 對某項 FAIL 有爭議 → 討論是否為 spec 明文例外(可加 rationale)
-3. 本輪 audit 就結束,user 自行處理
+後續路由:
+1. FAIL 可由既有 canonical 決定 → P2E，由 primary context 依 Standing Authorization remediation + verify
+2. 純工程／治理原因尚未收斂 → P2E，依 Engineering Decision Policy、tests 與 hard gates 收斂；task／deliverable 明確要求時才加 independent review，optional review 缺席不得阻擋一般工程；無法收斂則 fail closed 回報 technical blocker
+3. 必須改變產品／UI／UX SSOT 且仍有真實選擇或取捨 → P2H，batch-at-end 請 user 拍板
+4. 證據不足 → 補足 screenshot／量測，不以猜測結案
 
-(本 skill 不 auto-proceed;改 code 由其他 skill 或 user 決定。)
+(本 skill 保持 read-only；primary implementation 不需另取 user 工程授權。)
 ```
 
 ---
@@ -219,7 +221,7 @@ FAIL 項摘要:
 - **不做主觀審美**(「看起來比較漂亮」不是 audit 結論)
 - **不改 code / spec / story**(純 read-only report)
 - **不推斷沒截到的部分**(screenshot 沒含某 state 不做推測)
-- **不 auto-fix**(Phase 3 STOP 交 user 決策)
+- **不在本 read-only skill 內 auto-fix**(Phase 3 將 evidence 交回 primary context；依 P2E/P2H classifier 繼續)
 
 ## Common failure modes(watch for these)
 
@@ -237,9 +239,8 @@ FAIL 項摘要:
 
 ## 相關
 
-- `.claude/skills/design-system-audit/SKILL.md` — 全 dim code/spec audit(per design-system-audit SSOT);本 skill 是其 pixel-level 補位
-- `.claude/skills/product-ui-audit/SKILL.md` — consumer UI 對 DS 消費 audit(code 層),不處理視覺
-- `.claude/skills/component-quality-gate/SKILL.md` — 元件合入 DS 前的 45 項 checklist;Ship phase 可 chain 本 skill
-- CLAUDE.md `# 同 flex 列的互動 slot 幾何鐵律` — 本 skill checklist #3 的主要 canonical 來源
-- `.claude/rules/ui-development.md`「建立 UI 前必讀」 → layout primitive / token spec 清單 — 本 skill「合格標準」的對照錨
-- `memory/project_pending_tasks`「視覺 regression 基建」條目 — 長期 tech debt(Chromatic / screenshot-diff)
+- `packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md` — 全 dim code/spec audit(per design-system-audit SSOT);本 skill 是其 pixel-level 補位
+- `packages/design-system/ds-canonical/skills/product-ui-audit/SKILL.md` — consumer UI 對 DS 消費 audit(code 層),不處理視覺
+- `packages/design-system/ds-canonical/skills/component-quality-gate/SKILL.md` — 元件合入 DS 前的 35 項 checklist;Ship phase 可 chain 本 skill
+- `packages/design-system/ds-canonical/references/ui-dev-rules.md` `# 同 flex 列的互動 slot 幾何鐵律` — 本 skill checklist #3 的主要 canonical 來源
+- `packages/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 → layout primitive / token spec 清單 — 本 skill「合格標準」的對照錨

package/ds-canonical/skills/visual-audit/references/audit-architecture.md

@@ -8,15 +8,15 @@
 
 | Layer | 做什麼 | 由誰做 | 自動化 |
 |-------|-------|--------|--------|
-| **A. Mechanical** | (1) 截圖每個 scenario(retina PNG → `snapshots/`)<br>(2) WCAG 對比度掃描(所有可見文字 / icon vs 底色,flag AA 不過的組合)<br>(3) DOM 幾何 assertion(等高 / 對稱 padding / 正確 gap — 讀 `scripts/visual-assertions.json` 定義) | `scripts/visual-audit.mjs`(Playwright-driven) | **npm run visual-audit** 一鍵跑,產出 `snapshots/report.json` + PNG。CI 可接(exit 1 on violation) |
-| **B. AI judgement** | (1) 設計合理性(badge 位置語意對、carousel 箭頭不壓文字、zoom step 手感)<br>(2) 跨元件視覺一致(同 flex 列幾何鐵律、Family 視覺對齊)<br>(3) 世界級對照(「這跟 Figma/Notion/iOS 相比還差在哪」) | **本 skill**(`/visual-audit`),讀 `snapshots/*.png` + `report.json` 做 pattern recognition | invoke 時 AI 跑 |
+| **A. Mechanical** | (1) 截圖每個 scenario(retina PNG → Git-owned neutral evidence)<br>(2) WCAG 對比度掃描(所有可見文字 / icon vs 底色,flag AA 不過的組合)<br>(3) DOM 幾何 assertion(等高 / 對稱 padding / 正確 gap — 讀 `scripts/visual-assertions.json` 定義) | `scripts/visual-audit.mjs`(Playwright-driven) | **npm run visual-audit** 一鍵跑,產出 `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/report.json` + PNG。CI 可接(exit 1 on violation) |
+| **B. AI judgement** | (1) 設計合理性(badge 位置語意對、carousel 箭頭不壓文字、zoom step 手感)<br>(2) 跨元件視覺一致(同 flex 列幾何鐵律、Family 視覺對齊)<br>(3) 世界級對照(「這跟 Figma/Notion/iOS 相比還差在哪」) | **本 skill**(`/visual-audit`),讀 `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/*.png` + `report.json` 做 pattern recognition | invoke 時 AI 跑 |
 
 ### Layer A 先跑,Layer B 後補(workflow)
 
 ```
 1. npm run visual-audit                  # Layer A 產 snapshots + report
-2. /visual-audit                         # 本 skill 讀 snapshots/ 做 Layer B 判斷
-   (skill 自動讀 snapshots/report.json 作為 Layer A baseline,
+2. /visual-audit                         # 本 skill 讀 neutral runtime evidence 做 Layer B 判斷
+   (skill 自動讀 <absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/report.json 作為 Layer A evidence,
     重點關注 A 沒 flag 但視覺仍不對的 case)
 ```
 
@@ -35,7 +35,7 @@ npm run visual-audit
 # scoped 跑(快速驗證 — 1 個 component)
 node scripts/visual-audit.mjs --scope=component:Button
 
-# 只跑 changed(git diff)— 對齊 CLAUDE.md「日常 dev」高效模式
+# 只跑 changed(git diff)— 對齊 AGENTS.md provider-neutral「日常 dev」高效模式
 node scripts/visual-audit.mjs --scope=changed
 
 # 不啟 storybook(如果 storybook 已起)
@@ -43,8 +43,8 @@ node scripts/visual-audit.mjs --no-auto-start
 ```
 
 Output:
-- `snapshots/{scenarioId}.png` — retina PNG
-- `snapshots/report.json` — `{ contrast: [], geometryViolations: [], a11yViolations: [], baselineDiff: {} }`
+- `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/{scenarioId}.png` — retina PNG
+- `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/report.json` — `{ contrast: [], geometryViolations: [], a11yViolations: [], baselineDiff: {} }`
 
 ## Layer A interactive state coverage canonical
 

package/ds-canonical/skills/visual-audit/references/visual-checklist.md

@@ -5,7 +5,7 @@
 **通用量測原則**:
 - 用 image reading 取 screenshot 像素座標(左上為原點 0,0;單位 px)
 - 同一面向的 4 個量測點必須用「同一張 screenshot 的同一縮放比例」;混不同 screenshot 比例會誤判
-- 容器寬度 / viewport / density / theme 必先向 user 確認(SKILL.md Preconditions 項 3)
+- 容器寬度 / viewport / density / theme 必綁定同一 Layer-A capture manifest；不得靠猜測，也不得把可由 registry/capture 解析的工程工作轉問 user
 - 合格標準若為 token → 對照「該元件 spec 宣告的 token 值」或 `tokens/*/` primitive;不是「看起來接近就算對」
 - **容差規範**:px 量測允許 ±1px(螢幕截圖 sub-pixel rounding);ratio 允許 ±5%;明文標「精確」的項目(如對稱)不給容差
 
@@ -14,7 +14,7 @@
 - `實測: {量到的值}`
 - `預期: {token 值或 ratio}`
 - `差異: {若 FAIL,寫出 diff 和推測破壞規則}`
-- `對應規則: {CLAUDE.md 章節 or spec.md 段落 or token 名}`
+- `對應規則: {AGENTS.md 章節 or spec.md 段落 or token 名}`
 
 ---
 
@@ -34,7 +34,7 @@
 
 **FAIL 範例**:DatePicker 量到 top=12 / right=12 / bottom=8 / left=12,spec 未宣告 bottom asymmetric → FAIL,建議討論是對齊 12 還是補 spec rationale
 
-**對應規則**:CLAUDE.md `# Consistency Audit 原則`(actual == canonical OR rationale-for-deviation)
+**對應規則**:AGENTS.md `# 稽核 canonical`「Consistency 類稽核必 Phase 0 全掃再判」(actual == canonical OR rationale-for-deviation;design-system-audit Dim 13 enforce)
 
 ---
 
@@ -54,13 +54,13 @@
 
 **FAIL 範例**:DatePicker 箭頭按鈕 top=12px 但最後一排日期 bottom=4px → 差異 8px 違反上下對稱
 
-**對應規則**:該元件 spec.md + `.claude/rules/ui-development.md`「建立 UI 前必讀」 layout-space token
+**對應規則**:該元件 spec.md + `packages/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 layout-space token
 
 ---
 
 ## 3. 水平 gap 實際值 == gap token 宣告值(hover bg 不可吃掉)
 
-**Canonical source**: CLAUDE.md `# 同 flex 列的互動 slot 幾何鐵律`(gap 鐵律)
+**Canonical source**:`packages/design-system/ds-canonical/references/ui-dev-rules.md` `# 同 flex 列的互動 slot 幾何鐵律`(gap 鐵律)
 
 **怎麼量**:
 1. 量同一 flex row 相鄰兩 interactive slot 的 **box 邊** 之間距離(不是「視覺中心距離」,是右邊 slot 左緣 - 左邊 slot 右緣)
@@ -70,11 +70,11 @@
 
 **合格標準**:
 - default + hover 兩態的 gap 都 == 宣告值(±1px) → PASS
-- hover 狀態 gap 被 bg overflow 吃掉 → FAIL(違反 CLAUDE.md「同 flex 列幾何鐵律」)
+- hover 狀態 gap 被 bg overflow 吃掉 → FAIL(違反 `packages/design-system/ds-canonical/references/ui-dev-rules.md`「同 flex 列幾何鐵律」)
 
 **FAIL 範例**:FileItem 2026-04-19 bug,Button hover-bg 24px 超出 16px box,`gap-2`(8px)實際剩 ~4px
 
-**對應規則**:`.claude/rules/ui-development.md` → `# 同 flex 列的互動 slot 幾何鐵律`(必讀)
+**對應規則**:`packages/design-system/ds-canonical/rules/ui-development.md` → `# 同 flex 列的互動 slot 幾何鐵律`(必讀)
 
 ---
 
@@ -98,7 +98,7 @@
 
 **FAIL 範例**:Carousel prev/next 箭頭覆蓋 carousel item content;Badge 疊 Button 距離離譜用硬寫 px
 
-**對應規則**:對應元件 spec;`.claude/rules/ui-development.md`「元件 Props 命名」「常用 icon canonical」(若箭頭用錯 icon);`.claude/rules/ui-development.md`「建立 UI 前必讀」 overlay-surface pattern
+**對應規則**:對應元件 spec;`packages/design-system/ds-canonical/rules/ui-development.md`「元件 Props 命名」「常用 icon canonical」(若箭頭用錯 icon);同檔「建立 UI 前必讀」 overlay-surface pattern
 
 ---
 
@@ -136,7 +136,7 @@
 
 **FAIL 範例**:5 個 MenuItem 有 4 個 gap=8px,1 個 gap=12px(consumer 手動加了 `gap-3`)
 
-**對應規則**:`item-anatomy.spec.md`;`.claude/rules/ui-development.md`「新增數值前必須先查既有 pattern」
+**對應規則**:`item-anatomy.spec.md`;`packages/design-system/ds-canonical/rules/ui-development.md`「新增數值前必須先查既有 pattern」
 
 ---
 
@@ -175,13 +175,13 @@
 
 **FAIL 範例**:Input(size=md, 36px)+ Button(size=md, 36px)+ Select(誤用 size=sm, 28px)→ Select 偏低 8px
 
-**對應規則**:`uiSize.spec.md` field-height family;`.claude/rules/ui-development.md`「建立 UI 前必讀」 → uiSize token
+**對應規則**:`uiSize.spec.md` field-height family;`packages/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 → uiSize token
 
 ---
 
 ## 9. 跨 OS 一致 scrollbar
 
-**Canonical source**: `.claude/rules/ui-development.md`「建立 UI 前必讀」 「overflow 使用三規則」;`components/ScrollArea/`
+**Canonical source**:`packages/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 「overflow 使用三規則」;`components/ScrollArea/`
 
 **怎麼量**:
 1. 找 screenshot 內的 scrollable area
@@ -197,7 +197,7 @@
 
 **FAIL 範例**:DataTable 水平捲動用 native overflow-x-auto → Windows user 看到 15px scrollbar 吃 cell 寬度
 
-**對應規則**:`.claude/rules/ui-development.md`「建立 UI 前必讀」 → overflow 使用三規則
+**對應規則**:`packages/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 → overflow 使用三規則
 
 ---
 
@@ -241,7 +241,7 @@
 
 **FAIL 範例**:Popover 在 dark mode 下 shadow 消失(用了 `shadow-md` 硬寫);FileViewer 工具列在 light theme 變白(dark-mode override 失效)
 
-**對應規則**:`color.spec.md`;`.claude/rules/ui-development.md`「Tailwind 5 條核心」「shadow 一律用 `--elevation-*` token」;元件 spec 的 dark mode 段
+**對應規則**:`color.spec.md`;`packages/design-system/ds-canonical/rules/ui-development.md`「Tailwind 5 條核心」「shadow 一律用 `--elevation-*` token」;元件 spec 的 dark mode 段
 
 ---
 
@@ -292,6 +292,6 @@
 ## 補充:如何處理「checklist 沒涵蓋但視覺上怪」的情況
 
 - 記為 `額外觀察`,附 screenshot 座標 + 描述(1-2 句)
-- 交 user 決定是否升級為 checklist 項目
+- 依 shared governance authority classifier 路由：純機械 coverage／治理補強由 P2E 自動處理；只有改變產品／UI／UX SSOT 且仍有真取捨才交 P2H 決定是否升級
 - **不直接寫成 FAIL**(checklist 是 SSOT,擴項需正式流程)
 - 若同類觀察累積 3+ 次跨元件出現 → 建議升級為第 14 項 checklist 並更新本 reference

package/ds-canonical/skills/visual-audit/references/world-class-benchmarks.md

@@ -6,7 +6,7 @@
 - 合格標準優先走 DS 內 spec / token(actual == canonical)
 - DS spec 沒寫時,本檔提供世界級 idiom 作「可類推的合理區間」
 - 本檔數值**不可取代** DS 規則,只提供「世界級通常怎麼做」的事實陳述
-- 看到 FAIL 但 DS 無明文 canonical → 用本檔指出「世界級通常 X,本元件偏離 X」,交 user 決定是補 spec 還是改 code
+- 看到 FAIL 但 DS 無明文 canonical → 用本檔指出「世界級通常 X,本元件偏離 X」並套用 shared governance authority classifier：純工程／治理的 spec/code home 與 remediation 由 P2E 自動收斂；只有改變產品／UI／UX SSOT 且仍有真取捨才 P2H
 
 ---
 
@@ -32,7 +32,7 @@
 | **Atlassian Button group** | 8px gap;ring/focus outline 限制在 box 內,不 overflow |
 | **Ant Design Space** | default `gap-8`,hover bg 限制 box 內 |
 
-**世界級 idiom**:**hover bg / ring / focus outline 不超出 slot box**,保護 gap token 如實呈現。這對齊 CLAUDE.md`# 同 flex 列的互動 slot 幾何鐵律`。
+**世界級 idiom**:**hover bg / ring / focus outline 不超出 slot box**,保護 gap token 如實呈現。這對齊 `packages/design-system/ds-canonical/references/ui-dev-rules.md#同-flex-列的互動-slot-幾何鐵律`。
 
 ---
 
@@ -114,7 +114,7 @@
 - **Web DS 用 overlay scrollbar 跨 OS 一致**(Radix ScrollArea / Ant Design Scrollbar 都這樣做)
 - **原因**:Windows native scrollbar 吃寬度會讓同一 page 在 Mac 和 Windows 上 layout 不同,違反「設計在任何平台視覺一致」
 
-對應 DS:`components/ScrollArea/` + CLAUDE.md「overflow 使用三規則」。
+對應 DS:`components/ScrollArea/` + `packages/design-system/ds-canonical/references/build-ui-canonicals.md`「overflow 使用三規則」。
 
 ---
 

package/ds-canonical/templates/_README.md

@@ -0,0 +1,22 @@
+# DS canonical templates
+
+This directory ships **canonical app templates** for consumer apps to mirror.
+Per user 2026-05-27「ds repo push main → PW template 永遠 latest」directive.
+
+## Files
+
+- `dashboard-app.tsx` — AppShell + Sidebar + DashboardPage canonical full composition
+  (aligned with `sidebar.stories.tsx#IconCollapse` + `header-canonical.spec.md:57-72`)
+
+## Sync mechanism
+
+DS protected `main` / immutable release → `mirror-to-published-template.yml`:
+1. 由 DS SSOT build allowlisted `ds-product-template` snapshot，綁定 release BOM、npm integrity 與 scaffold lock
+2. 在無寫入憑證的 job 完成 clean-room install / governance / typecheck / build / a11y conformance；這不會自動升級 provider runtime certification
+3. 獨立、environment-gated Writer App 只可建立或更新 deterministic mirror PR，禁止 direct push target `main`
+4. 消費者的 `sync-design-system.yml` 再以同樣的 evidence-bound、PR-only 流程升級，不接受未認證的 branch payload
+
+Fork users 從 PW main fork → 取到當下最新 canonical baseline。Fork 後 diverge customization 是 fork user 自己責任。
+
+## SSOT chain
+DS canonical (this directory) → immutable release/BOM → evidence-verified published-template mirror PR → consumer upgrade PR → fork user 取得已審查的 exact version。

package/ds-canonical/templates/consumer-governance.md

@@ -0,0 +1,82 @@
+# Consumer Governance Contract
+
+This file is an upstream-managed, release-authenticated guide for every repository created from the
+DS product template. It explains the machine-enforced contract; it is not a second policy authority.
+The exact installed checker, `governance/lock.json`, the fork corpus lock, and protected CI remain
+authoritative. Product-owned root documentation stays product-owned, and stricter non-executable
+product rules belong only in `governance/overlay.md`.
+
+## One setup path in every environment
+
+Run `npm run setup:all` from a fresh checkout on local macOS/Linux, Codex Cloud, Claude Code
+on the web, Codespaces, or another Linux devcontainer host. Configure that same command as each
+hosted environment's setup command; Codex Cloud also uses it as the maintenance command after a
+cached container is restored. Session-start hooks never install or repair dependencies.
+
+Successful setup deliberately reports `scope=local-bootstrap`,
+`providerCertification=not-checked`, and `externalActivationRequired=false`. Ordinary bootstrap is
+complete on its own; the external-activation/readback lane is an explicit opt-in hardening path.
+The fields still do not claim that a cloud/provider runtime is certified or that external branch
+protection, apps, secrets, and required checks are activated.
+
+The locked execution contract requires Node.js 22.13.0 or newer, Bash, Git, `jq`, and Python 3.
+Native Windows is unsupported; use the committed Linux devcontainer or WSL2. The host npm only
+launches the setup script and may be npm 10 or newer. All authoritative npm operations use the
+independently downloaded and lock-verified exact npm 11.19.0 runtime. Unsupported or incomplete
+hosts fail before dependency installation or repository mutation.
+
+## Provider-neutral behavior
+
+`AGENTS.md` is the shared instruction authority. Claude, Codex, and future registered providers
+receive generated projections of the same instructions, hooks, skills, and independent-review
+contract. Provider-native hooks accelerate feedback but do not grant authority. A missing provider
+event falls back to the exact hooks-off checker and protected CI; an unregistered provider remains
+fail-closed instead of inventing a local policy surface.
+
+## Exact upgrades and `sync-all`
+
+`npm run sync-all -- --to X.Y.Z` is a syntax-only read-only plan. It does not query or authenticate
+the target and therefore reports `ok=false`, `targetVerification=deferred`,
+`targetVerified=false`, and `ready=false`; an exact-looking or nonexistent version cannot be
+mistaken for a verified release. The guarded apply path performs immutable-release, Release BOM,
+npm provenance, and signature verification before any live mutation. On a clean dedicated branch,
+`npm run sync-all -- --apply --to X.Y.Z` authenticates the exact release, reconstructs the complete
+managed snapshot, and transactionally updates eligible package, instruction, provider, skill, and
+non-executable governance data. This guide is one of those exact-hash upstream-managed files.
+Consumers already established on the current runtime/bootstrap contract receive later guide updates
+through ordinary `sync-all`. A legacy v1 consumer cannot use its old updater to replace that updater
+or cross the v2 runtime boundary: it first needs one reviewed full-snapshot bootstrap PR.
+Product-owned root README and other root documents are never taken over.
+
+Changes to `.github/**`, `.npmrc`, `governance/bin/**`, `scripts/**`, or package scripts require a
+separately reviewed full-snapshot PR — ordinary `sync-all` cannot replace the control plane that
+authorizes its own next execution. Reviewed paths run from the DS authority, materialize only a
+fresh snapshot, execute no candidate code, and emit proposals rather than applying to the live
+consumer or inventory.
+
+## Release mirror and protected PR trust chain
+
+Automatic template delivery is owned upstream by the release mirror. It opens a normal PR containing
+the exact published snapshot; a consumer does not carry a second release-dispatch/updater workflow.
+Repository Actions defaults remain read-only, and ordinary delivery requires no hosted environment or
+App credential in the consumer.
+
+The provider-neutral standard release order is exactly
+`pr-checks → merge → publish → readback → consumer`. The upstream release mirror owns template
+delivery. A registered product receiver is downstream-only: it pins every manifest discovered from
+the root workspace declaration to the exact release, regenerates the single npm lock, and derives
+both status and staging paths from `sync-exact-workspace-dependencies.mjs --list-receiver-paths`.
+It may open a protected PR; it may not publish, direct-write `main`, or replace mirror authority.
+
+Protected `main` requires the single `Verify consumer` context from `audit.yml`. That workflow performs
+one locked install followed by typecheck, import lint, and build. The normal PR review and protected
+branch rules decide whether the mirror proposal can merge. Preview, visual, accessibility, canary, and
+external readback evidence are optional hardening lanes unless a repository explicitly opts into them;
+they are not hidden prerequisites for the standard release path.
+
+## Verification boundary
+
+Use `npm run governance:check -- --hooks-off` before a PR. A local or cloud run proves deterministic
+repository conformance on that host; it does not by itself prove external GitHub protection or
+provider-runtime certification. Those claims require current target-bound evidence and independent
+external readback.