@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/templates/shared/rules/fec-naming-conventions.md

@@ -1,33 +1,33 @@
-# 命名规范
+# Naming convention
 
-## 文件与目录命名
+## File and directory naming
 
-| 类型 | 命名风格 | 示例 |
+| Type | Naming Style | Example |
 |------|----------|------|
-| 页面组件 | PascalCase + `Page` 后缀 | `UserDetailPage.tsx` / `UserDetailPage.vue` |
-| 布局组件 | PascalCase + `Layout` 后缀 | `MainLayout.tsx` / `MainLayout.vue` |
-| 通用组件 | PascalCase | `DataTable.tsx` / `AppButton.vue` |
-| Hooks / Composables | camelCase + `use` 前缀 | `useAuth.ts`、`useDebounce.ts` |
-| Store 文件 | camelCase + `Store` 后缀 | `authStore.ts`、`uiStore.ts` |
-| API 文件 | camelCase | `api.ts` 或按领域命名 `userApi.ts` |
-| 工具函数 | camelCase | `format.ts`、`validators.ts` |
-| 类型文件 | camelCase | `types.ts`、`models.ts` |
-| 常量文件 | camelCase | `constants.ts`、`config.ts` |
-| 测试文件 | 与源文件同名 + `.spec` / `.test` | `Button.spec.tsx`、`useAuth.spec.ts` |
-| 样式文件 | 组件名 + `.styles` + 扩展名 | `Button.styles.css`、`DataTable.styles.scss`；使用 styled-components 时为 `ComponentName.styles.ts` |
-| 语言包 | 语言代码（BCP 47） | `zh-CN.json`、`en-US.json` |
-| 目录名 | PascalCase（组件/页面）或 kebab-case（功能模块） | `UserDetail/`、`auth/`、`order/` |
-
-## 组件命名
+| Page component | PascalCase + `Page` suffix | `UserDetailPage.tsx` / `UserDetailPage.vue` |
+| Layout component | PascalCase + `Layout` suffix | `MainLayout.tsx` / `MainLayout.vue` |
+| Common components | PascalCase | `DataTable.tsx` / `AppButton.vue` |
+| Hooks / Composables | camelCase + `use` prefix | `useAuth.ts`, `useDebounce.ts` |
+| Store file | camelCase + `Store` suffix | `authStore.ts`, `uiStore.ts` |
+| API documentation | camelCase | `api.ts` or by domain `userApi.ts` |
+| Utility functions | camelCase | `format.ts`, `validators.ts` |
+| Type files | camelCase | `types.ts`, `models.ts` |
+| Constant files | camelCase | `constants.ts`, `config.ts` |
+| Test file | Same name as source file + `.spec` / `.test` | `Button.spec.tsx`, `useAuth.spec.ts` |
+| Style file | Component name + `.styles` + extension | `Button.styles.css`, `DataTable.styles.scss`; `ComponentName.styles.ts` when using styled-components |
+| Language pack | Language code (BCP 47) | `zh-CN.json`, `en-US.json` |
+| Directory name | PascalCase (component/page) or kebab-case (function module) | `UserDetail/`, `auth/`, `order/` |
+
+## Component naming
 
 ### React
 
 ```tsx
-// 文件名与组件名一致
+//The file name is consistent with the component name
 // src/components/DataTable/DataTable.tsx
 export function DataTable({ data, columns }: DataTableProps) { ... }
 
-// 页面组件加 Page 后缀
+//Add Page suffix to page component
 // src/pages/UserDetail/UserDetailPage.tsx
 export default function UserDetailPage() { ... }
 ```
@@ -35,86 +35,86 @@ export default function UserDetailPage() { ... }
 ### Vue
 
 ```vue
-<!-- 文件名与组件名一致 -->
+<!-- The file name is consistent with the component name -->
 <!-- src/components/AppButton/AppButton.vue -->
 <script setup lang="ts">
-// 无需 defineOptions，文件名即组件名
+// No need for defineOptions, the file name is the component name
 </script>
 ```
 
