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

package/ds-canonical/skills/product-ui-audit/references/audit-checks.md

@@ -0,0 +1,246 @@
+# Audit Checks — 6 維度 grep pattern + rule
+
+每個維度的具體 check。AI Phase 1 parallel 執行時依此 grep + rule 判斷。
+
+---
+
+## Dim 1 — Token 紀律
+
+### Check 1.1: shadcn compat alias
+
+```
+grep -nE '\b(bg-popover|text-popover-foreground|text-muted-foreground|bg-accent|text-accent-foreground|bg-destructive|bg-background|bg-card|text-card-foreground|border-input|text-primary-foreground)\b' {target}
+```
+
+**Severity**: P0。**Fix**: 對映見 `check_token_hygiene.sh` hook。
+
+### Check 1.2: Tailwind default shadow
+
+```
+grep -nE '\bshadow-(sm|md|lg|xl|2xl|inner)\b' {target}
+```
+
+**Severity**: P0。**Fix**: shadow-sm → shadow-[var(--elevation-100)] / shadow-md → shadow-[var(--elevation-200)] / shadow-lg → shadow-[var(--elevation-300)]。
+
+### Check 1.3: Tailwind v4 `[--foo]` shorthand
+
+```
+grep -nE '\[--[a-z][a-z0-9-]*\]' {target} | grep -v '\[&'
+```
+
+**Severity**: P0(silent fail)。**Fix**: `[--foo]` → `[var(--foo)]`。
+
+### Check 1.4: 硬寫 hex / rgb / hsl
+
+```
+grep -nE '#[0-9a-fA-F]{3,8}\b|rgb\(|rgba\(|hsl\(|hsla\(' {target}
+```
+
+**Severity**: P0。**Exception**: `#fff` 在 Avatar / Tag 白字變體是 documented cva exception(object map 非 cva,per CLAUDE.md `cva 適用範圍`);anatomy inspector chrome 顏色 highlight(`bg: 'rgba(...)'` in `.anatomy.stories.tsx`)。**Fix**: 改 semantic token(`var(--primary)` / `bg-primary` 等)。
+
+### Check 1.5: 硬寫 px 當應用 token
+
+```
+grep -nE 'w-\[\d+px\]|h-\[\d+px\]|text-\[\d+px\]|gap-\[\d+px\]|p-\[\d+px\]' {target}
+```
+
+**Severity**: P1(需 case-by-case 判斷)。**Rule**: 若有對應 field-height / layout-space / icon-size token,應改 token;若是 genuinely unique 尺寸則保留 + spec 解釋。
+
+---
+
+## Dim 2 — Layout primitive 消費
+
+### Check 2.1: icon+title+desc 垂直居中 → 應消費 Empty
+
+```
+# grep for potential misuse patterns
+grep -nE 'flex.*flex-col.*items-center.*text-center' {target}
+```
+
+對每 hit,檢查是否有:
+- LucideIcon 置頂 + title + desc(3-layer vertical stack)
+- 且 parent 是**空狀態 / 空目錄 / 無資料 / 拖放區 / 首次引導**等語境
+
+**Severity**: P1。**Fix**: `<Empty icon={Icon} title="..." description="..." />`。
+
+### Check 2.2: row prefix+content+suffix → 應消費 item-layout
+
+```
+grep -nE 'flex.*items-center.*gap-2' {target}
+```
+
+對每 hit,檢查是否是:
+- 單列 row with icon/avatar 左 + content 中 + action 右
+- 且是 menu / list / tree / file 類項目
+
+**Severity**: P1。**Fix**: 消費 `MenuItem` / `TreeItem` / `SidebarMenuButton` 等既有 row primitive(或組合 item-anatomy 的 slot components `<ItemIcon>` / `<ItemLabel>` / `<ItemSuffix>` 等)。
+
+### Check 2.3: overlay Header/Body/Footer → 應消費 overlay-surface
+
+```
+grep -nE 'border-b border-divider.*px-\[var\(--layout-space-loose\)\]' {target}
+grep -nE 'border-t border-divider.*px-\[var\(--layout-space-loose\)\]' {target}
+```
+
+若在 Dialog / Popover / Sheet / Drawer consumer 重複寫這個 pattern → flag。
+
+**Severity**: P1。**Fix**: 用 `<SurfaceHeader>` / `<SurfaceBody>` / `<SurfaceFooter>` 或 Dialog 的 sub-components。
+
+### Check 2.4: native overflow-(auto|scroll) → 應用 ScrollArea
+
+```
+grep -nE '\boverflow-(auto|scroll|x-auto|x-scroll|y-auto|y-scroll)\b' {target} | grep -vE 'scrollbar-none|useOverflow|horizontal-overflow'
+```
+
+**Severity**: P1(跨 OS drift)。**Fix**: 改用 `<ScrollArea>`;若是刻意隱藏 + fade-mask 改用 `horizontal-overflow` pattern。
+
+### Check 2.5: 硬寫 aspect-* → 應用 AspectRatio
+
+```
+grep -nE '\baspect-(video|square|\[[\d/]+\])' {target}
+```
+
+**Exception**: icon-only Button 以 `aspect-square w-X` 形成正方形 hit area(如 Sidebar trigger)屬幾何 layout 不是 media container,保留。
+
+**Severity**: P2(主要影響:未來 ratio 變化時漂移)。**Fix**: media/image container 改用 `<AspectRatio ratio={n}>`。
+
+### Check 2.6: Field wrapper 缺失
+
+```
+grep -nE '<input(?![^>]*ref=)' {target}
+```
+
+裸 `<input>` 未包 Field / fieldWrapperStyles → flag。
+
+**Severity**: P1。**Fix**: 包 Field 或消費 Input 元件。
+
+---
+
+## Dim 3 — 元件使用正確性
+
+### Check 3.1: icon-only 無 aria-label
+
+```
+grep -nE '(iconOnly|startIcon|ItemInlineAction)' {target}
+```
+
+每 hit 檢查同行或附近有 `aria-label=` / `label=`。
+
+**Severity**: P0(a11y 必要)。**Fix**: 加 `aria-label="..."`。
+
+### Check 3.2: Primary Button 堆疊
+
+```
+grep -nE 'variant="primary"' {target}
+```
+
+若同一 parent 出現多個 primary Button → flag(每 row 應只一個 primary action)。
+
+**Severity**: P1。**Fix**: 次要 action 改 tertiary / secondary。
+
+### Check 3.3: Dialog / Popover / Sheet 缺 title / description
+
+```
+grep -nE '<DialogContent>|<PopoverContent>|<SheetContent>' {target}
+```
+
+每 hit 追蹤 children 是否含 DialogTitle / DialogDescription。
+
+**Severity**: P0(Dialog a11y 必要)/ P1(Popover, 可選但建議)。**Fix**: 加 Title / Description(Radix 已提供)。
+
+### Check 3.4: 巢狀 Accordion / Tabs / Carousel
+
+```
+grep -nE '<(Accordion|Tabs|Carousel)' {target}
+```
+
+檢查是否有同名元件巢狀(兩層以上)。
+
+**Severity**: P1(UX 使用者迷失)。**Fix**: flatten 結構或改用 TreeView。
+
+---
+
+## Dim 4 — Mindset adherence
+
+### Check 4.1: placeholder 文案(M4 違反)
+
+```
+grep -nE '(Option [A-E]|按鈕[一二三四五]|Rule [A-E]|Variant [A-E]|Placeholder|Lorem ipsum|Foo|Bar|Test value)' {target}
+```
+
+**Severity**: P1(違反 Mindset #4 「真實業務場景」)。**Fix**: 改真實 SaaS 場景(Jira / Stripe / Notion / Linear / Figma)。
+
+### Check 4.2: TODO-未確認留白(M5 違反)
+
+```
+grep -nE '(TODO:\s*待確認|TODO:\s*decide|FIXME|XXX)' {target}
+```
+
+**Severity**: P2(必討論)。**Fix**: 若是規格未定應 surface 給 user 決策,不在 code 留模糊 TODO。
+
+### Check 4.3: cva defaultVariants 三方漂移(M3)
+
+**適用情境**: 若 consumer 在 app 層 override cva 的 defaultVariants(罕見但發生過),檢查是否同步 spec / docblock / anatomy。
+
+---
+
+## Dim 5 — 視覺幾何
+
+### Check 5.1: 同 flex 行互動 slot box 尺寸不一
+
+**手動 review pattern**: 找 `flex items-center gap-*` 包含多個 interactive element(Button / ItemInlineActionButton / Link),確認他們的 box 尺寸一致。
+
+例: FileItem `status slot(16px)` + `delete Button sm(28px)` = 不一致 → hover-bg 吃 gap。
+
+**Severity**: P0(世界級 DS 鐵律違反,違反 CLAUDE.md「同 flex 列的互動 slot 幾何鐵律」)。
+
+### Check 5.2: 自造 typography tier
+
+```
+grep -nE 'text-\[\d+px\]' {target}
+```
+
+用 `text-[13px]` 等自造尺寸 → flag。
+
+**Severity**: P1。**Fix**: 改用 DS typography utility(text-caption / text-body / text-body-lg / h1 / h2 等)。
+
+---
+
+## Dim 6 — A11y
+
+### Check 6.1: icon-only 無 aria-label(已含 Check 3.1)
+
+### Check 6.2: 非 button 用 onClick
+
+```
+grep -nE '<(div|span)[^>]*onClick='
+```
+
+非 `<button>` 元素綁 onClick → flag(缺 keyboard / screen reader)。
+
+**Severity**: P0。**Fix**: 改 `<button>` 或加 `role="button" tabIndex={0} onKeyDown={...}`。
+
+### Check 6.3: color 作唯一 state signal
+
+**手動 review**: 只用紅色 / 綠色 傳 error / success 無 icon 或 label → 色盲不可辨。
+
+**Severity**: P1(WCAG 1.4.1 違反)。**Fix**: 色 + icon 雙通道(CheckCircle / XCircle 等)。
+
+### Check 6.4: keyboard 陷阱
+
+**手動 review**: Modal 內 focus 能 loop(tab 出去要能回來);esc 能關;Arrow keys 導航 list。
+
+**Severity**: P0 若為 Modal / Dialog。**Fix**: 用 Radix primitives(已內建 focus trap)。
+
+---
+
+## 合法例外(documented)
+
+以下 hit 不是 bug,由既有 spec / CLAUDE.md 記錄為合理例外:
+
+- **Avatar 白字**(`text: '#fff'`): cva 適用範圍例外(style prop 驅動用 object map 而非 cva),per `cva 適用範圍` 章節。
+- **Anatomy inspector chrome**(`bg: 'rgba(...)'` in `.anatomy.stories.tsx`): dev-tool highlight 非 consumer UI token。
+- **Rating yellow stars**(`bg-warning` 黃星): 世界級 convention(Amazon / Google / Yelp 皆黃),spec line 73 明文 documented exception。
+- **uiSize icon-only button**(`aspect-square w-X`): 幾何性 square,非 media container,per uiSize.spec.md「calc 不用 aspect-square」主體邏輯。
+
+遇到 hit 時檢查是否屬上述 documented exception,若是則不 flag,否則 flag。

package/ds-canonical/skills/product-ui-audit/references/common-misuses.md

@@ -0,0 +1,329 @@
+# Common Misuses — 元件誤用 negative example 庫
+
+針對本 DS 常見的元件誤用 pattern。每筆:**誤用 → 正解 → 理由**。
+
+---
+
+## Button 誤用
+
+### ❌ 多個 primary Button 並列
+
+```tsx
+<div className="flex gap-2">
+  <Button variant="primary">儲存</Button>
+  <Button variant="primary">下載</Button>
+  <Button variant="primary">分享</Button>
+</div>
+```
+
+**正解**:一個 row 一個 primary,其他降階。
+
+```tsx
+<div className="flex gap-2">
+  <Button variant="primary">儲存</Button>
+  <Button variant="tertiary">下載</Button>
+  <Button variant="tertiary">分享</Button>
+</div>
+```
+
+**理由**:primary 是「這個流程的主 CTA」,多個 primary 會讓使用者不知該點哪個。
+
+### ❌ icon-only 無 aria-label
+
+```tsx
+<Button iconOnly startIcon={Trash} />  // ❌
+```
+
+**正解**:`aria-label="刪除"`。screen reader 必要。
+
+### ❌ Button 巢狀
+
+```tsx
+<Button onClick={outer}>
+  外層
+  <Button>內層</Button>  {/* ❌ 巢狀 button invalid HTML */}
+</Button>
+```
+
+**正解**:拆成兩個 sibling Button 或 inline ItemInlineAction。
+
+---
+
+## Field / Input 誤用
+
+### ❌ 裸 `<input>` 未包 Field wrapper
+
+```tsx
+<input type="text" className="border rounded p-2" />  {/* ❌ */}
+```
+
+**正解**:用 `<Input>` 元件或包 Field wrapper。
+
+**理由**:DS `<Input>` 已帶 fieldWrapperStyles(hover / focus / error / disabled 狀態全套),自 roll `<input>` 失去一致性。
+
+### ❌ Input 外層自訂 border / padding
+
+```tsx
+<div className="border-2 border-primary p-3 rounded-xl">
+  <Input />
+</div>
+```
+
+**正解**:用 Input 的 `error` prop 或 cva variant,不自套 wrapper。
+
+---
+
+## Dialog / Popover / Sheet 誤用
+
+### ❌ Dialog 內放 Popover(巢狀浮層)
+
+```tsx
+<Dialog>
+  <DialogContent>
+    <Popover>...</Popover>  {/* ❌ 浮層巢狀不推薦 */}
+  </DialogContent>
+</Dialog>
+```
+
+**正解**:改用 Dialog 內 Tabs / Accordion / SelectMenu 等 inline 結構。
+
+### ❌ Dialog 無 DialogTitle
+
+```tsx
+<DialogContent>
+  <p>確定刪除?</p>
+  <Button>確定</Button>
+</DialogContent>
+```
+
+**正解**:必有 DialogTitle + DialogDescription(a11y 必要)。
+
+```tsx
+<DialogContent>
+  <DialogHeader><DialogTitle>刪除專案?</DialogTitle></DialogHeader>
+  <DialogBody><p>此動作無法復原</p></DialogBody>
+  <DialogFooter>
+    <Button variant="tertiary">取消</Button>
+    <Button variant="primary">確定刪除</Button>
+  </DialogFooter>
+</DialogContent>
+```
+
+### ❌ Popover 當 Tooltip 用
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <button>hover me</button>
+  </PopoverTrigger>
+  <PopoverContent>提示文字</PopoverContent>
+</Popover>
+```
+
+**正解**:Tooltip 元件。Popover 是 click 觸發互動面板,Tooltip 是 hover 觸發純文字提示。
+
+---
+
+## Empty / 空狀態誤用
+
+### ❌ 自寫 flex+icon+title+desc 垂直居中
+
+```tsx
+<div className="flex flex-col items-center text-center gap-2 py-12">
+  <FileSearch size={48} className="text-fg-muted" />
+  <div className="text-body-lg font-medium">沒有符合的結果</div>
+  <div className="text-body text-fg-secondary">請調整篩選條件</div>
+  <Button>重設篩選</Button>
+</div>
+```
+
+**正解**:
+
+```tsx
+<Empty
+  icon={FileSearch}
+  title="沒有符合的結果"
+  description="請調整篩選條件"
+  action={<Button>重設篩選</Button>}
+/>
+```
+
+**理由**:Empty 元件 own icon size(Avatar 48px)/ typography tier / gap token。自寫 drift 風險。
+
+---
+
+## Skeleton / CircularProgress / Empty 混用
+
+### ❌ Loading 狀態用 Empty
+
+```tsx
+{isLoading && <Empty description="Loading..." />}  {/* ❌ */}
+```
+
+**正解**:Skeleton(骨架)或 CircularProgress(不知時長,indeterminate)。Empty 是「確認無資料」。全頁 loading 可 `<Empty icon={<CircularProgress size={48}/>} title="載入中" />`。
+
+### ❌ Error 狀態用 Empty
+
+```tsx
+{error && <Empty description="載入失敗" />}  {/* ❌ */}
+```
+
+**正解**:`<Alert variant="error">`。Empty 是中性空(可能有操作解除),Error 是需處理的問題。
+
+---
+
+## ProgressBar / CircularProgress 混用
+
+### ❌ 不知進度硬套 ProgressBar(value=0 / 亂跳)
+
+```tsx
+<ProgressBar value={isLoading ? 30 : 100} />  // ❌ 進度無法量化
+```
+
+**正解**:`<CircularProgress>`(不傳 value)做 indeterminate。ProgressBar 是 determinate。
+
+### ❌ 已知百分比的大區塊進度用 CircularProgress indeterminate
+
+```tsx
+<CircularProgress />  {/* 明明已知 45% */}
+```
+
+**正解**:大區塊 / 頁面級用 `<ProgressBar value={45} affix="value" />`;inline 小空間用 `<CircularProgress value={45} affix="value" />`。
+
+---
+
+## Tabs / Accordion / Carousel 誤用
+
+### ❌ Tabs 切換「獨立功能」而非平行視圖
+
+```tsx
+<Tabs>
+  <TabsTrigger value="settings">設定</TabsTrigger>
+  <TabsTrigger value="logout">登出</TabsTrigger>  {/* ❌ 登出是 action 不是 tab */}
+</Tabs>
+```
+
+**正解**:登出走 DropdownMenu 或獨立 Button。Tabs 是「切平行內容視圖」。
+
+### ❌ Accordion 內巢狀 Accordion
+
+```tsx
+<Accordion>
+  <AccordionItem>
+    <AccordionContent>
+      <Accordion>...</Accordion>  {/* ❌ */}
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+**正解**:改用 TreeView(有階層語意)或 flatten。
+
+### ❌ Carousel 當資料切換器用
+
+```tsx
+<Carousel>
+  <CarouselItem>總覽</CarouselItem>
+  <CarouselItem>成員</CarouselItem>
+  <CarouselItem>設定</CarouselItem>
+</Carousel>
+```
+
+**正解**:`<Tabs>`。Carousel 是輪播同類內容(圖片組 / testimonial),不是命名視圖切換。
+
+---
+
+## Coachmark / Dialog / Popover 用錯場景
+
+### ❌ 確認破壞性 action 用 Coachmark
+
+```tsx
+<Coachmark title="確定刪除?" onNext={del}>
+  <Button variant="primary" danger>刪除</Button>
+</Coachmark>
+```
+
+**正解**:`<Dialog>`。Coachmark 是 non-modal onboarding(使用者可忽略),Dialog 是 modal 阻斷(必須處理)。
+
+### ❌ 錯誤訊息用 Coachmark
+
+```tsx
+<Coachmark title="載入失敗" description="網路異常" />
+```
+
+**正解**:`<Alert variant="error">` 或 `<Notice>` (非浮層)/ Toast(非阻斷)。Coachmark 是主動推送功能介紹,不是錯誤回報。
+
+---
+
+## ScrollArea / Native overflow 混用
+
+### ❌ Consumer 內 DataTable 水平捲動用 native overflow-x-auto
+
+```tsx
+<div className="overflow-x-auto">
+  <DataTable columns={...} data={...} />
+</div>
+```
+
+**正解**:`<ScrollArea orientation="horizontal">` 包(跨 OS 一致)。
+
+```tsx
+<ScrollArea>
+  <DataTable columns={...} data={...} />
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>
+```
+
+---
+
+## AspectRatio / 硬寫 aspect-* 混用
+
+### ❌ media 容器硬寫 `aspect-video`
+
+```tsx
+<div className="aspect-video bg-muted">
+  <img src={url} />
+</div>
+```
+
+**正解**:
+
+```tsx
+<AspectRatio ratio={16 / 9} className="bg-muted">
+  <img src={url} className="w-full h-full object-cover" />
+</AspectRatio>
+```
+
+**理由**:`AspectRatio` 是 SSR-safe padding-bottom 方案,跨 OS / 未載入時穩定。硬寫 class 在某些邊緣瀏覽器失效。
+
+---
+
+## 色彩誤用
+
+### ❌ primary 當狀態色用(Mindset #1 違反)
+
+```tsx
+<ProgressBar className="bg-primary" value={60} />  {/* ❌ 除非就是進度 */}
+<Tag className="bg-primary">進行中</Tag>            {/* ❌ 應用 info */}
+```
+
+**正解**:進行中用 info,操作入口用 primary。
+
+```tsx
+<Tag className="bg-info-subtle text-info-text">進行中</Tag>
+<Button variant="primary">開始</Button>
+```
+
+### ❌ 硬寫 Tailwind 預設色
+
+```tsx
+<div className="text-red-500 bg-blue-100">  // ❌
+```
+
+**正解**:改 semantic token(text-error / bg-info-subtle)。
+
+---
+
+## 此清單如何擴充
+
+每次 audit 發現新 misuse pattern,append 到本檔。保留 negative example + 正解 + 理由 3 段格式。