# Frontend Engineering Standards

## 默认技术基线

- 第一优先基线为 `TypeScript + React + Next.js + Tailwind`。
- 若项目不是该栈，优先迁移“组件边界、状态分层、语义化、可访问性、性能”这些原则，不强行照搬具体 API。
- 前端需求默认要求复用共享能力 `frontend-engineering` 与 `frontend-ui-ux-system`。
- 企业内部应用若受集团架构白皮书约束，还需要显式确认统一框架、基础组件库、数据流方案和兼容性基线。

## 组件与目录约束

- 一个组件只承担一个主职责；容器编排、展示渲染、数据适配不要混成超大文件。
- 页面级文件负责路由、数据入口和组合；复杂交互逻辑下沉到 hooks 或 service 层。
- 组件命名和目录结构要让人能从路径直接看懂“页面、区块、基础组件、数据适配”的层次。
- 优先使用组合而不是深层继承式封装。

## React / Next 实现约束

- 能在服务端获取的数据优先在服务端获取；只有确实需要浏览器能力或即时交互时才进入 client 组件。
- 本地 state 只保留 UI 状态；服务端数据、表单状态、临时派生状态不要无序混放。
- 明确 loading、empty、error、success 四类状态，不允许只处理成功态。
- 路由、布局、权限和导航状态要可追溯，不把关键页面行为藏在副作用里。

## 企业内控补充

- 内部应用默认优先使用集团认可的前端框架、基础组件和公共能力，不单独发明重复的基础设施层。
- 浏览器兼容性、静态资源、监控埋点和统一登录等企业能力，需要在实现计划里说明是否复用集团方案。
- 如果需要引入新的前端基础库、状态管理方案或非集团标准组件，必须在 ADR 或实现计划中记录原因、影响面和回退方案。

## 语义化与可访问性

- 结构优先使用语义化 HTML，表单控件必须有显式标签。
- 交互元素必须支持键盘访问、焦点可见和屏幕阅读器可理解的名称。
- 图标按钮、图片、图表、状态提示都要有非颜色依赖的说明方式。
- 任何“为了好看去掉 focus ring”的做法都视为回归。

## 样式与设计 Token

- 组件中不要写散落的原始色值、字号、圆角、阴影、层级和间距常量。
- 所有视觉值优先走 token 或约定变量；新增样式前先检查是否已有同类 token。
- 响应式优先移动端基线，再向更大断点增强，不靠固定像素宽容器兜底。
- 不允许用大面积覆盖式 `!important`、魔法数字 `z-index` 或硬编码布局修补设计缺口。

## 性能与质量

- 首屏内容、关键交互和滚动列表要显式考虑包体、渲染次数和资源加载顺序。
- 图片和媒体必须考虑尺寸预留、压缩格式和懒加载策略，避免布局抖动。
- 列表、图表、大表单要有性能策略，不默认接受“以后再优化”。
- 每次前端交付都要留下自测证据，至少覆盖主路径、边界态、异常态和响应式结果。

## 代码评审基线

- 评审不只看“能不能跑”，还要看边界、语义、复用、可维护性和体验退化。
- 若改动引入新的设计 token、组件模式或交互范式，必须在交付中说明原因和适用范围。
- 进入 QA 前应补齐 [ui-review-checklist.md](../templates/ui-review-checklist.md)。