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

package/ds-canonical/fork/codex/agents/skills/delivery-handoff/references/inventory-checklist.md

@@ -0,0 +1,196 @@
+# Inventory Checklist — 元件 / token / a11y grep pattern
+
+Phase 1 inventory 生成的具體 grep + 統計方法。
+
+---
+
+## Component Inventory
+
+### 步驟 1: grep 所有 import
+
+```bash
+grep -rhnE "^import.*@/design-system/components/" {target} | \
+  sed -E 's/.*components\/([A-Z][a-zA-Z]+)\/.*/\1/' | \
+  sort | uniq -c | sort -rn
+```
+
+輸出:每個 DS 元件被 import 幾次。
+
+### 步驟 2: count JSX usage
+
+每個 component 精確使用次數(非 import):
+
+```bash
+for comp in Button Input Dialog Empty ScrollArea ...; do
+  count=$(grep -rhnE "<$comp\b" {target} | wc -l)
+  echo "$comp: $count"
+done
+```
+
+### 步驟 3: 輸出 table
+
+```markdown
+## Components Used (12)
+
+| Component | Count | Files |
+|-----------|-------|-------|
+| Button    | 12    | Checkout.tsx, Summary.tsx, ... |
+| Input     | 3     | PaymentForm.tsx |
+| Dialog    | 2     | ConfirmDialog.tsx, EditDialog.tsx |
+| Empty     | 1     | EmptyCart.tsx |
+| ProgressBar | 1   | UploadingBanner.tsx |
+| ScrollArea | 1    | ItemList.tsx |
+| ...       |       |       |
+```
+
+---
+
+## Token Inventory
+
+### CSS variable usage
+
+```bash
+grep -rohnE 'var\(--[a-z-]+\)' {target} | \
+  sort | uniq -c | sort -rn
+```
+
+### Semantic token utility class
+
+```bash
+grep -rohnE '\b(bg|text|border|fill|stroke|ring)-(primary|primary-hover|primary-subtle|primary-text|info|info-hover|info-subtle|info-text|error|error-hover|error-subtle|error-text|success|success-hover|success-subtle|success-text|warning|warning-hover|warning-subtle|warning-text|foreground|fg-secondary|fg-muted|fg-disabled|neutral-hover|neutral-active|neutral-selected|surface|surface-raised|canvas|muted|secondary|border|border-hover|divider|overlay|tooltip|notification|chart-[1-5])\b' {target} | \
+  awk -F: '{print $NF}' | sort | uniq -c | sort -rn
+```
+
+### 輸出 table
+
+```markdown
+## Tokens Used (24)
+
+| Token | Usage | Primary consumer |
+|-------|-------|------------------|
+| --primary | 8 | 主 CTA |
+| --fg-secondary | 14 | 次要文字 |
+| --error | 3 | 錯誤狀態 |
+| --surface-raised | 5 | Dialog / Popover bg |
+| ... | | |
+```
+
+---
+
+## Layout primitives 消費報告
+
+每類 primitive 用了幾次 + 哪些地方:
+
+```bash
+# Empty
+grep -rhnE '<Empty\b' {target} | wc -l
+
+# ScrollArea
+grep -rhnE '<ScrollArea\b' {target} | wc -l
+
+# AspectRatio
+grep -rhnE '<AspectRatio\b' {target} | wc -l
+
+# item-layout (MenuItem etc.)
+grep -rhnE '<(MenuItem|TreeItem|SidebarMenuButton|ItemIcon|ItemAvatar|ItemLabel|ItemSuffix)\b' {target} | wc -l
+
+# overlay-surface (Dialog/Popover auto consume)
+grep -rhnE '<(DialogHeader|DialogBody|DialogFooter|PopoverHeader|PopoverBody|PopoverFooter)\b' {target} | wc -l
+```
+
+輸出:
+
+```markdown
+## Layout primitives used
+
+| Primitive | Count | Note |
+|-----------|-------|------|
+| Empty     | 1     | EmptyCart.tsx |
+| item-layout | 5   | via MenuItem(3) / TreeItem(2) |
+| overlay-surface | 4 | via Dialog sub-components |
+| ScrollArea | 1    | ItemList.tsx |
+| AspectRatio | 0   | 本 feature 無 media container |
+| Horizontal-overflow | 0 | 本 feature 無水平溢出 |
+| Field-wrapper | 3  | via Input(3) |
+```
+
+---
+
+## A11y Checklist
+
+### 自動掃描(visible)
+
+```bash
+# icon-only 無 aria-label
+grep -rnE '(iconOnly|startIcon=\{)' {target} | \
+  xargs -I {} sh -c 'echo {} | grep -v "aria-label"'
+
+# 非 button 綁 onClick
+grep -rnE '<(div|span)[^>]*onClick=' {target}
+
+# Dialog 是否有 DialogTitle
+grep -rlE '<DialogContent>' {target} | \
+  xargs -I {} grep -L 'DialogTitle' {}
+```
+
+### 人工 review(本 skill AI 無法判)
+
+| Check | Status | Note |
+|-------|--------|------|
+| Color contrast WCAG AA | ? | 需 Storybook 視覺 + axe plugin |
+| Keyboard navigation tab order | ? | 需實際操作 |
+| Screen reader announce 正確 | ? | 需 VoiceOver / NVDA 測試 |
+| Focus trap 在 Modal 內 | ✓ | Radix 自動處理 |
+| Esc 關閉 Modal | ✓ | Radix 自動處理 |
+
+輸出:
+
+```markdown
+## A11y Status
+
+### Auto-scanned (visible issues)
+
+| Check | Status |
+|-------|--------|
+| icon-only 有 aria-label | ✓ 全過(12/12) |
+| 非 button 綁 onClick | ✓ 無 |
+| Dialog 有 Title | ✓ 2/2 |
+
+### Manual review needed
+
+- [ ] Color contrast(run axe in Storybook)
+- [ ] Keyboard navigation test
+- [ ] Screen reader test
+```
+
+---
+
+## 新增的元件 / token
+
+若 feature 過程中**新增**到 design-system/,在 inventory 特別標示:
+
+```markdown
+## New additions to DS (本 feature 過程新增)
+
+| Added | File | Motivation |
+|-------|------|-----------|
+| Coachmark | node_modules/@qijenchen/design-system/src/components/Coachmark/ | onboarding tour 需求 |
+| --chart-accent | node_modules/@qijenchen/design-system/src/tokens/color/semantic.css | data viz 擴充 |
+```
+
+讓 stakeholder 看得出「這 feature 帶動了 DS 擴充」的成本。
+
+---
+
+## 範本輸出順序
+
+inventory 結果編排:
+
+1. **Overview**(feature 規模:X screens / Y modals)
+2. **Components Used**(按 count 由高至低)
+3. **Tokens Used**(按 count 由高至低,分色 / 字 / 間距 / shadow 四類)
+4. **Layout primitives**(全表)
+5. **A11y**(auto + manual two tables)
+6. **New additions**(若有)
+
+如此 stakeholder 一分鐘可掃完,三分鐘可讀懂 feature 全景。

