27f - 前端 Steering 规则与反模式

# CLAUDE.md — 前端项目规则
 
## 项目概述
- 框架：React 19 + TypeScript 5.x
- 样式：Tailwind CSS v4 + CSS Modules（仅用于复杂动画）
- 状态管理：Zustand（全局）+ React Query/TanStack Query（服务端状态）
- 路由：React Router v7 / TanStack Router
- 构建工具：Vite 6
- 包管理器：pnpm
- 测试：Vitest + Testing Library + Playwright
 
## 代码风格强制规则
 
### TypeScript
- 严格模式：所有文件必须通过 strict TypeScript 检查
- 禁止 any：不允许使用 `any` 类型，使用 `unknown` + 类型守卫
- 接口优先：组件 props 使用 `interface`，工具类型使用 `type`
- 命名规范：组件 PascalCase，hooks 以 use 开头，工具函数 camelCase
 
### React
- 仅使用函数组件，禁止 class 组件
- hooks 必须遵循 Rules of Hooks（不在条件/循环中调用）
- 禁止在组件内定义组件（会导致每次渲染重新挂载）
- 使用 React.memo() 仅在性能分析证明需要时
- 事件处理函数命名：handle{Event}，如 handleClick、handleSubmit
- 自定义 hooks 必须放在 src/hooks/ 目录
 
### 样式
- 优先使用 Tailwind 工具类，避免自定义 CSS
- 组件变体使用 cva (class-variance-authority) 或 tailwind-variants
- 禁止内联 style 对象（除非是动态计算值）
- 禁止 !important
- 响应式断点：sm(640px) md(768px) lg(1024px) xl(1280px) 2xl(1536px)
- 颜色必须使用设计 token：bg-primary, text-secondary 等
 
### 无障碍
- 所有交互元素必须可键盘访问
- 图片必须有 alt 属性（装饰性图片使用 alt=""）
- 表单控件必须关联 label
- 使用语义化 HTML：nav, main, article, section, aside
- 颜色对比度至少 4.5:1（AA 级）
- 禁止仅依赖颜色传达信息
 
### 性能
- 禁止在渲染路径中使用 new Date()、Math.random()
- 列表渲染必须使用稳定的 key（禁止 index 作为 key，除非列表静态不变）
- 图片使用 next/image 或带 loading="lazy" 的 img
- 动态导入大型组件：React.lazy() + Suspense
- 禁止在 useEffect 中直接 fetch（使用 React Query）
 
### 依赖管理
- 新增依赖前必须检查 bundlephobia 体积
- 禁止引入 moment.js（使用 date-fns 或 dayjs）
- 禁止引入 lodash 全量包（使用 lodash-es 按需导入或原生方法）
- UI 组件优先使用 shadcn/ui（复制到项目中，不作为依赖）
 
### 文件组织
- 组件文件：src/components/{ComponentName}/{ComponentName}.tsx
- 页面文件：src/pages/ 或 src/app/（按路由框架）
- 工具函数：src/lib/ 或 src/utils/
- 类型定义：src/types/
- 常量：src/constants/
- 每个组件目录可包含：组件文件、测试文件、样式文件（如需 CSS Module）
 
## 禁止行为
- 禁止使用 var，仅使用 const/let
- 禁止使用 enum（使用 as const 对象）
- 禁止 console.log 提交到生产代码
- 禁止直接操作 DOM（document.getElementById 等）
- 禁止在组件外部定义可变状态
- 禁止使用 dangerouslySetInnerHTML（除非有 XSS 防护）

.kiro/
└── steering/
    ├── frontend-general.md      # 通用前端规则（inclusion: always）
    ├── react-patterns.md        # React 特定模式（inclusion: auto）
    ├── styling-rules.md         # 样式规范（inclusion: auto）
    └── accessibility.md         # 无障碍规则（inclusion: auto）

---
inclusion: always
description: 前端项目通用规则，适用于所有前端代码交互
globs: "src/**/*.{ts,tsx,css,scss}"
---
 
# 前端通用规则
 
## 技术栈
- React 19 + TypeScript strict mode
- Tailwind CSS v4（禁止混用其他 CSS-in-JS 方案）
- Vite 6 构建
- pnpm 包管理
 
