| name | quality-gate |
| description | 前端品質閘門。自動檢查 SEO、無障礙、效能模式、UI/UX 基線。編輯 .tsx/.css 後自動觸發,push 前強制執行。修復找到的問題,不做架構變更。 |
| source | self |
| updated | "2026-04-07T00:00:00.000Z" |
Quality Gate (前端品質閘門)
When to Use
在以下情況自動觸發(hook 驅動,不需手動):
- 編輯
.tsx / .css / .html 檔案後(PostToolUse hook)
git push 前(PreToolUse hook,blocking)
也可以手動執行 /quality-gate 做完整檢查。
檢查清單
1. SEO (Search Engine Optimization)
grep -r "metadataBase" src/app/layout.tsx
grep -r "openGraph" src/app/layout.tsx
grep -r "robots" src/app/layout.tsx
ls public/robots.txt
ls public/sitemap.xml
ls public/favicon.svg public/favicon.ico
修復規則:
metadataBase 必須設定為正式網域(不能是 localhost)
- OG image 路徑必須存在於 public/
- description 不超過 160 字元
2. Accessibility (無障礙)
Semantic HTML 檢查:
grep -rn "<header" src/components/
grep -rn "<main" src/
grep -rn "<nav " src/components/
grep -rn "<footer" src/components/
ARIA 檢查:
grep -rn "<button" src/components/ | grep -v "aria-label\|>{.*}<"
grep -rn "<Input\|<input" src/components/ | grep -v "aria-label\|<label"
grep -rn "setLocale\|locale" src/components/ | grep "button" | grep -v "aria-pressed"
Focus 檢查:
grep -rn "focus-visible" src/components/
修復規則:
- 每個互動元素必須可用鍵盤操作
- touch target >= 28px (7 * 4px grid)
- 色彩對比 WCAG AA (4.5:1 一般文字, 3:1 大文字)
3. Performance (效能)
grep -rn "<img " src/
grep -rn "next/image" src/
grep -rn "will-change" src/app/globals.css
grep -rn "contain:" src/app/globals.css
grep -rn "font-display\|next/font" src/
修復規則:
- 靜態圖片用
next/image + width/height + alt
- CSS 動畫用
transform / opacity,不用 top/left
- 紋理/背景固定層加
contain: strict
4. UI/UX 基線
grep -rn "back-to-top\|BackToTop\|scrollTo.*top" src/
grep -rn "noResults\|no.*found\|empty" src/components/
grep -rn "loading\|skeleton\|Suspense" src/
修復規則:
- 可滾動頁面 > 2 個 viewport 高度 → 必須有 Back to Top
- 所有篩選/搜尋必須有空狀態提示
- 外部連結必須有
target="_blank" rel="noopener noreferrer"
5. Reliability (穩定度)
grep -rn "\\b!\\." src/ --include="*.tsx" --include="*.ts" | grep -v "node_modules\|!="
grep -rn "localStorage\|sessionStorage" src/ | grep -v "typeof window"
grep -rn "ErrorBoundary\|error\\.tsx" src/
修復規則:
- 用 optional chaining (
?.) 取代 !.
localStorage 存取包在 typeof window !== 'undefined' 裡
- 根層級應有 error.tsx(Next.js App Router)
執行流程
- 跑上述所有 grep 檢查
- 列出問題清單(檔案:行號 + 問題描述)
- 按嚴重度排序:blocking > warning > info
- 逐一修復 blocking 問題
- 報告 warning(不自動修)
Blocking vs Warning
| 嚴重度 | 問題 | 動作 |
|---|
| Blocking | 缺 metadataBase、缺 aria-label on button/input、非 null assertion | 自動修復 |
| Warning | 缺 sitemap、缺 error.tsx、原生 img 標籤 | 報告,不擋 push |
| Info | 缺 JSON-LD、缺 canonical per page | 報告 |
6. Security (安全性)
grep -rn "sk-\|AKIA\|ghp_\|password\s*=\s*['\"]" src/ --include="*.tsx" --include="*.ts"
grep -rn "dangerouslySetInnerHTML" src/ --include="*.tsx" | grep -v "DOMPurify\|sanitize"
grep -rn 'target="_blank"' src/ --include="*.tsx" | grep -v "noopener"
grep -rn "<form" src/ --include="*.tsx" | grep -v "csrf\|token"
grep -rn "eval(\|new Function(" src/ --include="*.tsx" --include="*.ts"
修復規則:
- 機敏資料一律走環境變數(
.env.local),不硬編碼
dangerouslySetInnerHTML 必須搭配 DOMPurify
- 所有
target="_blank" 加 rel="noopener noreferrer"
- 禁止
eval() 和 new Function()
7. Architecture Documentation (SA/SD 同步)
每個專案必須有以下文件,且內容與程式碼一致:
| 文件 | 適用 | 必要內容 |
|---|
CLAUDE.md | 所有專案 | 專案概述、技術架構表、目錄結構、開發注意事項、後端位置(如分離) |
.interface-design/system.md | 前端專案 | 色彩 token、字型、間距、圓角、元件模式、手刻元件清單、禁止事項 |
openspec/ | 所有專案 | 變更管理(非架構文件,但必須存在) |
test -f CLAUDE.md
test -f .interface-design/system.md || test -f wireframes/cis-design-tokens.html
grep -oE 'src/[a-zA-Z0-9_/-]+' CLAUDE.md | sort -u | while read dir; do
[ -d "$dir" ] || [ -f "$dir" ] || echo "MISSING: $dir"
done
git diff --cached --diff-filter=ADR --name-only | head -10
git diff --cached --name-only | grep CLAUDE.md
修復規則:
- 新增元件/模組 → 更新 CLAUDE.md 目錄結構 + system.md 元件清單
- 刪除元件/模組 → 同步移除文件中的描述
- 改 API 端點 → 更新 CLAUDE.md API 段落
- 改設計 token → 更新 system.md 色彩/字型表
- 後端 router 數量變更 → 更新 CLAUDE.md API 說明
不做的事
- 不改架構
- 不改視覺設計
- 不加新功能
- 不重構程式碼
- 只修品質問題