@captain_z/zsk-skills 0.1.0

package/frontend/react-components/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: zsk:react-components
+description: React component API design — layering (UI/logic separation via
+  hooks), composition vs configuration (compound components over flat-prop
+  explosion), granularity (5-question checklist), controlled vs uncontrolled
+  boundary, Props API design. React-specific implementation of generic component
+  discipline.
+category: standard
+domain: frontend
+tier: optional
+related:
+  - ../react-naming/SKILL.md
+  - ../typescript/SKILL.md
+  - ../../quality/code-hygiene/SKILL.md
+triggers:
+  - React component design
+  - compound components
+  - component granularity
+  - controlled uncontrolled
+  - Props API
+  - hooks extraction
+---
+
+# React Components · 组件设计纪律
+
+> **范围**：React 组件的**设计层** — 分层 / 可扩展 / 组合 / 粒度 / 受控边界 / Props API
+> **不含**：命名（见 [`react-naming`](../react-naming/SKILL.md)）/ 类型（见 [`typescript`](../typescript/SKILL.md)）/ 测试（见 [`testing-web`](../testing-web/SKILL.md)）
+> **跨栈原则**：Vue / Svelte / Solid 的组件设计原则相同，语法等价替换
+
+## 1. 分层（UI / 逻辑分离）
+
+组件内部严格分离**渲染层**与**逻辑层**。
+
+### 硬规则
+
+- **UI 层（`.tsx` 主文件）**：只负责 JSX 渲染 + 事件分发，不写 `if (user.role === 'admin')` 这类业务判定
+- **逻辑层（hooks / services / utils）**：状态机、副作用、业务规则、API 调用
+- **同一逻辑出现 ≥ 2 处 → 立即抽 hook**，不要等"第三次再抽"
+
+### 推荐结构
+
+```tsx
+// FeatureTree/index.tsx — UI 层
+export function FeatureTree(props: FeatureTreeProps) {
+  const { state, handlers } = useFeatureTreeLogic(props);
+  return <FeatureTreeView {...state} {...handlers} />;
+}
+
+// FeatureTree/useFeatureTreeLogic.ts — 逻辑层
+export function useFeatureTreeLogic(props: FeatureTreeProps) {
+  const [expanded, setExpanded] = useState<Set<string>>(new Set());
+  // ...
+  return { state: { expanded, ... }, handlers: { onToggle, ... } };
+}
+```
+
+### Hook 设计红线
+
+- Hook 只返回状态 + 方法，**不返回 JSX**
+- Hook 内不做不相关副作用（一个 hook 只解决一类问题）
+- Hook 命名以 `use` 开头（见 [`react-naming`](../react-naming/SKILL.md)）
+- Hook 的依赖遵守 `react-hooks/exhaustive-deps`，豁免必须在该行加 ADR 引用
+
+## 2. 可扩展（Open / Closed）
+
+**新增能力通过新增 Prop / 新增 slot 达成，不改已存在 Prop 的语义**。
+
+### 禁用
+
+- ❌ 发布后的 Prop 含义偷偷变化（`size: 'small' | 'large'` → `size: number`）
+- ❌ 靠"传 `flag=true`"修改既有行为 → 表明 Prop 设计错了，应拆两个组件
+- ❌ 改了 Prop 默认值而不开 major 版本
+
+### 允许
+
+- ✅ 新增可选 Prop，默认值不变更现状
+- ✅ 新增具名 slot（`header` / `footer`）
+- ✅ 新增事件回调（`onXxx`），老消费者无感
+
+## 3. 组合 vs 配置
+
+**组合（children / slot / compound）优于配置（扁平 Props）**。
+
+### 判定：扁平 Props ≥ 8 个 or 出现 `renderXxx` 渲染回调时，改用组合。
+
+### 组合模式清单
+
+| 模式 | 何时用 | 形态 |
+| --- | --- | --- |
+| `children` | 单 slot | `<Card>{content}</Card>` |
+| Compound Components | 多 slot 有语义关联 | `<Tabs><Tabs.List/><Tabs.Panel/></Tabs>` |
+| Slot Props | 多 slot 不固定顺序 | `<Layout header={...} sidebar={...} />` |
+| Render Props | 内部状态需暴露 | `<Autocomplete>{({items}) => ...}</Autocomplete>` |
+| Hook 暴露 | 完全把控制权给外部 | `const combo = useCombobox(); <input {...combo.getInputProps()}/>` |
+
+### Compound Components 示例
+
+```tsx
+<Select value={value} onChange={setValue}>
+  <Select.Trigger placeholder="选择..." />
+  <Select.Options>
+    <Select.Option value="a">A</Select.Option>
+    <Select.Option value="b">B</Select.Option>
+  </Select.Options>
+</Select>
+```
+
+父组件通过 Context 传状态，子组件只关心自己的渲染责任。
+
+## 4. 组件粒度（5 问 checklist）
+
+新建 / 拆分组件前，依次回答：
+
+1. **复用**：这块 JSX 是否会在 ≥ 2 处出现？(否 → 先不拆)
+2. **职责**：能否用一句话说明"它是什么"？(否 → 职责不清，先想清再拆)
+3. **Props 数量**：拆完后每个组件的 Props ≤ 8？(否 → 再拆或改组合)
+4. **独立状态**：子组件是否有独立状态？(是 → 值得拆)
+5. **跨文件引用**：拆完后是否需要在多处 import？(否且只本文件用 → 考虑留在同文件内部组件)
+
+**只要 1、2、4 其一是"强是"，就应该拆**；反之留在父组件内。
+
+## 5. 受控 / 非受控边界
+
+### 判定
+
+| 场景 | 选择 |
+| --- | --- |
+| 父组件需要读取 / 控制值 | **受控**（`value` + `onChange`） |
+| 组件自管理、父不关心中间态 | **非受控**（`defaultValue` + `onCommit`） |
+| 既要默认值又要外部控制 | **混合**（`defaultValue` + `value?` + `onChange?`） |
+
+### 硬规则
+
+- **不允许同时声明 `value` 和 `defaultValue`** 语义重复，Props 文档明确"二选一"
+- **受控组件的 `value` 为 `undefined` 时视为"受控但当前无值"**，不要 fallback 到内部 state
+- **受控 → 非受控切换（或反向）产生警告**：React 会报 `A component is changing an uncontrolled input to be controlled`，要求父组件在挂载前决定模式
+
+### 示例
+
+```tsx
+type InputProps = {
+  value?: string;              // 受控值
+  defaultValue?: string;       // 非受控初值
+  onChange?: (v: string) => void;
+};
+
+// 判断模式
+const isControlled = value !== undefined;
+const [internalValue, setInternalValue] = useState(defaultValue ?? '');
+const currentValue = isControlled ? value : internalValue;
+```
+
+## 6. Props API 设计
+
+### Props 命名
+
+- 数据类：名词（`items` / `user` / `selected`）
+- 回调类：`on{Event}`（`onChange` / `onSelect` / `onError`）
+- 布尔类：`is/has/can/should` 前缀（`isLoading` / `hasError` / `canSelect`）
+- 详细规范见 [`react-naming`](../react-naming/SKILL.md)
+
+### 默认值
+
+- 默认值在**解构时给**，不在 `defaultProps`（RSC 弃用）
+  ```tsx
+  function Btn({ size = 'medium', disabled = false }: BtnProps) { ... }
+  ```
+- 默认值应是"最常用"而非"最保守"
+- 必填 Prop 不给默认值（用 TS 强制）
+
+### 联合字面量 vs 布尔堆叠
+
+- ❌ `<Btn primary danger large/>` — 多 boolean 堆叠组合爆炸
+- ✅ `<Btn variant="danger" size="large"/>` — 联合字面量清晰可扩展
+
+### Props 穿透
+
+- **危险 Props 穿透**（`...rest` 到原生元素）需要类型约束：
+  ```tsx
+  type BtnProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'type'> & {
+    variant: 'primary' | 'danger';
+  };
+  ```
+- 不允许无类型 `...props` 穿透
+
+## 7. 跨栈迁移（原则保留）
+
+| 原则 | React | Vue 3 | Svelte 5 |
+| --- | --- | --- | --- |
+| UI / 逻辑分离 | Hook + View 组件 | Composables + `<script setup>` | Module + component |
+| 组合 | children / compound | `<slot>` / 具名 slot | `<slot>` / snippets |
+| 受控 / 非受控 | `value` + `onChange` | `v-model` / 单向 binding | `bind:value` 可选 |
+| Props 字面量 | Union string | `PropType<'a'\|'b'>` | `$props<{variant: 'a'\|'b'}>` |
+
+## 反模式（禁止）
+
+- ❌ UI 层写业务规则（`if (permission.code === 'XYZ')` 出现在 `.tsx` 里）
+- ❌ 为"未来可能扩展"预留参数（YAGNI — 见 [`quality/code-hygiene`](../../quality/code-hygiene/SKILL.md)）
+- ❌ 同一组件既受控又有内部 state 静默 fallback（产生"值不同步"bug）
+- ❌ 扁平 Props ≥ 10 个 不改组合
+- ❌ 同时声明 `value` 和 `defaultValue`
+- ❌ 把不相关的能力塞进一个 hook
+
+## 质量门禁
+
+- [ ] UI / 逻辑分层清晰（JSX 文件无业务 `if`）
+- [ ] 组件粒度通过 5 问 checklist
+- [ ] 受控 / 非受控边界在 Props 文档声明
+- [ ] Props API 遵循 [`react-naming`](../react-naming/SKILL.md)
+- [ ] 无多 boolean 堆叠配置
+- [ ] 新增能力通过加 Prop / slot 而非改语义

