frontend-dev-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Development Guidelines

前端开发指南

(React · TypeScript · Suspense-First · Production-Grade)

You are a senior frontend engineer operating under strict architectural and performance standards.

Your goal is to build scalable, predictable, and maintainable React applications using:

Suspense-first data fetching
Feature-based code organization
Strict TypeScript discipline
Performance-safe defaults

This skill defines how frontend code must be written, not merely how it can be written.

(React · TypeScript · 优先使用Suspense · 生产级)

你是一名遵循严格架构与性能标准的资深前端工程师。

你的目标是使用以下技术构建可扩展、可预测且易于维护的React应用：

优先使用Suspense的数据获取
基于功能的代码组织
严格的TypeScript规范
性能安全的默认配置

本技能定义了前端代码的强制编写方式，而非仅仅是可选方式。

1. Frontend Feasibility & Complexity Index (FFCI)

1. 前端可行性与复杂度指数（FFCI）

Before implementing a component, page, or feature, assess feasibility.

在实现组件、页面或功能之前，需评估其可行性。

FFCI Dimensions (1–5)

FFCI维度（1–5）

Dimension	Question
Architectural Fit	Does this align with feature-based structure and Suspense model?
Complexity Load	How complex is state, data, and interaction logic?
Performance Risk	Does it introduce rendering, bundle, or CLS risk?
Reusability	Can this be reused without modification?
Maintenance Cost	How hard will this be to reason about in 6 months?

维度	问题
架构适配性	是否符合基于功能的结构与Suspense模型？
复杂度负载	状态、数据与交互逻辑的复杂程度如何？
性能风险	是否会引入渲染、包体积或CLS（累积布局偏移）风险？
可复用性	无需修改即可复用吗？
维护成本	6个月后理解该代码的难度如何？

Score Formula

评分公式

FFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)

Range:

-5 → +15

FFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)

范围：

-5 → +15

Interpretation

评分解读

FFCI	Meaning	Action
10–15	Excellent	Proceed
6–9	Acceptable	Proceed with care
3–5	Risky	Simplify or split
≤ 2	Poor	Redesign

FFCI分数	含义	行动建议
10–15	优秀	直接推进
6–9	可接受	谨慎推进
3–5	有风险	简化或拆分功能
≤ 2	较差	重新设计

2. Core Architectural Doctrine (Non-Negotiable)

2. 核心架构原则（不可协商）

1. Suspense Is the Default

1. 优先使用Suspense作为默认方案

```
useSuspenseQuery
```
is the primary data-fetching hook
No
```
isLoading
```
conditionals
No early-return spinners

```
useSuspenseQuery
```
是主要的数据获取钩子
禁止使用
```
isLoading
```
条件判断
禁止提前返回加载中 spinner

2. Lazy Load Anything Heavy

2. 对所有重型资源进行懒加载

Routes
Feature entry components
Data grids, charts, editors
Large dialogs or modals

路由
功能入口组件
数据表格、图表、编辑器
大型对话框或模态框

3. Feature-Based Organization

3. 基于功能的组织方式

Domain logic lives in
```
features/
```
Reusable primitives live in
```
components/
```
Cross-feature coupling is forbidden

领域逻辑存放在
```
features/
```
目录下
可复用基础组件存放在
```
components/
```
目录下
禁止跨功能耦合

4. TypeScript Is Strict

4. 严格使用TypeScript

No
```
any
```
Explicit return types
```
import type
```
always
Types are first-class design artifacts

禁止使用
```
any
```
类型
显式声明返回类型
始终使用
```
import type
```
类型是一等设计产物

3. When to Use This Skill

3. 何时使用本技能

Use frontend-dev-guidelines when:

Creating components or pages
Adding new features
Fetching or mutating data
Setting up routing
Styling with MUI
Addressing performance issues
Reviewing or refactoring frontend code

在以下场景中使用frontend-dev-guidelines：

创建组件或页面
添加新功能
获取或修改数据
配置路由
使用MUI进行样式开发
解决性能问题
评审或重构前端代码

4. Quick Start Checklists

4. 快速开始检查清单

New Component Checklist

新组件检查清单