-- 多词组件名（避免与 HTML 原生标签冲突）
-- Vue 全局组件推荐使用 `App` 前缀（`AppButton`、`AppModal`）
-- 模板中使用 PascalCase 引用：`<AppButton>` 而非 `<app-button>`
+- Multi-word component names (to avoid conflicts with HTML native tags)
+- Vue global components are recommended to use the `App` prefix (`AppButton`, `AppModal`)
+- Use PascalCase reference in template: `<AppButton>` instead of `<app-button>`
 
-## 变量与函数命名
+## Variable and function naming
 
-| 类型 | 命名风格 | 示例 |
+| Type | Naming Style | Example |
 |------|----------|------|
-| 普通变量 | camelCase | `userName`、`isLoading`、`pageSize` |
-| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE` |
-| 布尔值 | `is` / `has` / `should` / `can` 前缀 | `isVisible`、`hasPermission`、`canEdit` |
-| 事件处理（组件内） | `handle` 前缀 | `handleClick`、`handleSubmit` |
-| 回调 Props | `on` 前缀 | `onClick`、`onSubmit`、`onChange` |
-| 数组 | 复数名词 | `users`、`orderItems`、`selectedIds` |
-| Map / Record | `xxxMap` 或 `xxxByYyy` | `userMap`、`permissionsById` |
-| Ref (Vue) | 不加 `Ref` 后缀 | `count`（不用 `countRef`） |
-| 接口 | PascalCase，不加 `I` 前缀 | `UserProfile`（不用 `IUserProfile`） |
-| Props 接口 | 组件名 + `Props` | `DataTableProps`、`UserFormProps` |
-| Emits 接口 | 组件名 + `Emits` | `UserFormEmits` |
-| 枚举 | PascalCase，成员用 PascalCase | `OrderStatus.Pending` |
-| 泛型参数 | 单字母大写或语义化 | `T`、`TData`、`TItem` |
-
-## CSS 类命名
-
-- 与项目约定保持一致（BEM / CSS Modules / Tailwind / Atomic CSS）
-- 如果使用 CSS Modules，类名用 camelCase：`.headerTitle`、`.cardBody`
-- 如果使用 BEM，遵循 `block__element--modifier` 格式
-- CSS 变量使用 kebab-case：`--color-primary`、`--spacing-md`
-
-## 路由命名
-
-| 类型 | 命名风格 | 示例 |
+| Ordinary variables | camelCase | `userName`, `isLoading`, `pageSize` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `DEFAULT_PAGE_SIZE` |
+| Boolean value | `is` / `has` / `should` / `can` prefix | `isVisible`, `hasPermission`, `canEdit` |
+| Event handling (inside component) | `handle` prefix | `handleClick`, `handleSubmit` |
+| Callback Props | `on` prefix | `onClick`, `onSubmit`, `onChange` |
+| Array | Plural noun | `users`, `orderItems`, `selectedIds` |
+| Map / Record | `xxxMap` or `xxxByYyy` | `userMap`, `permissionsById` |
+| Ref (Vue) | Without `Ref` suffix | `count` (without `countRef`) |
+| Interface | PascalCase, without `I` prefix | `UserProfile` (without `IUserProfile`) |
+| Props interface | component name + `Props` | `DataTableProps`, `UserFormProps` |
+| Emits interface | component name + `Emits` | `UserFormEmits` |
+| Enum | PascalCase, members use PascalCase | `OrderStatus.Pending` |
+| Generic parameters | Single letter capitalization or semantic | `T`, `TData`, `TItem` |
+
+## CSS class naming
+
+- Aligned with project conventions (BEM/CSS Modules/Tailwind/Atomic CSS)
+- If using CSS Modules, use camelCase for class names: `.headerTitle`, `.cardBody`
+- If using BEM, follow the `block__element--modifier` format
+- CSS variables use kebab-case: `--color-primary`, `--spacing-md`
+
+## Route naming
+
+| Type | Naming Style | Example |
 |------|----------|------|
-| 路由路径 | kebab-case | `/user-detail`、`/order-list` |
-| 路由名称 | PascalCase | `UserDetail`、`OrderList` |
-| 路由参数 | camelCase | `:userId`、`:orderId` |
-| 查询参数 | camelCase | `?pageSize=10&sortBy=name` |
-| 路径常量 | UPPER_SNAKE_CASE | `ROUTE_USER_DETAIL = '/user-detail'` |
+| routing path | kebab-case | `/user-detail`, `/order-list` |
+| Route name | PascalCase | `UserDetail`, `OrderList` |
+| Routing parameters | camelCase | `:userId`, `:orderId` |
+| Query parameters | camelCase | `?pageSize=10&sortBy=name` |
+| Path constants | UPPER_SNAKE_CASE | `ROUTE_USER_DETAIL = '/user-detail'` |
 
-## API 命名
+## API naming
 
-| 类型 | 命名风格 | 示例 |
+| Type | Naming Style | Example |
 |------|----------|------|
-| GET 列表 | `getXxxList` | `getUserList(params)` |
-| GET 单条 | `getXxxDetail` / `getXxxById` | `getUserDetail(id)` |
-| POST 创建 | `createXxx` | `createOrder(data)` |
-| PUT 更新 | `updateXxx` | `updateUser(id, data)` |
-| DELETE 删除 | `deleteXxx` | `deleteOrder(id)` |
-| DTO 类型 | 动词 + 名词 + `DTO` | `CreateOrderDTO`、`UpdateUserDTO` |
-| 响应类型 | 名词 | `User`、`Order`、`PageResult<User>` |
-
-## i18n Key 命名
-
-- 使用点分命名空间：`module.section.label`
-- 示例：`user.form.username`、`common.button.submit`、`error.network.timeout`
-- 不使用中文 / 拼音作为 key
-
-## 反模式
-
-- 文件名和组件名不一致（`user-table.tsx` 导出 `DataGrid`）
-- 同一项目混用多种命名风格（有的 kebab-case 有的 PascalCase）
-- 使用缩写或不明确的名称（`btn`、`usr`、`tmp`、`handleA`）
-- 布尔值没有语义前缀（`visible` → 应为 `isVisible`）
-- 常量不用大写（`maxRetry` → 应为 `MAX_RETRY`）
-- CSS 变量硬编码在组件中而非使用统一变量
-
-## 检查清单
-
-- [ ] 文件名与导出的组件/函数名一致
-- [ ] 页面组件有 `Page` 后缀，布局组件有 `Layout` 后缀
-- [ ] 布尔变量使用 `is` / `has` / `can` / `should` 前缀
-- [ ] 事件处理用 `handle` 前缀，回调 Props 用 `on` 前缀
-- [ ] 常量使用 UPPER_SNAKE_CASE
-- [ ] 路由路径使用 kebab-case，路由名使用 PascalCase
-- [ ] API 函数命名与 HTTP 方法语义一致
-- [ ] i18n key 使用点分命名空间，无硬编码文案
+| GET list | `getXxxList` | `getUserList(params)` |
+| GET single item | `getXxxDetail` / `getXxxById` | `getUserDetail(id)` |
+| POST Create | `createXxx` | `createOrder(data)` |
+| PUT update | `updateXxx` | `updateUser(id, data)` |
+| DELETE delete | `deleteXxx` | `deleteOrder(id)` |
+| DTO type | Verb + Noun + `DTO` | `CreateOrderDTO`, `UpdateUserDTO` |
+| Response type | Noun | `User`, `Order`, `PageResult<User>` |
+
+## i18n Key naming
+
+- Use dotted namespace: `module.section.label`
+- Examples: `user.form.username`, `common.button.submit`, `error.network.timeout`
+- Do not use Chinese/Pinyin as key
+
+## Anti-pattern
+
+- File name and component name are inconsistent (`user-table.tsx` exports `DataGrid`)
+- Mixing multiple naming styles (some kebab-case, some PascalCase) in the same project
+- Use abbreviated or ambiguous names (`btn`, `usr`, `tmp`, `handleA`)
+- Boolean values have no semantic prefix (`visible` → should be `isVisible`)
+- Constants do not need to be capitalized (`maxRetry` → should be `MAX_RETRY`)
+- CSS variables are hardcoded in components instead of using uniform variables
+
+## Checklist
+
+- [ ] The file name is consistent with the exported component/function name
+- [ ] Page components have the `Page` suffix, and layout components have the `Layout` suffix.
+- [ ] Boolean variables use `is` / `has` / `can` / `should` prefixes
+- [ ] Event handling is prefixed with `handle`, callback Props are prefixed with `on`
+- [ ] constant using UPPER_SNAKE_CASE
+- [ ] Use kebab-case for the routing path and PascalCase for the routing name.
+- [ ] API function naming is consistent with HTTP method semantics
+- [ ] i18n key uses dotted namespace, no hardcoded copy

package/templates/shared/rules/fec-performance.md

@@ -1,21 +1,21 @@
-# 前端性能规则
+# Front-end performance rules
 
-凡是新增页面、组件、资源加载或数据请求时，都应用本文件。
+This document will be used whenever new pages, components, resource loading or data requests are added.
 
-## 核心原则
+## Core Principles
 
-- 默认懒加载，按需加载
-- 减少首屏关键资源
-- 避免不必要的重渲染
-- 关注 Core Web Vitals
-- 前端构建必须同时验证开发体验和生产产物，不能只看 dev server 正常
-- 在上下文或任务边界不清时，不启动大规模性能重构；先定位瓶颈再改代码
-- 对长时间运行的命令保留可回看日志，必要时使用终端会话、CI artifact 或测试报告
-- 每项性能建议都要绑定证据、影响范围、验证方式和回退风险
+- Lazy loading by default, loading on demand
+- Reduce key resources on the first screen
+- Avoid unnecessary re-rendering
+- Follow Core Web Vitals
+- The front-end build must verify the development experience and production products at the same time. You cannot just check whether the dev server is normal.
+- Do not initiate large-scale performance refactoring when the context or task boundaries are unclear; locate bottlenecks first and then change the code
+- Keep reviewable logs of long-running commands, using terminal sessions, CI artifacts, or test reports when necessary
+- Each performance recommendation must be bound with evidence, scope of impact, verification methods and rollback risks
 
-## 代码分割与懒加载
+## Code splitting and lazy loading
 
-### 路由级分割
+### Routing level segmentation
 
 ```tsx
 // React