## 核心约束
1. 所有组件必须是函数组件 + TypeScript
2. Props 接口必须显式定义并导出
3. 禁止使用 any 类型
4. 新增 npm 依赖前必须说明理由和体积影响
5. 每个新组件必须包含基本的无障碍支持
 
## 文件命名
- 组件：PascalCase.tsx
- hooks：useCamelCase.ts
- 工具函数：camelCase.ts
- 类型：camelCase.types.ts
- 测试：*.test.ts(x)

---
inclusion: auto
description: React 组件和 hooks 的编写模式规则
globs: "src/**/*.tsx"
---
 
# React 模式规则
 
## 组件模式
- 使用具名导出（export function），避免默认导出
- Props 解构在参数位置，不在函数体内
- 条件渲染使用早返回模式，避免深层嵌套三元表达式
- 复杂条件渲染提取为独立组件
 
## Hooks 规则
- 自定义 hooks 必须以 use 开头
- 禁止在 useEffect 中执行数据获取（使用 TanStack Query）
- useEffect 的依赖数组必须完整，不允许 eslint-disable
- useMemo/useCallback 仅在性能分析证明需要时使用
- 状态更新使用函数式更新：setState(prev => ...)
 
## 状态管理分层
- 组件本地状态：useState / useReducer
- 跨组件共享：Zustand store（按功能域拆分）
- 服务端状态：TanStack Query（缓存、重试、乐观更新）
- URL 状态：路由参数 + searchParams
- 禁止：将所有状态放入全局 store

---
inclusion: auto
description: 样式编写规范
globs: "src/**/*.{tsx,css,scss}"
---
 
# 样式规则
 
## Tailwind CSS
- 使用项目定义的设计 token（颜色、间距、字体）
- 组件变体使用 cva 或 tailwind-variants 管理
- 可复用组件使用 tailwind-merge 处理类名冲突
- 响应式优先移动端：先写移动端样式，再用 sm:/md:/lg: 扩展
- 暗色模式使用 dark: 前缀，不要手动切换类名
 
## 禁止
- 禁止 !important
- 禁止内联 style（除动态计算值外）
- 禁止全局 CSS 选择器（除 globals.css 中的 reset）
- 禁止混用 Tailwind 和 styled-components
- 禁止硬编码颜色值（必须使用 token）
- 禁止使用 @apply 创建大量自定义工具类（违背 Tailwind 理念）

---
inclusion: auto
description: 无障碍合规规则
globs: "src/**/*.tsx"
---
 
# 无障碍规则（WCAG 2.2 AA）
 
## 必须遵守
1. 所有交互元素必须可通过键盘操作（Tab/Enter/Space/Escape）
2. 焦点必须可见且有明确的焦点指示器样式
3. 图片：信息性图片必须有描述性 alt，装饰性图片使用 alt=""
4. 表单：每个输入控件必须关联 <label>，错误信息使用 aria-describedby
5. 按钮：使用 <button> 而非 <div onClick>，图标按钮必须有 aria-label
6. 链接：使用 <a> 而非 <span onClick>，链接文本必须描述目标
7. 标题层级：h1-h6 必须按顺序使用，不跳级
8. 颜色对比度：正文至少 4.5:1，大文本至少 3:1
9. 动画：提供 prefers-reduced-motion 媒体查询支持
10. 模态框：必须实现焦点陷阱和 Escape 关闭
 
## 语义化 HTML
- 页面结构：<header>, <nav>, <main>, <aside>, <footer>
- 内容分区：<article>, <section>（必须有标题）
- 列表：使用 <ul>/<ol>/<dl>，不用 div 模拟
- 表格：使用 <table> + <thead>/<tbody>/<th scope>

---
description: 前端开发通用规则
globs: ["src/**/*.tsx", "src/**/*.ts", "src/**/*.css"]
---
 
# 前端开发规则
 
## 技术栈约束
- 框架：React 19 + TypeScript（strict mode）
- 样式：Tailwind CSS v4
- 状态：Zustand（客户端）+ TanStack Query（服务端）
- 构建：Vite 6
- 测试：Vitest + Testing Library
 