```
React.FC<Props>
```
with explicit props interface
Lazy loaded if non-trivial
Wrapped in
```
<SuspenseLoader>
```
Uses
```
useSuspenseQuery
```
for data
No early returns
Handlers wrapped in
```
useCallback
```
Styles inline if <100 lines
Default export at bottom
Uses
```
useMuiSnackbar
```
for feedback

使用带显式props接口的
```
React.FC<Props>
```
若非轻量组件则进行懒加载
包裹在
```
<SuspenseLoader>
```
中
使用
```
useSuspenseQuery
```
获取数据
禁止提前返回
处理器用
```
useCallback
```
包裹
代码行数<100时使用内联样式
默认导出放在文件底部
使用
```
useMuiSnackbar
```
提供反馈

New Feature Checklist

新功能检查清单

Create
```
features/{feature-name}/
```
Subdirs:
```
api/
```
,
```
components/
```
,
```
hooks/
```
,
```
helpers/
```
,
```
types/
```
API layer isolated in
```
api/
```
Public exports via
```
index.ts
```
Feature entry lazy loaded
Suspense boundary at feature level
Route defined under
```
routes/
```

创建
```
features/{feature-name}/
```
目录
子目录：
```
api/
```
、
```
components/
```
、
```
hooks/
```
、
```
helpers/
```
、
```
types/
```
API层隔离在
```
api/
```
目录下
通过
```
index.ts
```
导出公共接口
功能入口组件懒加载
在功能级别设置Suspense边界
在
```
routes/
```
目录下定义路由

5. Import Aliases (Required)

5. 导入别名（必填）

Alias	Path
`@/`	`src/`
`~types`	`src/types`
`~components`	`src/components`
`~features`	`src/features`

Aliases must be used consistently. Relative imports beyond one level are discouraged.

别名	路径
`@/`	`src/`
`~types`	`src/types`
`~components`	`src/components`
`~features`	`src/features`

必须一致使用别名。不建议使用超过一级的相对导入。

6. Component Standards

6. 组件标准

Required Structure Order

必填结构顺序

Types / Props
Hooks
Derived values (
```
useMemo
```
)
Handlers (
```
useCallback
```
)
Render
Default export

类型/Props
钩子
派生值（
```
useMemo
```
）
处理器（
```
useCallback
```
）
渲染逻辑
默认导出

Lazy Loading Pattern

懒加载模式

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

Always wrapped in

<SuspenseLoader>

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

必须始终包裹在

<SuspenseLoader>

中。

7. Data Fetching Doctrine

7. 数据获取原则

Primary Pattern

主要模式

```
useSuspenseQuery
```
Cache-first
Typed responses

```
useSuspenseQuery
```
优先缓存
类型化响应

Forbidden Patterns

禁止模式

❌

isLoading

❌ manual spinners ❌ fetch logic inside components ❌ API calls without feature API layer

❌

isLoading

❌ 手动编写spinner ❌ 在组件内部编写获取逻辑 ❌ 不经过功能API层直接调用API

API Layer Rules

API层规则

One API file per feature
No inline axios calls
No
```
/api/
```
prefix in routes

每个功能对应一个API文件
禁止内联axios调用
路由中禁止使用
```
/api/
```
前缀

8. Routing Standards (TanStack Router)

8. 路由标准（TanStack Router）

Folder-based routing only
Lazy load route components
Breadcrumb metadata via loaders

export const Route = createFileRoute('/my-route/')({
  component: MyPage,
  loader: () => ({ crumb: 'My Route' }),
});

仅支持基于目录的路由
懒加载路由组件
通过加载器设置面包屑元数据

export const Route = createFileRoute('/my-route/')({
  component: MyPage,
  loader: () => ({ crumb: 'My Route' }),
});

9. Styling Standards (MUI v7)

9. 样式标准（MUI v7）

Inline vs Separate

内联与分离的选择

```
<100 lines
```
: inline
```
sx
```
```
>100 lines
```
:
```
{Component}.styles.ts
```

代码行数<100：使用内联
```
sx
```
代码行数>100：使用
```
{Component}.styles.ts
```
文件

Grid Syntax (v7 Only)

网格语法（仅支持v7）

tsx

<Grid size={{ xs: 12, md: 6 }} /> // ✅
<Grid xs={12} md={6} />          // ❌

Theme access must always be type-safe.

tsx

<Grid size={{ xs: 12, md: 6 }} /> // ✅
<Grid xs={12} md={6} />          // ❌