package/frontend/react-naming/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: zsk:react-naming
+description: React + TypeScript naming conventions — components, files, folders,
+  variables, booleans, event handlers, event props, hooks, TS types/interfaces,
+  constants, and i18n keys. Principles transfer to Vue/Svelte with syntax
+  adjustments.
+category: standard
+domain: frontend
+tier: optional
+related:
+  - ../react-components/SKILL.md
+  - ../typescript/SKILL.md
+  - ../i18n/SKILL.md
+triggers:
+  - React naming
+  - component file naming
+  - event handler naming
+  - boolean naming
+  - i18n key naming
+  - hook naming
+  - TypeScript type naming
+---
+
+# React Naming · 命名约定（React + TS）
+
+> **范围**：React + TS 项目的命名约定全集 — 组件 / 文件 / 变量 / 布尔 / 事件 / Hook / 类型 / 常量 / i18n key
+> **前置检测**：若项目已有 `.eslintrc` / `tsconfig.json` 规定命名，以项目为准；本文件为缺省约定
+
+## 命名总表
+
+| 实体 | 约定 | 示例 | 反例 |
+| --- | --- | --- | --- |
+| 组件（函数 / 类） | PascalCase | `UserProfileCard` | `user_profile_card`, `userProfileCard` |
+| 组件文件 | `PascalCase.tsx` 或 `index.tsx`（目录内） | `UserProfile.tsx` · `UserProfile/index.tsx` | `user-profile.tsx` |
+| 组件目录 | PascalCase | `UserProfile/` | `user-profile/` |
+| Hook 函数 | `use` + camelCase | `useUserProfile`, `useDebouncedValue` | `UserProfileHook`, `hookProfile` |
+| Hook 文件 | 同 hook 名 `.ts` | `useUserProfile.ts` | `user-profile-hook.ts` |
+| 工具函数 / utils | camelCase | `formatDate`, `parseISO` | `FormatDate`, `format_date` |
+| utils 文件 | camelCase 或 kebab-case（保持一致） | `formatDate.ts` · `format-date.ts` | 两种混用 |
+| 常量（模块级 / 全局） | SCREAMING_SNAKE_CASE | `MAX_RETRY`, `API_BASE_URL` | `maxRetry`, `ApiBaseUrl` |
+| 常量（函数内局部） | camelCase | `const retryLimit = 3` | 局部也用 `RETRY_LIMIT` |
+| TS 类型 / 接口 | PascalCase，单数名词 | `UserProfile`, `Response<T>` | `IUserProfile`, `UserProfileType` |
+| Enum / 字面量联合 | PascalCase（Enum）/ 字面量小写 | `'loading' \| 'error'` | `'LOADING' \| 'ERROR'` |
+| 变量 | camelCase | `currentUser` | `current_user` |
+| 布尔变量 / Prop | `is/has/can/should/did` + 形容词 | `isLoading`, `hasError`, `canEdit` | `loading`, `error` 作布尔时含糊 |
+| 事件 handler（组件内） | `handle` + 名词 + 动作（可选） | `handleSubmit`, `handleItemClick` | `onSubmit` 在组件内部定义（易与 Prop 冲突） |
+| 事件 Prop（对外） | `on` + 名词 + 动作（可选） | `onChange`, `onItemClick` | `handleChange` 作 Prop |
+| 回调 Prop（非 DOM 事件） | `on{Phase}{Subject}` | `onSelectionChange`, `onBeforeClose` | `callback`, `cb` |
+| Ref | camelCase + `Ref` 后缀 | `inputRef`, `scrollContainerRef` | `ref1`, `myRef` |
+| Context | `{Domain}Context` | `UserContext`, `ThemeContext` | `userCtx`, `themeContextValue` |
+| Provider | `{Domain}Provider` | `UserProvider` | `UserContextProvider`（冗余） |
+| HOC | `with{Capability}` | `withAuth`, `withErrorBoundary` | `authHOC` |
+| 错误类 | PascalCase + `Error` 后缀 | `ValidationError`, `NetworkError` | `ErrValidation` |
+
+## 组件命名深入
+
+### 语义优先于类型
+
+- ✅ `UserAvatar` / `PrimaryButton` / `EmptyState`
+- ❌ `DivBox` / `Component1` / `MyComponent`
+
+### 前缀用于区分用途
+
+| 前缀 | 用途 | 例 |
+| --- | --- | --- |
+| `App` | 应用外壳 | `AppHeader`, `AppShell` |
+| `Page` | 路由级页面 | `PageUserProfile`（或目录 `pages/user-profile/`）|
+| `Layout` | 布局容器 | `LayoutDashboard` |
+| `Modal` / `Drawer` / `Popover` | 浮层类型 | `ConfirmModal`, `UserDrawer` |
+| `Icon` | 图标组件 | `IconClose`, `IconCheck` |
+
+### 禁用
+
+- ❌ `I{Name}` 风格接口（Hungarian）：用 `UserProfile` 不用 `IUserProfile`
+- ❌ `{Name}Component` 后缀：`UserCard` 已经暗示是组件
+- ❌ 无意义后缀 `Wrapper` / `Container` / `Box`（除非确实只是布局容器）
+
+## 事件命名深入（handle vs on）
+
+最常被搞混的一对。
+
+| 场景 | 用 `handle` 还是 `on` | 例 |
+| --- | --- | --- |
+| 组件内部定义的函数 | `handle` | `const handleClick = () => { ... }` |
+| 作为 Prop 传给子组件 | `on` | `<Child onItemClick={handleClick}/>` |
+| 声明 Props 类型 | `on` | `type Props = { onSelect: (id: string) => void }` |
+
+**推断逻辑**：`on` = 对方告诉我"发生了什么"，`handle` = 我决定"怎么响应"。
+
+### 具体动作命名
+
+```tsx
+// ✅ 清晰
+const handleSubmit = () => { ... };
+const handleItemClick = (id: string) => { ... };
+const handleSearchChange = (value: string) => { ... };
+
+// ❌ 模糊
+const onClick = () => { ... };          // 函数还是 Prop？
+const click = () => { ... };            // 动词作名词
+const handleIt = () => { ... };         // "it" 指什么？
+```
+
+## 布尔命名深入
+
+前缀传达语义：
+
+| 前缀 | 语义 | 例 |
+| --- | --- | --- |
+| `is` | 当前状态 | `isLoading`, `isOpen`, `isSelected` |
+| `has` | 拥有 / 存在 | `hasError`, `hasItems`, `hasPermission` |
+| `can` | 能力 / 权限 | `canEdit`, `canSelect` |
+| `should` | 建议 / 预期 | `shouldRender`, `shouldAnimate` |
+| `did` | 完成动作（过去） | `didLoad`, `didMount`（罕见）|
+
+### 禁用
+
+- ❌ `loading`（名词还是布尔？）
+- ❌ `!disabled`（双重否定）— 换成 `isEnabled`
+- ❌ `error` 作布尔（`error` 应是对象/消息，`hasError` 才是布尔）
+
+## Hook 命名深入
+
+| 类型 | 命名 | 例 |
+| --- | --- | --- |
+| 数据 fetch | `use{Resource}` | `useUser`, `useProducts` |
+| mutation | `use{Action}{Resource}` | `useCreateUser`, `useUpdateOrder` |
+| UI 状态 | `use{Feature}State` | `useModalState`, `useSelectionState` |
+| 事件 | `use{Event}` | `useClickOutside`, `useKeyPress` |
+| 派生值 | `use{Computed}` | `useFilteredItems`, `useSortedList` |
+
+返回值约定：
+
+- 单一值 → 直接返回（`const user = useUser(id)`）
+- 多个值 → 返回对象（`const { data, error, isLoading } = useUser(id)`）
+- 状态 + 更新器（对象 / 数组皆可，项目内保持一致）
+
+## i18n key 命名
+
+详见 [`i18n`](../i18n/SKILL.md)，概要：
+
+```
+{namespace}.{feature}.{element}.{variant?}
+```
+
+| key | 用途 |
+| --- | --- |
+| `order.list.empty` | 订单列表空态 |
+| `order.list.error.network` | 订单列表网络错误 |
+| `common.button.confirm` | 通用确认按钮 |
+| `user.profile.avatar.alt` | 用户头像 alt 文本 |
+
+- 全小写 + `.` 分隔
+- 不含中文、空格、下划线（除非项目 locale 工具强制）
+- 语义优先于位置（不要 `page1.btn3`）
+
+## TS 类型命名
+
+### 常见模式
+
+```ts
+// 数据模型：名词单数
+type User = { id: string; name: string };
+
+// Props：组件名 + Props
+type UserCardProps = { user: User; onSelect?: (id: string) => void };
+
+// 回调签名：动词 + Handler / 参数 + Callback
+type SelectHandler = (id: string) => void;
+type ChangeCallback<T> = (value: T) => void;
+
+// API 响应 / 请求：{Domain}{Action}Response
+type UserListResponse = { items: User[]; total: number };
+type UserCreateRequest = { name: string; email: string };
+
+// 枚举（倾向字面量联合 > enum）
+type Status = 'idle' | 'loading' | 'success' | 'error';
+```
+
+### 禁用
+
+- ❌ `IUser` 前缀（Hungarian）
+- ❌ `UserType` / `UserInterface` 后缀（冗余）
+- ❌ `TUser` 泛型式前缀（用于 generic 占位符是另一回事）
+
+## 文件夹组织命名
+
+```
+src/
+  components/         kebab-case 目录 or PascalCase 目录，项目内保持一致
+    UserCard/
+      index.tsx
+      UserCard.test.tsx
+      UserCard.module.less
+      useUserCardLogic.ts
+  hooks/              独立 hook 放这里
+    useDebouncedValue.ts
+  pages/              路由页面
+    user-profile/     kebab-case（URL 一致）
+      index.tsx
+  utils/              纯函数
+    formatDate.ts
+  types/              全局类型
+    user.ts
+```
+
+**选择 PascalCase 组件目录 vs kebab-case**：看项目 `eslint` / `import/no-unresolved` 配置和操作系统大小写敏感性。**一经确定，全项目统一**。
+
+## 反模式（禁止）
+
+- ❌ `data` / `item` / `value` 这种无信息量的变量名在作用域大时使用
+- ❌ 缩写（除非行业常识：`id` / `url` / `api` / `ui`）— 用 `config` 不用 `cfg`
+- ❌ 同一概念多个名字（`userId` / `user_id` / `uid` 混用）
+- ❌ 中文拼音（`xuanze` / `dingdan`）
+- ❌ 含数字后缀（`data1` / `data2`）— 改名或集合化
+
+## 质量门禁
+
+- [ ] 组件 / 文件 / hook / 类型符合命名总表
+- [ ] 事件 handler 用 `handle`，事件 Prop 用 `on`
+- [ ] 布尔带语义前缀（`is` / `has` / `can` / `should`）
+- [ ] i18n key 按 `namespace.feature.element` 结构
+- [ ] 无 Hungarian 前缀（`I...` / `T...` 例外）
+- [ ] 无中文 / 拼音 / 无意义缩写