## 代码生成规则
1. 生成 TypeScript 代码时必须包含完整类型定义
2. 组件 props 必须定义 interface 并导出
3. 不要生成 any 类型，使用 unknown + 类型守卫
4. 不要生成 class 组件
5. 不要在组件内部定义子组件
6. 不要使用 enum，使用 as const 对象
7. 事件处理函数使用 handle 前缀
8. 异步操作使用 async/await，不使用 .then() 链
 
## 样式规则
1. 仅使用 Tailwind 工具类
2. 使用项目设计 token，不硬编码颜色/间距
3. 响应式使用 mobile-first：默认移动端，sm:/md:/lg: 扩展
4. 组件变体使用 cva 管理
 
## 无障碍
1. 交互元素使用语义化 HTML（button, a, input）
2. 图片必须有 alt 属性
3. 表单控件必须关联 label
4. 自定义组件必须支持键盘操作
 
## 性能
1. 大型组件使用 React.lazy() 动态导入
2. 列表使用稳定 key（不用 index）
3. 图片使用 lazy loading
4. 避免在渲染路径中创建新对象/数组

# 检查项目技术栈
cat package.json | jq '.dependencies, .devDependencies'
 
# 检查现有 lint 配置
ls -la .eslintrc* eslint.config.* .prettierrc* stylelint.config.*
 
# 检查现有 AI 规则文件
ls -la CLAUDE.md .cursorrules .cursor/rules/ .kiro/steering/

请分析我的前端项目并生成适合的 Steering 规则。

项目信息：
- package.json 中的依赖：[粘贴依赖列表]
- 目录结构：[粘贴 tree 输出]
- 现有 ESLint 配置：[粘贴配置]
- 团队规模：[人数]
- 目标 AI 工具：[Claude Code / Kiro / Cursor]

请生成：
1. 技术栈约束规则
2. 代码风格规则（基于现有 ESLint 配置推断）
3. 文件组织规则（基于现有目录结构推断）
4. 性能和无障碍基线规则
5. 禁止行为清单

输出格式：[CLAUDE.md / Kiro Steering / Cursor Rules]

# 检测 !important 使用
grep -r "!important" src/ --include="*.css" --include="*.scss" --include="*.tsx"
 
# 检测内联 style 使用
grep -rn "style={{" src/ --include="*.tsx" --include="*.jsx"
 
# 检测全局 CSS 选择器（非 module）
find src/ -name "*.css" ! -name "*.module.css" -exec grep -l "[^@]\..*{" {} \;
 
# 使用 Stylelint 检测
npx stylelint "src/**/*.css" --config .stylelintrc.json

## 样式规则（CSS 冲突防护）
- 本项目仅使用 Tailwind CSS v4 作为样式方案
- 禁止使用内联 style 对象（唯一例外：动态计算的 CSS 变量值）
- 禁止使用 !important
- 禁止创建全局 CSS 选择器（globals.css 中的 CSS reset 除外）
- 禁止在项目中引入 styled-components、emotion 或其他 CSS-in-JS 库
- 组件变体使用 cva (class-variance-authority) 管理
- 可复用组件的 className prop 必须通过 tailwind-merge 合并
- Tailwind 类名顺序：布局 → 尺寸 → 间距 → 排版 → 颜色 → 边框 → 效果

请审查以下组件的样式代码，检测并修复 CSS 冲突问题：

[粘贴组件代码]

检查项：
1. 是否混用了多种样式方案？统一为 Tailwind CSS
2. 是否有 !important？移除并通过正确的类名顺序解决
3. 是否有内联 style？转换为 Tailwind 工具类
4. 是否有 Tailwind 类名冲突（如同时有 p-4 和 p-8）？使用 tailwind-merge
5. 是否有全局 CSS 选择器影响组件？改为 CSS Module 或 Tailwind

请输出修复后的代码，并解释每处修改的原因。