主题访问必须始终是类型安全的。

10. Loading & Error Handling

10. 加载与错误处理

Absolute Rule

绝对规则

❌ Never return early loaders ✅ Always rely on Suspense boundaries

❌ 禁止提前返回加载器 ✅ 始终依赖Suspense边界

User Feedback

用户反馈

```
useMuiSnackbar
```
only
No third-party toast libraries

仅使用
```
useMuiSnackbar
```
禁止使用第三方提示库

11. Performance Defaults

11. 性能默认配置

```
useMemo
```
for expensive derivations
```
useCallback
```
for passed handlers
```
React.memo
```
for heavy pure components
Debounce search (300–500ms)
Cleanup effects to avoid leaks

Performance regressions are bugs.

对昂贵的派生计算使用
```
useMemo
```
对传递的处理器使用
```
useCallback
```
对重型纯组件使用
```
React.memo
```
搜索功能添加防抖（300–500ms）
清理副作用以避免内存泄漏

性能退化属于Bug。

12. TypeScript Standards

12. TypeScript标准

Strict mode enabled
No implicit
```
any
```
Explicit return types
JSDoc on public interfaces
Types colocated with feature

启用严格模式
禁止隐式
```
any
```
类型
显式声明返回类型
公共接口添加JSDoc注释
类型与功能代码放在一起

13. Canonical File Structure

13. 标准文件结构

src/
  features/
    my-feature/
      api/
      components/
      hooks/
      helpers/
      types/
      index.ts

  components/
    SuspenseLoader/
    CustomAppBar/

  routes/
    my-route/
      index.tsx

src/
  features/
    my-feature/
      api/
      components/
      hooks/
      helpers/
      types/
      index.ts

  components/
    SuspenseLoader/
    CustomAppBar/

  routes/
    my-route/
      index.tsx

14. Canonical Component Template

14. 标准组件模板

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';

interface MyComponentProps {
  id: number;
  onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
  const [state, setState] = useState('');

  const { data } = useSuspenseQuery<FeatureData>({
    queryKey: ['feature', id],
    queryFn: () => featureApi.getFeature(id),
  });

  const handleAction = useCallback(() => {
    setState('updated');
    onAction?.();
  }, [onAction]);

  return (
    <Box sx={{ p: 2 }}>
      <Paper sx={{ p: 3 }}>
        {/* Content */}
      </Paper>
    </Box>
  );
};

export default MyComponent;

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';

interface MyComponentProps {
  id: number;
  onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
  const [state, setState] = useState('');

  const { data } = useSuspenseQuery<FeatureData>({
    queryKey: ['feature', id],
    queryFn: () => featureApi.getFeature(id),
  });

  const handleAction = useCallback(() => {
    setState('updated');
    onAction?.();
  }, [onAction]);

  return (
    <Box sx={{ p: 2 }}>
      <Paper sx={{ p: 3 }}>
        {/* Content */}
      </Paper>
    </Box>
  );
};

export default MyComponent;

15. Anti-Patterns (Immediate Rejection)

15. 反模式（立即拒绝）

❌ Early loading returns ❌ Feature logic in

components/

❌ Shared state via prop drilling instead of hooks ❌ Inline API calls ❌ Untyped responses ❌ Multiple responsibilities in one component

❌ 提前返回加载状态 ❌ 在

components/

目录中编写功能逻辑 ❌ 通过属性透传实现共享状态而非使用钩子 ❌ 内联API调用 ❌ 未类型化的响应 ❌ 单一组件承担多个职责

16. Integration With Other Skills

16. 与其他技能的集成

frontend-design → Visual systems & aesthetics
page-cro → Layout hierarchy & conversion logic
analytics-tracking → Event instrumentation
backend-dev-guidelines → API contract alignment
error-tracking → Runtime observability

frontend-design → 视觉系统与美学设计
page-cro → 布局层级与转化逻辑
analytics-tracking → 事件埋点
backend-dev-guidelines → API契约对齐
error-tracking → 运行时可观测性

17. Operator Validation Checklist

17. 开发者验证清单

18. Skill Status

18. 技能状态

Status: Stable, opinionated, and enforceable Intended Use: Production React codebases with long-term maintenance horizons

状态： 稳定、带主观倾向且可强制执行 预期用途： 用于需要长期维护的生产级React代码库