@@ -25,77 +25,77 @@ const Dashboard = lazy(() => import('./pages/Dashboard'));
 const Dashboard = () => import('./pages/Dashboard.vue');
 ```
 
-### 组件级分割
+### Component level segmentation
 
-仅在以下场景使用组件级懒加载：
+Only use component-level lazy loading in the following scenarios:
 
-- 重型第三方库（图表、编辑器、地图）
-- 条件渲染的大型模块（如设置面板、高级筛选）
-- 不在首屏可视区域的内容
+- Heavy-duty third-party libraries (charts, editors, maps)
+- Large modules for conditional rendering (such as settings panel, advanced filtering)
+- Content that is not in the visible area of the first screen
 
-## 渲染性能
+## Rendering performance
 
 ### React
 
-- 合理使用 `React.memo` 避免不必要的重渲染
-- `useMemo` / `useCallback` 仅在依赖稳定且子组件使用 memo 时才有意义
-- 列表渲染必须使用稳定的 `key`
-- 避免在渲染函数内创建新对象、数组或函数
+- Use `React.memo` wisely to avoid unnecessary re-rendering
+- `useMemo` / `useCallback` only makes sense if the dependency is stable and the subcomponent uses memo
+- List rendering must use a stable `key`
+- Avoid creating new objects, arrays or functions inside render functions
 
 ### Vue
 
-- 使用 `computed` 而非 `watch` + 手动赋值
-- 大列表使用虚拟滚动
-- 避免在 `v-for` 中使用 `v-if`
-- 使用 `shallowRef` / `shallowReactive` 优化大型对象
-
-## 资源优化
-
-- 图片使用 WebP/AVIF 格式，提供适当尺寸
-- 图标优先使用 SVG sprite 或 icon font，避免大量独立图片请求
-- 字体按需加载，使用 `font-display: swap`
-- 第三方依赖按需导入（如 `import { Button } from 'antd'` 而非 `import antd from 'antd'`）
-
-## Vite 构建与开发性能
-
-使用 Vite 时额外遵守：
-
-- `vite build` 不做类型检查，CI 必须单独执行 `tsc --noEmit` 或接入 `vite-plugin-checker`
-- 慢启动先用 `vite --profile` 定位插件、解析或预构建瓶颈
-- 大项目可使用 `server.warmup.clientFiles` 预热核心入口
-- CJS/UMD 依赖互操作问题优先通过 `optimizeDeps.include` 处理
-- 手动分包优先使用稳定对象形式，不要把每个 `node_modules` 包拆成独立 chunk
-- 组件库模式必须 externalize peer dependencies，并单独产出类型声明
-- `vite preview` 只用于本地构建烟测，不是生产服务器
-
-## 数据请求
-
-- 避免瀑布式请求（串行依赖），尽可能并行
-- 合理使用缓存策略（SWR / React Query / VueQuery）
-- 分页加载或虚拟滚动处理大数据集
-- 防抖/节流处理高频触发的请求（搜索、滚动）
-
-## 检查清单
-
-- [ ] 是否记录核心路由、设备、网络和当前指标
-- [ ] 路由是否按需加载
-- [ ] 重型组件是否懒加载
-- [ ] 大列表是否使用虚拟滚动或分页
-- [ ] 图片是否使用现代格式和合理尺寸
-- [ ] 第三方库是否按需导入
-- [ ] 是否存在不必要的重渲染
-- [ ] Vite 项目是否单独执行 typecheck
-- [ ] Vite 构建产物是否经过 `vite build` 和本地预览烟测
-- [ ] 是否复查 loading、error、empty、disabled 和移动端状态没有被优化破坏
-
-## 反模式
-
-- 将所有路由打包在一个 chunk 中
-- 在首屏加载整个图表库或编辑器
-- 在组件内重复创建相同的 API 请求
-- 大列表不做虚拟化直接渲染数千行 DOM
-- 频繁操作（如输入、滚动）不做防抖/节流
-- 认为 `vite build` 通过就代表 TypeScript 没有错误
-- 设置 `envPrefix: ""` 或把服务端密钥注入客户端 bundle
-- 未先复现卡顿、包体积或 Web Vitals 指标，就做大范围“性能优化”
-- 为追求实验室分数删除状态反馈、降低可访问性或牺牲主路径可维护性
+- Use `computed` instead of `watch` + manual assignment
+- Use virtual scrolling for large lists
+- Avoid using `v-if` inside `v-for`
+- Use `shallowRef` / `shallowReactive` to optimize large objects
+
+## Resource optimization
+
+- Images use WebP/AVIF format and provide appropriate sizes
+- For icons, use SVG sprite or icon font first to avoid a large number of independent image requests
+- Fonts are loaded on demand, use `font-display: swap`
+- Third-party dependencies are imported on demand (such as `import { Button } from 'antd'` instead of `import antd from 'antd'`)
+
+## Vite build and development performance
+
+Additional compliance when using Vite:
+
+- `vite build` does not do type checking, CI must execute `tsc --noEmit` separately or access `vite-plugin-checker`
+- Use `vite --profile` to locate plug-in, parsing or pre-built bottlenecks before slow start
+- Large projects can use `server.warmup.clientFiles` to warm up the core entrance
+- CJS/UMD dependency interoperability issues are first handled through `optimizeDeps.include`
+- For manual sub-packaging, use stable object form first, do not split each `node_modules` package into independent chunks
+- Component library mode must externalize peer dependencies and produce type declarations separately
+- `vite preview` is only used for local build smoke tests, not production servers
+
+## Data request
+
+- Avoid waterfall requests (serial dependencies), parallelize as much as possible
+- Proper use of caching strategies (SWR/React Query/VueQuery)
+- Paged loading or virtual scrolling for processing large data sets
+- Anti-shake/throttle processing of high-frequency triggered requests (search, scrolling)
+
+## Checklist
+
+- [ ] Whether to record core routing, device, network and current metrics
+- [ ] Whether the route is loaded on demand
+- [ ] Whether heavy components are lazy loaded
+- [ ] Whether to use virtual scrolling or paging for large lists
+- [ ] Whether the image uses a modern format and reasonable size
+- [ ] Whether third-party libraries are imported on demand
+- [ ] Whether there is unnecessary re-rendering
+- [ ] Whether the Vite project executes typecheck separately
+- [ ] Whether the Vite build product has passed the `vite build` and local preview smoke tests
+- [ ] Whether to review loading, error, empty, disabled and mobile status are not destroyed by optimization
+
+## Anti-pattern
+
+- Pack all routes in one chunk
+- Load the entire chart library or editor on the first screen
+- Create the same API request repeatedly within the component
+- Large lists directly render thousands of lines of DOM without virtualization
+- No anti-shake/throttling for frequent operations (such as input, scrolling)
+- It is considered that passing `vite build` means that TypeScript has no errors
+- Set `envPrefix: ""` or inject the server key into the client bundle
+- Doing extensive “performance optimization” without first reproducing lag, packet size or Web Vitals indicators
+- Remove status feedback, reduce accessibility, or sacrifice main path maintainability in pursuit of lab scores

package/templates/shared/rules/fec-react.md

@@ -1,82 +1,82 @@
-# React 规则
+# React rules
 
-当仓库或目标模块使用 React 时，应用本文件。
+This file applies when the repository or target module uses React.
 
-## 技术栈
+## Technology stack
 
-<!-- 请根据项目实际情况修改 -->
+<!-- Please modify according to the actual situation of the project -->
 
-- 框架: React + TypeScript
-- 样式: Tailwind CSS + CSS Modules
-- 状态管理: Zustand / Redux Toolkit / Jotai（按项目实际选择）
-- UI 组件库: 按项目实际选择（如 Ant Design、Material UI 或内部 Design System）
-- 版本与依赖：新建模块、补充 `package.json` 或更新本节前，优先采用彼此兼容的主流稳定版本（对齐官方文档、脚手架默认值或包管理器推荐），避免混用已停止维护或与仓库主线 major 不匹配的依赖。
+- Framework: React + TypeScript
+- Style: Tailwind CSS + CSS Modules
+- Status management: Zustand / Redux Toolkit / Jotai (select according to the actual project)
+- UI component library: actual selection by project (such as Ant Design, Material UI or internal Design System)
+- Versions and dependencies: Before creating a new module, supplementing `package.json` or updating this section, give priority to using mainstream stable versions that are compatible with each other (align with official documents, scaffolding defaults or package manager recommendations) to avoid mixing dependencies that have stopped maintaining or do not match the major of the mainline of the warehouse.
 
-## React 组件规范
+## React component specification
 
-- 使用**函数组件**、Hooks 与 TypeScript；**不要**新增类组件（含手写 Error Boundary，统一用 `react-error-boundary` 等库）
-- 保持组件小而可组合
-- 将可复用逻辑提取到 hooks
-- props 保持明确且类型清晰
-- 保持可访问性与键盘交互
-- 优先使用可推导状态，避免重复维护 state
-- 在创建新基础组件前，先复用现有设计系统
-- 禁止使用 any，优先使用 unknown
-- CSS 命名遵循 BEM（CSS Modules 场景）
+- Use **Function Components**, Hooks and TypeScript; **Do not** add new class components (including handwritten Error Boundary, use `react-error-boundary` and other libraries)
+- Keep components small and composable
+- Extract reusable logic into hooks
+- Keep props explicit and clearly typed
+- Maintain accessibility with keyboard interaction
+- Prioritize the use of deducible state to avoid repeated state maintenance
+- Reuse existing design systems before creating new base components
+- It is forbidden to use any, prefer unknown
+- CSS naming follows BEM (CSS Modules scenario)
 
-## 模式与最佳实践（React）
+## Patterns and Best Practices (React)
 
-- **组合**：用小组件 + `children`/props 拼装；避免宽布尔 props 与假「继承」。
-- **复合组件**：根组件用 Context 向子组件暴露状态；子组件在缺少 Context 时明确报错。
-- **Render Props**：仅在需要封装数据态并把渲染交给上层时考虑；多数场景优先自定义 Hook + 普通组件。
-- **Context + useReducer**：中等复杂度的多子树客户端状态；勿把高频变化大对象放在顶层 Context；服务端数据用 React Query / SWR。
-- **表单**：中大型表单优先 React Hook Form + Zod；避免单文件巨型受控 state。
-- **Error Boundary**：关键模块用 **`react-error-boundary`**（或团队统一的同类库）在模块边界兜底；业务组件一律函数式，不手写类组件 Error Boundary。
-- **性能**：`useMemo`/`useCallback`/`React.memo` 按需使用；长列表用虚拟列表（如 TanStack Virtual、react-window）；昂贵计算注意不可变派生（勿原地 `sort` 原数组）。
-- **动效**：Framer Motion 或 CSS transition；尊重 `prefers-reduced-motion`。
-- **无障碍**：复合控件补齐 `role`/`aria-*` 与键盘操作；弹窗管理焦点落入与关闭后恢复。
-- **Next.js**：App Router 与 Server Components 相关约定以项目 Next 规则为准。
+- **Composition**: Use widgets + `children`/props to assemble; avoid wide boolean props and fake "inheritance".
+- **Composite component**: The root component uses Context to expose state to sub-components; sub-components explicitly report an error when Context is missing.
+- **Render Props**: Only considered when it is necessary to encapsulate the data state and hand over the rendering to the upper layer; in most scenarios, custom Hook + ordinary components are given priority.
+- **Context + useReducer**: Medium complexity multi-subtree client state; do not put high-frequency changing large objects in the top-level Context; use React Query / SWR for server-side data.
+- **Form**: Prioritize medium and large forms with React Hook Form + Zod; avoid single-file giant controlled state.
+- **Error Boundary**: Key modules use **`react-error-boundary`** (or a similar library unified by the team) to cover the module boundaries; business components must be functional, and no handwritten class components Error Boundary.
+- **Performance**: Use `useMemo`/`useCallback`/`React.memo` on demand; use virtual lists for long lists (such as TanStack Virtual, react-window); pay attention to immutable derivation for expensive calculations (do not `sort` the original array in place).
+- **Motion**: Framer Motion or CSS transition; respect `prefers-reduced-motion`.
+- **Accessibility**: Compound controls complement `role`/`aria-*` and keyboard operations; pop-up window management focus is dropped and restored after closing.
+- **Next.js**: The relevant agreements between App Router and Server Components are subject to the project Next rules.
 
-## React 实现指导
+## React Implementation Guide
 
-创建新组件前：
+Before creating a new component:
 
-1. 先搜索是否已存在等价组件
-2. 判断逻辑是否应该放入自定义 hook
-3. 与项目当前样式方案保持一致
+1. First search whether equivalent components already exist
+2. Determine whether the logic should be put into a custom hook
+3. Be consistent with the current style scheme of the project
 
-编辑 React 组件时：
+When editing a React component:
 
-- 避免在同一个文件里混合数据请求、重业务逻辑和展示逻辑
-- 避免设计过宽或语义不清的 props API
-- 对局部问题避免滥用 context
-- 保持条件渲染可读，必要时提取重复分支
+- Avoid mixing data requests, heavy business logic and presentation logic in the same file
+- Avoid designing props APIs that are too broad or have unclear semantics
+- Avoid abusing context for local problems
+- Keep conditional rendering readable and extract duplicate branches if necessary
 
-## React 文件组织
+## React file organization
 
-优先遵循仓库已有约定。
-常见输出可能包括：
+Priority is given to following existing agreements in the warehouse.
+Common output may include:
 
 - `Component.tsx`
 - `Component.types.ts`
 - `hooks/useComponentLogic.ts`
-- `ComponentName.styles.css`（普通 CSS / CSS Modules；使用 styled-components 时为 `ComponentName.styles.ts`）
-- 如果仓库采用就近测试，则补充测试文件，如：`__tests__/Component.spec.tsx`
+- `ComponentName.styles.css` (plain CSS / CSS Modules; `ComponentName.styles.ts` when using styled-components)
+- If the warehouse uses nearby testing, add test files, such as: `__tests__/Component.spec.tsx`
 
-## 组件文件规模
+## Component file size
 
-- 单个组件文件保持**职责单一**、语义清晰、易于维护。
-- **行数参考**：优先将单文件控制在约 **300 行**以内；超过 **500 行**应视为**强烈拆分信号**。
-- **未到 500 行也应拆分**的情形：同时存在**复杂状态交织**、**过多副作用**、**JSX 嵌套过深**、**密集条件分支**、数据获取与 UI 长期混在同一文件等，使单文件难以一眼把握时，应拆为**子组件**、**自定义 Hooks**、**工具函数**、**常量**与**类型定义**等独立单元（目录与命名仍遵循上文「React 文件组织」）。
+- A single component file maintains a single responsibility, clear semantics, and is easy to maintain.
+- **Line number reference**: Prioritize the single file to be controlled within about **300 lines**; more than **500 lines** should be regarded as a **strong splitting signal**.
+- **Situations that should be split even if it is less than 500 lines**: There are **complex state interleaving**, **too many side effects**, **JSX too deep nesting**, **dense conditional branches**, data acquisition and UI are mixed in the same file for a long time, etc., making it difficult to grasp a single file at a glance. It should be split into independent units such as **subcomponents**, **custom Hooks**, **tool functions**, **constants** and **type definitions** (the directory and naming still follow the "React file organization" above).
 
-## React 反模式
+## React anti-patterns
 
-避免：
+Avoid:
 
-- 新建**类组件**或手写类式 Error Boundary（应使用函数组件 + `react-error-boundary` 等）
-- 对可推导值使用多余 state
-- 大段 JSX 不拆成子组件
-- 单文件堆叠过多职责与行数，**逾 500 行或复杂度已高**仍拒不拆分（参见上文「组件文件规模」）
-- 使用不稳定 key
-- 在 props 和 hooks 中无理由使用 `any`
-- 没有充分理由时引入第二套样式体系
+- Create a new **class component** or handwritten class Error Boundary (function component + `react-error-boundary`, etc. should be used)
+- Use redundant state for derivable values
+- Large sections of JSX are not broken into subcomponents
+- A single file is stacked with too many responsibilities and lines. It exceeds 500 lines or has high complexity and still refuses to be split (see "Component file size" above)
+- Use unstable keys
+- Use `any` in props and hooks without reason
+- Introduce a second style system when there is no good reason