# 检测 store 文件大小（过大说明状态集中）
wc -l src/store/*.ts src/stores/*.ts
 
# 检测 useEffect + fetch 模式
grep -rn "useEffect.*fetch\|useEffect.*axios\|useEffect.*api" src/ --include="*.tsx"
 
# 检测 prop drilling（props 中包含大量透传属性）
grep -rn "\.\.\.props\|{.*,.*,.*,.*,.*}" src/ --include="*.tsx" | head -20
 
# 检测 Context Provider 嵌套
grep -rn "Provider>" src/ --include="*.tsx" | wc -l

## 状态管理分层规则
- 组件本地 UI 状态（开关、输入值、展开/折叠）：useState
- 复杂本地状态逻辑（表单、多步骤流程）：useReducer
- 跨组件共享的客户端状态：Zustand（按功能域拆分 store）
- 服务端数据（API 响应）：TanStack Query（禁止 useEffect + fetch）
- URL 状态（筛选、分页、排序）：路由 searchParams
- 每个 Zustand store 不超过 10 个字段，超过则拆分
- Props 传递不超过 2 层，超过则提升状态或使用 Zustand
- 禁止在多处维护同一数据的副本

请审查以下代码的状态管理架构，识别并修复状态混乱问题：

[粘贴相关组件和 store 代码]

项目状态管理规范：
- 本地 UI 状态 → useState/useReducer
- 服务端数据 → TanStack Query
- 跨组件客户端状态 → Zustand（按功能域拆分）
- URL 状态 → searchParams

检查项：
1. 是否有 useEffect + fetch 模式？迁移到 TanStack Query
2. 是否有过大的全局 store？按功能域拆分
3. 是否有 prop drilling（超过 2 层）？提升状态或使用 store
4. 是否有同一数据的多份副本？确定单一数据源
5. 是否有不必要的全局状态（应该是本地状态）？降级为 useState

请输出重构方案和修改后的代码。

# 检测内联对象（性能问题）
grep -rn "style={{" src/ --include="*.tsx"
 
# 检测大型 bundle
npx vite-bundle-visualizer
# 或
npx source-map-explorer dist/assets/*.js
 
# 检测缺少 lazy loading 的路由
grep -rn "import.*from.*pages\|import.*from.*views" src/ --include="*.tsx" | grep -v "lazy\|React.lazy"
 
# 使用 React DevTools Profiler 检测不必要的重渲染
# 或在代码中临时添加：
# useEffect(() => { console.log('Component rendered:', componentName) })
 
# Lighthouse 性能审计
npx lighthouse http://localhost:5173 --only-categories=performance --output=json

## 性能规则
- 路由级组件必须使用 React.lazy() + Suspense 动态导入
- 禁止在 JSX 中创建内联对象（style={{}}），提取为常量或使用 Tailwind
- 列表渲染使用稳定 key（数据 ID），禁止使用 index 作为 key（除非列表静态不变）
- 图片必须指定 width/height 属性防止布局偏移（CLS）
- 图片使用 loading="lazy"（首屏图片除外）
- 大于 100KB 的第三方库必须动态导入
- useEffect 中的订阅/定时器必须在清理函数中取消
- 禁止在渲染路径中调用 new Date()、Math.random()、JSON.parse()
- React.memo / useMemo / useCallback 仅在 Profiler 证明需要时使用
- 字体使用 font-display: swap，避免 FOIT

请对以下 React 组件进行性能审查和优化：

[粘贴组件代码]

检查项：
1. 是否有不必要的重渲染？（内联对象、内联函数、缺少 memo）
2. 是否缺少代码分割？（大型组件/页面应 lazy 加载）
3. 是否有 useEffect 内存泄漏？（缺少清理函数）
4. 图片是否优化？（lazy loading、尺寸指定、格式优化）
5. 列表 key 是否稳定？
6. 是否有渲染路径中的昂贵计算？

请输出优化后的代码，并用注释标注每处优化的原因和预期收益。
不要过度优化——仅修复明确的性能问题，不要给每个组件都加 React.memo。

# 使用 axe-core 自动检测
npx @axe-core/cli http://localhost:5173
 
# 检测 div 模拟交互元素
grep -rn "div.*onClick\|span.*onClick" src/ --include="*.tsx"
 
# 检测缺少 alt 的图片
grep -rn "<img" src/ --include="*.tsx" | grep -v "alt="
 
# 检测缺少 label 的表单
grep -rn "<input\|<select\|<textarea" src/ --include="*.tsx" | grep -v "aria-label\|aria-labelledby\|id=.*label"
 
# ESLint 无障碍检查
npx eslint src/ --rule '{"jsx-a11y/click-events-have-key-events": "error", "jsx-a11y/no-static-element-interactions": "error"}'
 
# Lighthouse 无障碍审计
npx lighthouse http://localhost:5173 --only-categories=accessibility --output=json

## 无障碍强制规则（WCAG 2.2 AA）
- 可点击元素必须使用 <button> 或 <a>，禁止 <div onClick> 或 <span onClick>
- 所有 <img> 必须有 alt 属性：信息性图片写描述，装饰性图片用 alt=""
- 所有表单控件必须关联 <label>（htmlFor）或使用 aria-label
- 自定义下拉菜单/模态框必须实现完整键盘支持（Tab/Escape/Arrow keys）
- 模态框必须实现焦点陷阱（focus trap）
- 颜色对比度：正文文本至少 4.5:1，大文本至少 3:1
- 禁止仅用颜色传达信息（必须配合图标/文字/形状）
- 动画必须尊重 prefers-reduced-motion 媒体查询
- 页面标题（<title>）必须描述当前页面内容
- 标题层级（h1-h6）必须按顺序使用，不跳级
- 使用语义化 HTML 标签：<nav>, <main>, <article>, <section>, <aside>, <footer>

请对以下组件进行 WCAG 2.2 AA 级无障碍审查和修复：

[粘贴组件代码]

检查项：
1. 交互元素是否使用语义化 HTML？（button/a 而非 div/span）
2. 图片是否有适当的 alt 属性？
3. 表单控件是否关联 label？
4. 是否支持键盘操作？（Tab 导航、Enter/Space 激活、Escape 关闭）
5. 颜色对比度是否达标？（4.5:1 正文，3:1 大文本）
6. 是否有 ARIA 属性缺失？（aria-label, aria-expanded, aria-hidden 等）
7. 标题层级是否正确？
8. 动画是否尊重 prefers-reduced-motion？

请输出修复后的代码，标注每处修改对应的 WCAG 准则编号。

# 分析 bundle 组成
npx vite-bundle-visualizer
 
# 检查依赖体积
npx bundlephobia-cli moment lodash axios
 
# 检测未使用的依赖
npx knip
 
# 检测 lodash 全量导入
grep -rn "from 'lodash'" src/ --include="*.ts" --include="*.tsx"
# 正确方式应该是 from 'lodash-es/debounce' 或 from 'lodash/debounce'
 
# 检测 moment.js 使用
grep -rn "from 'moment'" src/ --include="*.ts" --include="*.tsx"
 
# 检查打包后的文件大小
ls -lh dist/assets/*.js | sort -k5 -h

## 依赖管理规则（包体积控制）
- 新增 npm 依赖前必须说明：1) 为什么需要 2) 体积多大 3) 是否有更轻量替代
- 禁止引入的库：
  - moment.js → 使用 date-fns 或 dayjs
  - lodash（全量）→ 使用 lodash-es 按需导入或原生 JS 方法
  - axios → 使用原生 fetch + 轻量封装
  - jQuery → 禁止
- 图标使用 lucide-react 或 @heroicons/react（tree-shakable）
- UI 组件优先使用 shadcn/ui（复制源码，不作为 npm 依赖）
- 图表库：轻量场景用 CSS/SVG，复杂场景用 recharts（tree-shakable）
- 单个第三方库 gzip 后不超过 50KB，超过需要动态导入
- 总 bundle size 目标：首屏 JS < 200KB (gzip)

请审查以下项目的依赖列表，识别包体积膨胀问题并提供优化方案：

package.json dependencies:
[粘贴依赖列表]

当前 bundle 分析结果：
[粘贴 bundle analyzer 输出或文件大小列表]

请检查：
1. 是否有可以用更轻量替代品替换的大型库？
2. 是否有未使用 tree-shaking 友好导入方式的库？
3. 是否有应该动态导入（lazy load）的大型库？
4. 是否有完全未使用的依赖？
5. 是否有可以用原生 API 替代的库？

对每个问题，请提供：
- 当前库名和体积
- 推荐替代方案和体积
- 具体的代码修改示例

# 检测只使用一次的自定义 hooks
for hook in $(grep -rn "export.*function use" src/hooks/ --include="*.ts" -l); do
  hookName=$(grep -o "function use[A-Za-z]*" "$hook" | head -1 | awk '{print $2}')
  count=$(grep -rn "$hookName" src/ --include="*.tsx" --include="*.ts" | grep -v "export" | wc -l)
  echo "$hookName: used $count times"
done
 
# 检测 props 过多的组件
grep -rn "interface.*Props" src/ --include="*.tsx" -A 20 | grep -c ";"
# 超过 10 个属性的 Props 接口需要审查
 
# 检测 HOC 嵌套
grep -rn "export default.*with.*with" src/ --include="*.tsx"
 
# 检测过深的目录嵌套（可能是过度分层）
find src/ -type f -name "*.tsx" | awk -F/ '{print NF-1}' | sort -rn | head -10

## 抽象规则（防止过度工程）
- 自定义 hook 仅在逻辑被 3 处以上复用时才创建
- 组件 props 不超过 8 个，超过则拆分为多个组件
- 禁止使用 HOC（Higher-Order Components），使用 hooks 或组合模式
- 禁止创建"万能组件"（一个组件通过 props 切换完全不同的行为）
- 优先使用组合（Composition）而非继承或配置
- 目录嵌套不超过 4 层
- 遵循 YAGNI：不为"将来可能需要"的场景预先抽象
- 两处重复代码可以接受，三处以上再考虑抽象
- 简单逻辑直接写在组件中，不需要提取为独立函数

请审查以下代码的抽象层次，识别过度抽象问题并简化：

[粘贴代码]

检查项：
1. 是否有只使用一次的自定义 hook？→ 内联到组件中
2. 是否有 props 超过 8 个的"万能组件"？→ 拆分为多个专用组件
3. 是否有不必要的中间层（Repository/Service/Controller）？→ 简化层级
4. 是否有过早的抽象（为未来需求预留的接口）？→ 删除，需要时再加
5. 是否有 HOC 嵌套？→ 转换为 hooks

原则：
- 代码应该"刚好够用"，不多不少
- 可读性优先于可复用性
- 具体优先于抽象

请输出简化后的代码。

# 检测硬编码颜色值（应使用 token）
grep -rn "bg-blue-\|bg-red-\|bg-green-\|text-blue-\|text-red-\|border-blue-" src/ --include="*.tsx" | grep -v "primary\|secondary\|accent\|muted"
 
# 检测不一致的间距
grep -rn "className=" src/ --include="*.tsx" | grep -o "p-[0-9]\+\|px-[0-9]\+\|py-[0-9]\+\|gap-[0-9]\+" | sort | uniq -c | sort -rn
 
# 检测不一致的圆角
grep -rn "className=" src/ --include="*.tsx" | grep -o "rounded[a-z-]*" | sort | uniq -c | sort -rn
 
# 检测不一致的字体大小
grep -rn "className=" src/ --include="*.tsx" | grep -o "text-[a-z]\+" | sort | uniq -c | sort -rn

## 设计一致性规则
- 颜色必须使用设计 token：bg-primary, bg-secondary, bg-muted, text-foreground 等
- 禁止使用 Tailwind 默认调色板的具体色阶（如 bg-blue-500）
- 间距使用统一的 spacing scale：4(1rem), 6(1.5rem), 8(2rem)
- 圆角统一：卡片 rounded-lg，按钮 rounded-md，输入框 rounded-md，徽章 rounded-full
- 阴影统一：卡片 shadow-sm，弹出层 shadow-lg，模态框 shadow-xl
- 字体大小层级：
  - 页面标题：text-3xl font-bold
  - 区域标题：text-xl font-semibold
  - 卡片标题：text-lg font-medium
  - 正文：text-base
  - 辅助文本：text-sm text-muted-foreground
- 按钮样式必须使用项目定义的 Button 组件变体，不要手写按钮样式
- 新组件的视觉样式必须参考已有的相似组件

请审查以下组件集合的样式一致性，并统一为设计系统规范：

组件列表：
[粘贴多个组件代码]

项目设计 token：
- 颜色：primary, secondary, accent, muted, destructive, foreground, background
- 间距：4(sm), 6(md), 8(lg), 12(xl)
- 圆角：sm(rounded), md(rounded-md), lg(rounded-lg), full(rounded-full)
- 阴影：sm(shadow-sm), md(shadow-md), lg(shadow-lg)

检查项：
1. 颜色是否统一使用 token？
2. 间距是否遵循 spacing scale？
3. 圆角和阴影是否一致？
4. 字体大小层级是否正确？
5. 相似组件的视觉处理是否一致？

请输出统一后的代码，并列出所有修改点。

# 检测固定宽度值
grep -rn "w-\[.*px\]\|h-\[.*px\]\|width:.*px\|min-width:.*px" src/ --include="*.tsx" --include="*.css"
 
# 检测缺少响应式前缀的 grid
grep -rn "grid-cols-[2-9]" src/ --include="*.tsx" | grep -v "sm:\|md:\|lg:"
 
# 检测缺少 flex-wrap
grep -rn "flex " src/ --include="*.tsx" | grep -v "flex-wrap\|flex-col"
 
# 使用 Responsively App 或 Polypane 多视口同步测试
# 或使用 Playwright 自动化测试不同视口
npx playwright test --project=mobile --project=tablet --project=desktop
 
# Lighthouse 移动端审计
npx lighthouse http://localhost:5173 --emulated-form-factor=mobile --output=json

## 响应式布局规则
- 采用 mobile-first 策略：默认样式为移动端，用 sm:/md:/lg: 扩展
- 禁止使用固定像素宽度（w-[400px]），使用相对单位或 max-w-*
- Grid 布局必须包含响应式列数：grid-cols-1 sm:grid-cols-2 lg:grid-cols-3
- Flex 容器在可能换行的场景必须添加 flex-wrap
- 文字溢出处理：长文本使用 truncate 或 line-clamp-*
- 触摸目标最小 44x44px（min-h-11 min-w-11）
- 模态框在移动端使用全屏或底部抽屉模式
- 导航栏必须有移动端汉堡菜单方案
- 表格在移动端使用卡片布局或水平滚动（overflow-x-auto）
- 测试断点：375px (iPhone SE), 768px (iPad), 1024px (iPad 横屏), 1280px (桌面), 1536px (大屏)
- 使用 Container Queries (@container) 处理组件级响应式

请审查以下组件的响应式布局，修复在不同视口下的断裂问题：

[粘贴组件代码]

目标视口：
- 移动端：375px（iPhone SE）
- 平板竖屏：768px
- 平板横屏：1024px
- 桌面：1280px
- 大屏：1536px

检查项：
1. 是否有固定像素宽度？→ 改为相对单位或 max-w
2. Grid/Flex 是否在所有视口下正常？→ 添加响应式断点
3. 文字是否可能溢出？→ 添加 truncate 或 line-clamp
4. 触摸目标是否足够大？→ 最小 44x44px
5. 模态框/弹出层在移动端是否正常？→ 适配移动端布局
6. 导航栏是否有移动端方案？→ 汉堡菜单

请使用 mobile-first 策略重写响应式样式，确保在所有目标视口下正常显示。

# .github/workflows/frontend-quality.yml
name: Frontend Quality Gate
 
on:
  pull_request:
    paths:
      - 'src/**'
      - 'package.json'
 
jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: pnpm/action-setup@v4
        with:
          version: 9
 
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'
 
      - run: pnpm install --frozen-lockfile
 
      # TypeScript 类型检查
      - name: Type Check
        run: pnpm tsc --noEmit
 
      # ESLint + 无障碍规则
      - name: Lint
        run: pnpm eslint src/ --max-warnings 0
 
      # Stylelint CSS 检查
      - name: Style Lint
        run: pnpm stylelint "src/**/*.css"
 
      # 未使用依赖检测
      - name: Dead Code Check
        run: pnpm knip --no-exit-code
 
      # Bundle Size 检查
      - name: Build
        run: pnpm build
 
      - name: Bundle Size Check
        run: |
          MAX_SIZE=250000  # 250KB gzip
          ACTUAL=$(gzip -c dist/assets/index-*.js | wc -c)
          echo "Bundle size: $ACTUAL bytes (max: $MAX_SIZE)"
          if [ "$ACTUAL" -gt "$MAX_SIZE" ]; then
            echo "❌ Bundle size exceeds limit!"
            exit 1
          fi
 
      # Lighthouse CI
      - name: Lighthouse
        uses: treosh/lighthouse-ci-action@v12
        with:
          configPath: .lighthouserc.json
          uploadArtifacts: true

