Back to Details

implement-frontend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implement Frontend

前端实现

Apply this skill when the repository already follows this stack:

React + TypeScript + Next.js
React Hook Form + Zod
React Query or Connect Query
Proto-generated API types (when present)

If local conventions differ, preserve existing project standards and apply only the transferable principles.

当代码库已采用以下技术栈时，可应用本规范：

React + TypeScript + Next.js
React Hook Form + Zod
React Query or Connect Query
Proto生成的API类型（若存在）

若项目本地规范与此不同，请保留现有项目标准，仅应用可迁移的原则。

Core workflow

核心工作流

Set ownership boundaries before editing.
- Keep render-only concerns in components.
- Keep fetching, mapping, and business rules in hooks.
- Keep server state in query cache, form state in RHF, and UI-only state in
```
useState
```
  .
Implement with strict typing and explicit mappings.
- Avoid type escapes such as
```
any
```
  ,
```
as any
```
  , and ignore directives.
- Map API models to UI models in mappers instead of casting.
Verify reliability and UX before finishing.
- Cover loading, error, and empty states.
- Add cancellation and cleanup for async work when race conditions are possible.
- Preserve keyboard accessibility and focus behavior.

在编辑前明确职责边界。
- 仅将渲染相关逻辑放在组件中。
- 将数据获取、映射和业务逻辑放在钩子中。
- 服务器状态存储在查询缓存中，表单状态存储在RHF中，仅UI相关状态使用
```
useState
```
  管理。
采用严格类型检查与显式映射实现。
- 避免使用
```
any
```
  、
```
as any
```
  以及忽略类型检查的指令等类型逃逸操作。
- 在映射器中将API模型转换为UI模型，而非直接类型转换。
完成前验证可靠性与用户体验。
- 覆盖加载、错误与空状态。
- 当存在竞态条件风险时，为异步操作添加取消与清理逻辑。
- 保留键盘可访问性与焦点行为。

Non-negotiable checks

强制检查项

Remove duplicate state and
```
useEffect
```
sync loops.
Keep API calls and business logic out of render components.
Invalidate or update only affected query keys.
Use rollback-safe optimistic updates only.
Remove
```
console.*
```
,
```
debugger
```
, dead code, and unused imports.

移除重复状态与
```
useEffect
```
同步循环。
禁止在渲染组件中包含API调用与业务逻辑。
仅使受影响的查询键失效或更新。
仅使用支持回滚的乐观更新。
移除
```
console.*
```
、
```
debugger
```
、死代码与未使用的导入。

Stack guardrails

技术栈约束规则

If the repo uses RHF + Zod, use

createZodResolver

; avoid

zodResolver(schema as any)

.

If using RHF, avoid putting the entire
```
form
```
object in dependency arrays.
Keep proto-to-UI transforms in a dedicated mapper file (for example
```
utils/proto-mappers.ts
```
) when proto contracts are used.

若代码库使用RHF + Zod，请使用
```
createZodResolver
```
；避免使用
```
zodResolver(schema as any)
```
。
若使用RHF，避免将整个
```
form
```
对象放入依赖数组。
当使用Proto契约时，将Proto到UI的转换逻辑放在专用的映射文件中（例如
```
utils/proto-mappers.ts
```
）。

References

参考文档

Use
```
react-patterns.md
```
for forms, hooks, state ownership, query usage, and accessibility.
Use
```
typescript-patterns.md
```
for type hygiene, proto typing, and code organization.

表单、钩子、状态归属、查询使用与可访问性相关内容，请参考
```
react-patterns.md
```
。
类型规范、Proto类型与代码组织相关内容，请参考
```
typescript-patterns.md
```
。