package/ds-canonical/fork/codex/agents/skills/independent-review/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: independent-review
+description: "Obtain an evidence-bound, read-only second opinion on product-consumer changes from a distinct certified peer provider without acquiring DS-author authority."
+---
+
+<!-- _generated: canonical provider skill projection; source: node_modules/@qijenchen/design-system/ds-canonical/skills/independent-review/SKILL.md + packages/governance/canonical/providers.json; do not edit this provider view. -->
+
+# independent-review — Codex adapter
+
+Read and follow the complete provider-neutral workflow at `node_modules/@qijenchen/design-system/ds-canonical/skills/independent-review/SKILL.md`. This file only resolves the provider binding; it must not redefine workflow meaning.
+
+## Resolved binding
+
+- `currentProvider: codex`
+- `reviewSelectionPolicy: highest-certified-independent-review-v1`
+- `reviewClass: tier-0-governance`
+- `independentPeerProvider: selected-and-frozen-at-review-prepare-time`
+- `transport: content-addressed-model-broker-exchange-v1`
+- `targetCertificationContract: exact-provider-runtime-surface-role-target-v1`
+- `sameProviderPeer: invalid`
+- `authorProviderRequired: true`
+- `authorProviderMustEqualCurrentProvider: true`
+- `independentReviewerMustDifferFromAuthor: true`
+- `reviewIsolation: separate-context-required`
+- `reviewMutation: read-only`
+- `reviewWorkspace: immutable-snapshot-or-enforced-tool-deny`
+- `mutationDetection: before-after-worktree-fingerprint`
+- `missingEvidenceOutcome: REVIEW-BLOCKED`
+- `compatibilityEvidence: packages/governance/canonical/providers.json#codex.skillBindings`
+
+## Required canonical references
+
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/independent-review/references/evidence-contract.md`
+
+
+## Adapter execution
+
+1. Require the author provider to be codex and resolve only a distinct reviewer through highest-certified-independent-review-v1/tier-0-governance.
+2. Verify an exact certified provider/runtime/surface/product-consumer target before claiming an independent second opinion.
+3. Freeze and digest the product scope, dispatch without author conclusions, and require a separate read-only context.
+4. Validate broker/transport evidence and before/after worktree fingerprints; emit findings only and never acquire DS-author, release, or mutation authority.
+
+Unavailable transport, same-provider execution, missing identity/evidence, incomplete coverage, absent isolation, or worktree drift is `REVIEW-BLOCKED`, never PASS.

package/ds-canonical/fork/codex/agents/skills/independent-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Independent Review"
+  short_description: "Read-only cross-provider product second opinion"
+  default_prompt: "Use $independent-review to obtain an evidence-bound read-only second opinion from a distinct provider."

package/ds-canonical/fork/codex/agents/skills/independent-review/references/evidence-contract.md

@@ -0,0 +1,23 @@
+# Independent-review evidence contract
+
+Use the transport selected by the generated provider binding. Do not invent a provider command, copy credentials into the repository, or create a second evidence schema.
+
+The model-broker execution layer (evidence broker, shard/transcript carriers, model runner, managed-CI executors) was retired 2026-08-04; broker or managed receipts are permanently rejected. The surviving authority-owned contract surfaces are `scripts/lib/deep-audit-evidence-contract.mjs` (waived self-review and entitlement review-lane validation) and `scripts/lib/model-api-transport.mjs` (pure invocation-profile and response-substitution contract). A product reviewer consumes their validated receipt but never edits, publishes, or executes authority release controls. If a validated receipt is unavailable, use `LOCAL-REVIEW-ONLY` or `REVIEW-BLOCKED`, never managed or certified evidence.
+
+A caller-supplied JavaScript callback, a self-declared model string, or structurally valid result
+JSON is not transport attestation and can never yield `REVIEW-VALIDATED`. An independent-review
+claim requires the entitlement review lane: a resolved provider binding whose peer, profile, and
+entitlement readback are certified for the exact target, with response substitution fail-closed.
+Without that binding the only honest outcomes are the waived self-review route (recorded waiver,
+self-attested coverage, `unverifiedModelCoverage` visible) or `REVIEW-BLOCKED`.
+
+Emit one closed review record in the response with:
+
+- outcome and evidence class;
+- author/current/peer provider, model release, context, transport, and exact target-certification identity;
+- repository, head, tree, diff, inventory, rubric, brief, and peer-output digests;
+- before/after worktree fingerprints and mutation verdict;
+- complete scope coverage, verified findings, rejected claims, unresolved disagreements, and unavailable evidence;
+- explicit role-boundary confirmation: no files, Git state, comments, external systems, releases, or upstream canonical sources were mutated.
+
+Missing fields or digest mismatch produce `REVIEW-BLOCKED`. The record is evidence about a review, not authorization to change or release anything.

package/ds-canonical/fork/codex/agents/skills/performance-audit/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: performance-audit
+description: Performance audit for design-system components and product UI. Checks render count, unnecessary re-renders, memoization gaps, bundle size impact, useEffect chains, context thrashing. Invoke when user says「這元件效能如何」「為什麼很卡」「bundle 變大」「re-render 太多」, auto-invoked by `/component-quality-gate` Phase 4.5 (advanced mode) and `/design-system-audit` Dimension D3.
+---
+
+<!-- _generated: canonical provider skill projection; source: skills/performance-audit/SKILL.md; provider: codex; do not edit this adapter view. -->
+
+> **Product-role projection(build 自動)**:本 skill 的執行步驟已只保留本 product repo 實際存在的指令。DS-author-only executor 會被改寫為 browser/manual/product-CI 等價驗證,不得在 product 中嘗試不存在的腳本。
+
+# Performance Audit — 元件效能稽核
+
+## 存在意義
+
+現有 `/design-system-audit`(全 dim per design-system-audit SSOT,code/spec 層)+ `/visual-audit`(pixel 層)**都不看效能**。render 次數過多、context 亂鋪、useEffect 鏈條過長這類 bug:
+- tsc 過、eslint 過、視覺正常
+- production 卡
+- 日常 dev 看不出來,到 stakeholder demo 才爆
+
+本 skill 作為稽核 6 維度的 **D3 元件效能** canonical home。
+
+## 觸發時機(對齊 shared governance 稽核 canonical)
+
+| 情境 | 模式 | 本 skill 跑什麼 |
+|------|------|----------------|
+| 新元件 merge 前 | 進階強制 | 全面(render count / memo / bundle) |
+| 元件新功能 | 進階強制 | 全面 scoped to 新 prop / variant |
+| 產品 demo 前 | 進階強制 | scoped to URL(常用頁 route) |
+| 日常 dev | 高效 | tsc pass + bundle diff 門檻即可 |
+| Release cut | 進階 + 全 DS scope | 全 DS render / memo / bundle 全跑 |
+
+## Preconditions
+
+- 元件 folder 存在於 `node_modules/@qijenchen/design-system/src/components/{Name}/`
+- `node_modules` 已安裝
+- Storybook 可啟動(用於 render-count 測量)
+
+## Workflow
+
+### Phase 0 — Scope 判定(一致性類必先全掃)
+
+- 若 scope = 單元件 → 走 Phase 1-3 對該元件
+- 若 scope = 全 DS / URL → **先全掃列出所有 hot path**(render 過多元件 / bundle 大元件 / context 亂鋪元件),Phase 1-3 按 impact 排序逐一 audit
+
+### Phase 1 — Render & re-render
+
+查 4 項:
+1. **Unnecessary re-render**:consumer 改 prop / state 時,本元件是否 re-render?`React.memo` 是否需要?
+2. **Inline 物件 / 函式 prop**:`style={{ ... }}` / `onClick={() => ...}` 每 render 造新 ref → child memo 失效
+3. **Context 粒度**:`<ThemeProvider value={theme}>` 若含頻繁變動 field(e.g. `openMenuId`)→ 整個 subtree 重渲。Context 必切分粒度或用 selector
+4. **Key 穩定性**:list items 用 `key={index}` 導致無意義 remount
+
+**工具**:
+- React DevTools Profiler record → 看 flame graph
+- `why-did-you-render` dev dep 觸發警告(**尚未落地**;trigger = 下一個 render-storm 類 bug 實例時一併引入,roadmap 殘項列冊)
+- 直接 grep pattern(inline style / arrow onClick)
+
+### Phase 2 — Memoization / dependency
+
+查 3 項:
+1. **useMemo / useCallback dep array**:遺漏 dep(stale closure)/ 多 dep(無效 memo)
+2. **useEffect dep array**:同上;特別注意 object / array dep(每 render 新 ref → 無限迴圈或無效 cleanup)
+3. **Computed value in render**:重計算 heavy op(sort / filter / 轉換) → 必 `useMemo`
+
+### Phase 3 — Bundle size
+
+查 3 項:
+1. **Direct heavy import**:`import * as Icons from 'lucide-react'`(全庫入 bundle) vs `import { Check } from 'lucide-react'`
+2. **Lazy-loadable portion**:Dialog / Sheet / Coachmark 等 rare-use overlay,可 `React.lazy` 減首屏
+3. **Duplicate dep**:`framer-motion` vs `motion/react` / 不同版本 react-day-picker 等
+
+**工具**:
+- `npx vite build --report`(vite bundle visualizer)
+- **bundle-size gate(已落地 2026-07-07)**:`npm run build`(budget SSOT = the product build/bundle budget configuration,total + top-8 entry 各 +10% headroom;governance check and protected product CI 內建必跑;蓄意增大 → `--init` 更新 budget + commit 說明)
+
+### Phase F — Report and route
+
+產出:
+
+```markdown
+# Performance Audit — {Scope} — {YYYY-MM-DD}
+
+## Summary
+- Render issues: N
+- Memoization gaps: M
+- Bundle impact: K KB
+
+## Findings(按 impact 排序)
+### P0: {title}
+- 位置: {file:line}
+- 現況: {render count / bundle contribution}
+- 建議: {具體修法}
+- 是工程／治理修實作(P2E auto)，還是產品／UI／UX SSOT 真取捨(P2H)?
+
+## Authority classification
+- P2E:{工程／治理 finding，交 canonical owner 自主修復}
+- P2H:{只有真正產品／UI／UX SSOT 取捨才列 exact target-bound decision}
+```
+
+本 skill 保持 read-only，report 是 evidence receipt；caller／canonical owner 對 P2E 直接接續
+修復與驗證，不把 read-only skill boundary 誤當 user checkpoint。只有 P2H 或
+shared-governance human-only boundary 才停止。
+
+## Non-goals
+
+- 不改 code / spec(純 read-only report)
+- 不做 micro-benchmark(10ms 以下差異不 report,噪音太多)
+- 不處理 network / backend(純前端 render / bundle)
+
+## 相關
+
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D3 補位
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/visual-audit/SKILL.md` — pixel 層(D5)
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/ux-audit/SKILL.md` — UX 行為層(D4)
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill

package/ds-canonical/fork/codex/agents/skills/product-ui-audit/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: product-ui-audit
+description: Audit product / consumer UI code (非 design-system 本身) against DS usage discipline + mindset adherence. Catches element misuse / design principle violations / token leakage / geometry bugs / a11y gaps across 7 dimensions. Invoke via /product-ui-audit when user says「audit 這個 UI」「檢查 X feature 用對 DS 嗎」「這段 code 符合設計原則嗎」,or auto-invoked by /prototype Phase 3.5 gate.
+---
+
+<!-- _generated: canonical provider skill projection; source: skills/product-ui-audit/SKILL.md; provider: codex; do not edit this adapter view. -->
+
+> **Product-role projection(build 自動)**:本 skill 的執行步驟已只保留本 product repo 實際存在的指令。DS-author-only executor 會被改寫為 browser/manual/product-CI 等價驗證,不得在 product 中嘗試不存在的腳本。
+
+# Product UI Audit Workflow
+
+Purpose: design-system-audit audits the **DS itself**(spec / cva / SSOT 三方漂移);product-ui-audit audits **consumer UI code**(不是 DS 本身,是 app / exploration / feature code — 即「consumer 用 DS 的地方」)。防止:
+
+- 元件亂用(wrong variant / missing props / incorrect composition)
+- 設計原則亂用(placeholder 文案 / 憑直覺創造 pattern / Mindset 違反)
+- Token 逃逸(硬寫 hex / shadcn alias 回流 / shadow-sm 繞過 elevation)
+- 幾何 bug(flex gap token 被 overflow 吃、slot box 不一致)
+- A11y 缺口
+
+## When to run
+
+**明確觸發(直接 invoke)**:
+- User 說「audit 這個 UI」「audit X feature」「檢查 /src/app/xxx」
+- User 說「這段 code 符合設計原則嗎」「DS 用對了嗎」「有元件亂用嗎」
+- `/prototype` Phase 3.5 自動 invoke(audit `src/explorations/{topic-slug}/`)
+- PR review 前自我檢查
+
+**不觸發**:
+- 要 audit DS 本身 → 走 `/design-system-audit`(不同 scope)
+- 要 audit token 定義 → 走 `design-system-audit`
+- 只要求補 stories → 直接補,不需 audit
+
+## 生態位
+
+```
+  /design-system-audit   audit DS 本身(設計系統內部)
+  /product-ui-audit      audit consumer UI code(本 skill)
+  /prototype             呼叫本 skill 作 Phase 3.5 gate
+  /delivery-handoff      只在產品交付前執行(產 handoff 文件)
+```
+
+## Preconditions
+
+- User 指定 audit target(file path / folder / feature area)
+- Target 是 consumer 層 UI code(`src/app/**` / `src/explorations/**` / `src/pages/**` / `src/features/**` / `apps/**`(含 DS repo 自家 `apps/template` + create-app 產物)等 — **不掃 `node_modules/@qijenchen/design-system/src/`**)
+- shared governance instructions 全讀(7 維 audit 都依此為基準)
+
+---
+
+## 7-Dimension Audit
+
+### Full-repository preflight(release / full or deep audit only)
+
+Feature-scoped UI audit 不擴張到無關檔案；但 release、full-repo 或 deep audit 必先依
+`node_modules/@qijenchen/design-system/ds-canonical/references/repository-hygiene.md` 完成一次
+Git-index + nonignored worktree inventory。若 authority repo 的 portable gate 可用，執行
+`perform the equivalent check described in the common product instruction (repository-hygiene-invariant.mjs is DS-author-only)`；否則依同一
+canonical 手動分類。未掛載的 registered repo 是 unobserved，不可寫成 PASS。
+
+每個 dimension 獨立檢查,產出 findings。詳細 grep pattern + rule 見 `references/audit-checks.md`。
+
+### Dim 1 — Token 紀律(token hygiene)
+
+- 硬寫 hex / rgb / rgba / hsl 色值
+- shadcn compat alias(bg-popover / text-muted-foreground / bg-accent / bg-destructive / bg-background / bg-card / border-input / text-primary-foreground / text-accent-foreground / text-card-foreground / text-popover-foreground)**(完整 deny-list SSOT:`node_modules/@qijenchen/design-system/src/tokens/utility-registry.json`;此處 inline 為 grep 便利,新增 alias 改 registry)**
+- Tailwind default shadow(shadow-sm / md / lg / xl / 2xl / inner)— 應走 elevation token
+- Tailwind v4 `[--foo]` shorthand 靜默失效
+- 硬寫 px 值當該用 token(`w-[48px]` 應改 token)
+
+此維對齊既有 token 防線(the installed immutable governance checker 5-check:shadcn alias / v4 shorthand / hardcoded shadow / primitive-color-as-utility / native overflow，由 the installed immutable governance checker source；+ the installed immutable governance checker 對齊 utility-registry.json 類別 — pattern hardcode 於 hook,registry 僅存在性 fallback gate)+ 擴充硬色值 / 硬 px 檢查。
+
+### Dim 2 — Layout primitive 消費(per shared governance 清單)
+
+掃是否正確消費既有 layout primitives(非自 roll):
+
+| 視覺 pattern | 應消費 | 違規 signal |
+|------|---------|---------|
+| icon+title+desc 垂直居中 | `<Empty>` | 自己寫 flex flex-col items-center 3-layer text |
+| row prefix+content+suffix | `item-layout` | 自己寫 flex items-center gap-2 3-slot |
+| overlay Header/Body/Footer | `overlay-surface` | 自己寫 border-b/border-t padding loose/tight |
+| 橫向按鈕列 | `action-bar` pattern | 自己 flex gap-2 按鈕組 |
+| 水平溢出 + fade mask | `horizontal-overflow` | 自己 overflow-x-auto + mask |
+| 跨 OS 一致捲軸 | `ScrollArea` | native `overflow-(auto\|scroll)` |
+| 圖像 / media 容器 | `AspectRatio` | 硬寫 `aspect-video` / `aspect-square` class |
+| Field wrapper | `Field` + `fieldWrapperStyles` | 自己 border + padding + startIcon + endAction |
+
+### Dim 3 — 元件使用正確性
+
+- Button / Input / Select 等 variant / size / props 組合合理
+  - icon-only 有 `aria-label`
+  - Button primary 沒堆疊(一個 row 一個 primary)
+  - Input 外有 Field wrapper(非 standalone input)
+- Composition 正確
+  - Popover 不放互動破壞(Dialog trigger in Popover content 避免)
+  - Accordion / Tabs / Carousel 不巢狀
+- Radix API 用對
+  - Dialog 有 DialogTitle / DialogDescription for a11y
+  - DropdownMenu 不當 Select 用
+
+### Dim 4 — Mindset adherence
+
+對齊 shared governance 6 條 mindset(逐條檢查 #1-#5;#6「大原則吸收瑣碎」屬 governance meta 層,不在 consumer code audit scope。編號用 mindset #N,避免撞 meta-patterns M-rules 編號):
+
+- **mindset #1 對標世界級**:新 pattern 有對標備註? 或找得到對應既有元件?
+- **mindset #2 不憑直覺發明**:新數值(gap / padding / font-size)前有 grep 既有?
+- **mindset #3 改一處看三處**:若改 DS 的 cva defaultVariants,spec / docblock / anatomy 三方同步?
+- **mindset #4 真實業務場景**:stories / examples 用真實場景 (Jira / Stripe / Notion...)?無 `Option A/B/C` / `按鈕一` / `Rule A`?
+- **mindset #5 先證據、再分權**:code 裡有 TODO-未確認留白?兩類都 flag——屬產品／UI／UX SSOT 真取捨 → 列入 user 決策清單;屬純工程 → 違反「依證據自主收斂」(工程不確定性不得留 TODO,應當場收斂)
+
+### Dim 5 — 視覺幾何(Mindset #1 視覺擴充 + `node_modules/@qijenchen/design-system/ds-canonical/references/ui-dev-rules.md`「同 flex 列互動 slot 幾何鐵律」)
+
+- 同 flex 行的互動 slot box 尺寸一致(例:FileItem status / delete 都 h-field-sm)
+- hover-bg / ring / focus outline 不溢出 box 吃 gap token
+- padding 對稱正確
+- Typography tier 正確(text-body / text-caption / etc.,不自造 `text-[13px]`)
+
+### Dim 6 — A11y
+
+- icon-only 元件有 `aria-label`
+- interactive element `role` 正確
+- Dialog / Popover / Sheet 有 title + description
+- keyboard navigation 可用(Tab / Enter / Esc)
+- color contrast(不用純 color 傳 state — 要 icon / label 配合)
+
+詳見 `references/audit-checks.md`。
+
+### Dim 7 — D6 設計原則自檢(consumer 是否牴觸 DS canonical)
+
+chain `node_modules/@qijenchen/design-system/ds-canonical/skills/design-system-audit/references/principle-audit-protocol.md` 做 4 子維 scoped 對 consumer code:
+
+- **D6a 合理性**:consumer 自己的設計判斷是否有 rationale(為什麼這樣用 DS 元件)
+- **D6b 一致性**:跨 feature 同概念處理一致(同 team 兩頁面 dismiss 不應用不同方式)
+- **D6c 無矛盾**:consumer 實作是否牴觸 DS spec 聲明(例:用 Button 作 dismiss 明顯違 item-anatomy SSOT)
+- **D6d 完整性**:state 覆蓋(error / loading / empty)
+
+判斷 auto vs STOP 依 protocol 的 authority classifier。修 consumer code 一致化、工程 bug、
+a11y、performance 與治理修復 = AUTO；只有建議會改變產品／UI／UX SSOT 且存在真實取捨時
+才 STOP 提議。修改 DS canonical 本身不自動等於 human gate。
+
+---
+
+## Workflow
+
+### Phase 0 — Scope
+
+從 explicit request、目前 frozen scope、changed paths 與 registered feature owner 解析 audit
+target(file / folder / feature area)。工程範圍模糊時選最小完整 affected scope 並記錄 rationale；
+只有不同 scope 會導致真正產品／UI／UX SSOT 取捨時才提問 user。禁止無 evidence 掃整個 repo
+(失焦)，也禁止把可由 repository evidence 解出的 scope 轉交 user。
+
+### Phase 1 — Parallel 7-Dimension audit
+
+7 個維度各自獨立 grep + code review。可 parallelize。
+
+### Phase 2 — Report
+
+產出 report 表格:
+
+```
+| Dim | File:Line | Finding | Severity | Fix suggestion |
+|-----|-----------|---------|----------|----------------|
+| 1 Token | src/app/foo.tsx:42 | 硬寫 `#3b82f6` | P0 | 改 var(--primary) |
+| 2 Layout | src/app/bar.tsx:87 | 自己寫 icon+title+desc 垂直堆疊 | P1 | 改用 `<Empty>` |
+| 3 Component | src/app/baz.tsx:12 | icon-only Button 無 aria-label | P0 | 加 aria-label |
+| ... |
+```
+
+### Checkpoint 1 — Triage evidence receipt
+
+類似 design-system-audit 的 triage checkpoint:
+
+```
+🔍 Audit 結果
+
+P0(必修,無爭議):N 項
+P1(批次修 + review):M 項
+P2E(工程／治理，自主修):K 項
+P2H(產品／UI／UX SSOT 真取捨):J 項
+
+P0/P1/P2E 依 frozen scope 自主修；只有 P2H 要 exact target-bound user decision。
+```
+
+詳見 `references/report-template.md`。
+
+### Phase 3 — Fix
+
+P0/P1/P2E 依 Standing Authorization surgical 修復；每批(Dim 1 / Dim 2 / ...)一個
+可驗證 change set。P2H 在 exact decision 前保持 proposal-only。
+
+### Phase 4 — Verify
+
+- `npx tsc -b` 無錯(禁 `--noEmit` — root tsconfig `files: []` silent pass;動型別 surface 加跑 `npm run build`,對齊 component-quality-gate + self-verify.md)
+- re-run 本 skill(縮窄到原 findings)確認 zero regression
+
+### Phase 5 — Visual audit(stakeholder-gate,mandatory on stakeholder-visible work)
+
+對齊 **shared governance 稽核 canonical Tier 1 stakeholder-gate**:產品 UI 要給 stakeholder / end-user 看之前,**code + visual 雙層都要過**。Phase 1-4 是 code 層;本 Phase 補視覺層。
+
+**Input**:Phase 4 verify 過關的產品 UI(screens / routes / embedded widgets)
+
+**Process**:
+1. 確認 user 有提供 **URL 清單**(產品 app routes)或 **Storybook scenario id**(若產品 stories 在 Storybook):
+   - URL mode:`use the active browser/Storybook screenshot workflow and preserve visual evidence`(例:`--urls=http://localhost:3000/inbox,http://localhost:3000/settings`)
+   - Storybook mode:`use the active browser/Storybook screenshot workflow and preserve visual evidence`
+2. **Layer A mechanical**(auto):WCAG 對比度 + DOM 幾何 assertion + 1x screenshot(retina 需 `--retina` opt-in)→ `snapshots/`
+3. **Layer B AI judgement**(chain `/visual-audit` skill):讀 `snapshots/*.png`,判斷設計合理性(視覺對齊 / 覆蓋限制 / 世界級對照 / typography hierarchy)
+4. Violation 分級:
+   - Contrast AA 不過 → **P0**(a11y 強制)
+   - Geometry assertion fail → **P0**(機械規則違反)
+   - Layer B AI 視覺判斷 finding → 按嚴重度 P0 / P1 / P2
+
+**Gate 規則**:P0 有 → 停下修,不放給 stakeholder；P1/P2E 自主修復與驗證；只有
+P2H 產品／UI／UX SSOT 真取捨走 exact target-bound user-decision 流程。
+
+**何時可縮窄**:內部 UI(只給 engineer / admin 看,非 stakeholder / end-user)可依
+canonical scope evidence 縮窄 Layer B，但 Layer A a11y P0 不得省略；這是工程判斷，
+不是 user approval gate。
+
+**為什麼 mandatory**:code audit 對 + spec 對,視覺仍可能錯(對比不夠、overlay 疊到文字、跨 OS 捲軸跑版)——這類 bug 只有視覺層抓得到。產品給 stakeholder / user 看時 = stakeholder-visible artifact,必過 Tier 1 gate。
+
+---
+
+## 呼叫時的回答格式
+
+audit 完畢報告應含:
+1. **Scope**:audit 了什麼(path / file 數量)
+2. **Summary**:per dimension 的 pass/fail 數
+3. **Findings table**:具體 file:line + severity + fix
+4. **Recommendations**:P0 優先 / 建議修順序
+5. **Next step**:列出已自主處理的 P0/P1/P2E；只有 P2H 才列唯一需要的 user decision
+
+---
+
+## Non-goals
+
+- 不 audit DS 本身(走 /design-system-audit)
+- 不把 P1/P2 severity 當成 human gate；依 P2E/P2H authority class 處理。
+- 不 audit 業務邏輯正確性(本 skill 管 UI / DS consumption / design principles,不管 data flow 對不對)
+- 不 replace code review(本 skill 是 pre-review self-check,不是 final QA)
+
+## Common failure modes
+
+- **Scope 模式混淆**:feature audit 才限制到指定 folder；release/full/deep audit 必依 preflight 全 repo、NO-SAMPLE 掃完，再以 severity/authority 分批 remediation，不得用「finding 太多」縮 scope
+- **Dim 間互相矛盾**:Dim 2 建議用 Empty 但 Dim 3 說 Button 該在某處 — surface 而非自己選
+- **P0/P1 分類偏誤**:把明確 bug 當 P1 / 把 style preference 當 P0 — 嚴格按 audit-checks.md 分類
+- **把所有 P2 當 human gate**:severity 不等於決策 authority；P2E 工程／治理 remediation 自主完成，只有 genuine product/UI/UX SSOT 取捨的 P2H 才停下請 user 拍板
+
+## References
+
+- [references/audit-checks.md](references/audit-checks.md) — 7 維度具體 grep pattern + rule
+- [references/common-misuses.md](references/common-misuses.md) — 常見元件誤用 negative example 庫
+- [references/report-template.md](references/report-template.md) — P0/P1/P2 severity 分類 + report 格式