// .lighthouserc.json
{
  "ci": {
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.8 }],
        "categories:accessibility": ["error", { "minScore": 0.9 }],
        "categories:best-practices": ["error", { "minScore": 0.9 }],
        "first-contentful-paint": ["warn", { "maxNumericValue": 2000 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
        "total-blocking-time": ["warn", { "maxNumericValue": 300 }]
      }
    }
  }
}

// package.json
{
  "lint-staged": {
    "src/**/*.{ts,tsx}": [
      "eslint --fix --max-warnings 0",
      "prettier --write"
    ],
    "src/**/*.css": [
      "stylelint --fix",
      "prettier --write"
    ]
  }
}

请作为前端代码审查员，审查以下 PR diff，检查八大反模式：

[粘贴 git diff 输出]

检查清单：
1. ❌ CSS 冲突：是否混用样式方案？是否有 !important？
2. ❌ 状态混乱：状态分层是否合理？是否有 useEffect+fetch？
3. ❌ 性能陷阱：是否有内联对象/函数？是否缺少代码分割？
4. ❌ 无障碍违规：是否有 div onClick？是否缺少 alt/label？
5. ❌ 包体积膨胀：是否引入了不必要的大型依赖？
6. ❌ 过度抽象：是否有只用一次的 hook？props 是否过多？
7. ❌ 样式不一致：是否使用了设计 token？间距/颜色是否统一？
8. ❌ 响应式断裂：是否有固定宽度？Grid 是否有响应式断点？

