---
name: frontend-ui-conventions
description: 前端 UI 通用规范。用于本仓库 React 前端开发时，统一技术栈、暗色主题、CSS Modules、对话框与 API 层约束。
---

# 前端通用规范

## 技术栈约束

- React + Vite
- 路由：React Router
- 状态：Zustand（如现有模块已采用）
- 样式：CSS Modules
- 网络：原生 `fetch`（统一走 `utils/api.js`）

## 主题与视觉

- 保持暗色主题一致，不引入突兀浅色块
- 颜色、边框、文字层级沿用现有页面设计
- 新页面优先复用已有组件和样式变量

## 组件复用规则

- 改页面前先检索现有自定义组件，优先复用，不重复造轮子
- 公共可复用组件统一放 `src/components/common/`，页面私有组件再放业务目录
- 若必须新增组件，先评估是否可扩展已有组件（例如通过 `props`/插槽）而不是复制一份新实现
- `frontend/config_app` 与 `frontend/cloud_app` 各自维护本工程公共组件目录，但复用策略保持一致

## 交互规则

- 对话框统一走 `frontend-dialog` 规范
- 只读展示、下拉控件统一走 `frontend-conventions` 规范
- 需要确认的危险操作必须二次确认

## API 约束

- 统一封装在 `utils/api.js`
- 请求/响应字段统一 `snake_case`
- 错误提示统一入口，不在页面散写不同风格处理

## 文件组织

- 页面放 `pages/`
- 组件放 `components/`
- 公共组件放 `components/common/`
- Hook 与状态放 `hooks/`
- 工具与 API 放 `utils/`