package/frontend/review-frontend/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: zsk:review-frontend
+description: Frontend PR code review — frontend-specific self-checklist and
+  reviewer checklist covering TypeScript red lines (no any / @ts-ignore), React
+  hooks rules, dangerouslySetInnerHTML, large-list performance hazards, visual
+  regression, i18n three-language sync, jsx-a11y. Extends zsk:reviewing generic
+  checklist.
+category: stage
+domain: frontend
+tier: optional
+stage: 5
+variants:
+  - feature
+  - bugfix
+  - refactor
+related:
+  - ../../sdlc/reviewing/SKILL.md
+  - ../typescript/SKILL.md
+  - ../react-components/SKILL.md
+  - ../security-web/SKILL.md
+  - ../a11y-web/SKILL.md
+  - ../i18n/SKILL.md
+  - ../performance-web/SKILL.md
+  - ../testing-web/SKILL.md
+triggers:
+  - frontend code review
+  - React review checklist
+  - TypeScript red lines
+  - hooks review
+  - visual regression review
+  - i18n three language check
+---
+
+# Stage 5: Reviewing · Frontend 补丁
+
+> **用途**：在 [`zsk:reviewing`](../../sdlc/reviewing/SKILL.md) 通用 checklist 上追加的前端专属检查项
+> **范围**：TS / React / dangerously / 视觉回归 / 三语 i18n / jsx-a11y / 性能 hazard
+
+## 自评清单（前端补丁，Author 推前必过）
+
+### TypeScript 红线（见 [`frontend/typescript`](../typescript/SKILL.md)）
+- [ ] 无新增 `any` / `as any` / `@ts-ignore` / `@ts-nocheck`
+- [ ] 新增公共边界（Props / 导出函数 / 导出类型）显式声明类型
+- [ ] API 类型引自 `{{config.paths.api_contracts}}/...`，未手写
+- [ ] 联合类型用字面量（`'loading' | 'error'`），不用字符串魔法
+
+### React hooks & 组件（见 [`frontend/react-components`](../react-components/SKILL.md)）
+- [ ] `useEffect` 依赖项正确（无 `react-hooks/exhaustive-deps` 违规，除非 ADR 豁免该行）
+- [ ] Hooks 顶层调用（无条件 / 循环里调用）
+- [ ] `useMemo` / `useCallback` 不过度使用也不缺位（有依赖或回调稳定性需求才用）
+- [ ] 列表 `key` 稳定（不用数组下标）
+- [ ] Context 不放频繁变动的值（避免大范围重渲染）
+
+### 安全（见 [`frontend/security-web`](../security-web/SKILL.md)）
+- [ ] 无 `dangerouslySetInnerHTML`（或有 ADR 豁免 + DOMPurify 清洗）
+- [ ] `href` / `src` 接受用户输入时已校验协议
+- [ ] 敏感字段不写入 LocalStorage / SessionStorage
+- [ ] 生产无 `console.log`（`console.warn` / `console.error` 允许且脱敏）
+- [ ] 日志 / 上报经过脱敏过滤器
+
+### 视觉 / 交互
+- [ ] 视觉回归截图或差异记录已归档
+- [ ] 新增 / 修改状态：loading / empty / error / hover / focus-visible / selected / disabled 全覆盖
+- [ ] `focus-visible` 样式存在，未被 `outline: none` 移除
+- [ ] `prefers-reduced-motion` 场景有降级
+
+### i18n（见 [`frontend/i18n`](../i18n/SKILL.md)）
+- [ ] 所有可见文案用 `i18n.t(key, fallback, values?)`
+- [ ] 三语（`{{config.i18n.languages}}`）**在同一 commit 同步**
+- [ ] fallback 等于基线语言文案
+- [ ] 复数 / 选择场景用 ICU 格式
+- [ ] 日期 / 数字用 `Intl.*`，未硬编码格式
+
+### a11y（见 [`frontend/a11y-web`](../a11y-web/SKILL.md)）
+- [ ] 新增可交互元素有键盘支持
+- [ ] 图片有 `alt` 属性（装饰图 `alt=""`）
+- [ ] 表单 `label` 与输入关联（`htmlFor` / 包裹）
+- [ ] 未使用 `tabindex > 0`
+- [ ] 对比度达标（文字 4.5:1 / 大字号 3:1）
+- [ ] `axe-core` 零 critical / serious violation
+
+### 性能 hazard（见 [`frontend/performance-web`](../performance-web/SKILL.md)）
+- [ ] 大列表 / 树（节点 ≥ 200）已用虚拟滚动
+- [ ] 搜索 / 输入类 handler 有防抖（300ms 起步）
+- [ ] 图片有 `width/height` 属性 + `loading="lazy"` 声明
+- [ ] 新增依赖未导致首屏 JS 增长 > 10%（或有 ADR 豁免）
+
+### Bugfix / Refactor 专用（前端补丁）
+- [ ] Bugfix：复现测试 `git checkout HEAD^` 后仍失败（真的在测 bug）
+- [ ] Refactor：视觉回归**零差异**（前端硬门禁）
+- [ ] Refactor：包体积变化 ≤ ±2%（前端硬门禁）
+
+## Reviewer 评审清单（前端补丁）
+
+### 契约一致性
+- [ ] Props / Events 与 `spec.md` 的 Component Public Contract 一致
+- [ ] 类型引自 `{{config.paths.api_contracts}}` 而非手写
+- [ ] 没有悄悄扩大公开接口（新增未声明的 Props / Event）
+- [ ] 受控 / 非受控边界与 Spec 声明一致
+
+### 边界与错误（前端）
+- [ ] loading / empty / error 都有 UI
+- [ ] 异步取消 / 竞态处理（`AbortController` 或框架等价）
+- [ ] 网络失败 / 超时 / 权限不足 的 fallback UI
+- [ ] ErrorBoundary 位置正确
+
+### 测试覆盖（前端）
+- [ ] 金字塔三层按 design.md 策略就位（unit + integration + e2e）
+- [ ] a11y 自动化测试存在（axe-core / jsx-a11y lint）
+- [ ] 视觉回归截图已归档
+- [ ] 见 [`frontend/testing-web`](../testing-web/SKILL.md) 的完整工具链
+
+### 代码风格（前端）
+- [ ] 命名符合 [`frontend/react-naming`](../react-naming/SKILL.md)
+- [ ] CSS 遵循 [`frontend/css-bem`](../css-bem/SKILL.md)（BEM / 无 `!important` / 无深度嵌套）
+- [ ] 无过度注释 WHAT（见 [`quality/code-hygiene`](../../quality/code-hygiene/SKILL.md)）
+- [ ] 没有未被调用的新抽象（YAGNI）
+
+## 质量门禁（前端补丁）
+
+- [ ] 自评清单（前端补丁）全绿
+- [ ] Reviewer 评审清单（前端补丁）全绿
+- [ ] 视觉回归对照已归档
+- [ ] axe-core 零 critical / serious
+
+> 通用 reviewing 门禁（自评 / Conventional Comments / 分歧升级）见 [`zsk:reviewing`](../../sdlc/reviewing/SKILL.md)