对每个发现的问题，请标注：
- 严重程度：🔴 必须修复 / 🟡 建议修复 / 🟢 可选优化
- 具体位置：文件名 + 行号
- 修复建议：具体的代码修改方案

---
inclusion: always
description: 电商前端项目规则
globs: "src/**/*.{ts,tsx}"
---
 
# 电商前端规则
 
## 技术栈
- React 19 + TypeScript strict
- Tailwind CSS v4 + shadcn/ui
- Zustand（购物车、用户偏好）
- TanStack Query（产品数据、订单数据）
- React Router v7
 
## 电商特定规则
- 价格显示必须使用 Intl.NumberFormat，支持多币种
- 产品图片必须使用 srcset 提供多分辨率版本
- 产品列表必须支持无限滚动或分页（不一次加载全部）
- 购物车状态必须持久化到 localStorage
- 所有用户输入必须做 XSS 防护（DOMPurify）
- 搜索输入必须 debounce（300ms）
- 产品卡片必须包含：图片、名称、价格、评分、加入购物车按钮
- 加入购物车按钮必须有 loading 和 success 状态反馈

请为电商产品列表页生成一个 ProductCard 组件。

需求：
- 显示产品图片、名称、价格、评分、加入购物车按钮
- 响应式：移动端单列，平板双列，桌面三列
- 支持键盘操作和屏幕阅读器
- 价格使用 Intl.NumberFormat 格式化
- 图片使用 lazy loading 和 srcset
- 加入购物车有 loading/success 状态

请遵循项目 Steering 规则生成代码。

请审查以下 ProductCard 组件，检查八大前端反模式：

[AI 生成的 ProductCard 代码]

重点检查：
1. 样式是否使用设计 token？
2. 状态管理是否合理？（加入购物车状态应该用什么管理？）
3. 图片是否优化？（lazy loading, srcset, alt）
4. 无障碍是否完整？（键盘操作, ARIA, 语义化 HTML）
5. 响应式是否覆盖所有断点？
6. 是否有不必要的抽象？