# 设计系统（权威）

> **目标**: 以 Lark 风格为统一视觉语言，作为所有前端视觉规范的单一事实来源  
> **最后更新**: 2026-01-15

---

## ✅ 入口与执行

- 前端实现与设计（含视觉对齐）：`frontend-main`

---

## 📋 文档索引

| 文档 | 说明 |
|------|------|
| [设计原则](./design-principles.md) | 设计理念与体验原则 |
| [Lark 风格指南](./lark-style-guide.md) | 视觉规范与组件样式 |
| [组件库规范](./component-library.md) | 组件设计与使用 |
| [UI 规范编写标准](./ui-specification-standard.md) | UI 规范写作流程 |

---

## ✅ 全局反馈规范（统一标准）

> 目的：确保“成功/失败/警告/处理中/空态/确认”的视觉与交互一致，减少误读与重复实现。  
> 范围：Toast、确认弹窗、顶部横幅、页面级错误/空态、表单校验提示。  
> 权威实现入口：`frontend-main`。

### 1) 基本原则

- 禁止使用 `window.alert` / `window.confirm` 作为最终交互。  
- 同类型反馈必须复用统一样式与组件，不得页面级自创。  
- 所有可见文案必须 i18n；不得硬编码提示文本。  
- 反馈信息分级明确：成功/错误/警告/提示/处理中/需处理，颜色与图标不可混用。

### 2) Toast 规范（瞬时反馈）

- 适用：轻量反馈、非阻断操作结果。  
- 类型：`success` / `error` / `warning` / `info` / `loading` / `neutral` / `action`。  
- 视觉：白底 + 左侧色条，图标与色条一致；`loading` 必须有旋转图标。  
- 统一入口：使用 `@/lib/toast`，禁止直接引用第三方库实例。

### 3) 确认弹窗规范（阻断操作）

- 适用：删除、撤回、批量更新、不可逆操作。  
- 类型：`danger` / `primary` 两种样式。  
- 视觉：标题含状态点/图标，主按钮颜色与类型一致；取消按钮统一样式。  
- 禁止 `confirm()`；统一使用组件化确认弹窗（后续统一到 ConfirmProvider）。

### 4) 顶部横幅规范（系统级提示）

- 适用：系统维护、重要公告、全局风险提示。  
- 类型：`info` / `warning` / `error`（按风险等级）。  
- 视觉：浅色底 + 边框 + 左侧图标；文案简明，支持跳转。

### 5) 页面级错误 / 空态

- 错误页：用于页面加载失败或权限异常；需提供“重试/返回”入口。  
- 空态：用于无数据或筛选为空；需提供“引导操作”或“清空筛选”。

### 6) 表单校验提示

- 类型：`error` / `warning` / `success`。  
- 规则：错误优先；警告不阻断提交但需提示；成功用于关键字段通过校验。  
- 视觉：输入框边框与提示文字颜色一致，配图标。

### 7) 禁止与替代清单

- 禁止：`window.alert` / `window.confirm` / 页面手写遮罩弹窗 / 自定义色值。  
- 替代：统一 Toast、统一确认弹窗、统一 Banner、统一 PageState、统一 FieldMessage。

### 8) 交付与测试要求

- 每次替换必须覆盖：到达断言 + 成功/稳定断言（见测试规范）。  
- 每完成 5 个用例更新一次测试报告。  
- 统一预览页作为视觉对齐基准。

### 9) 组件层统一方案（方案B）

> 目的：把“空态/错误/校验/权限不足”等反馈从页面收敛到统一组件与规范，降低页面重复实现。  
> 适用：进入全局统一阶段时执行，需配套回归测试。

**统一组件清单**
- `PageState`：页面级空态/错误/无权限  
- `FieldMessage`：表单校验与提示  
- `FeedbackBanner`：系统级横幅提示  
- `ConfirmProvider`：统一确认弹窗  
- `toast`：统一瞬时反馈入口

**统一参数规范（示例）**
- `variant`: `empty` / `error` / `warning` / `info` / `success` / `loading`
- `layout`: `compact` / `center` / `card`
- `title` / `description` / `actionLabel` / `onAction`

**迁移策略**
1. 先替换全局路由错误/无权限页  
2. 再替换列表空态/错误态（数据密集页）  
3. 再替换表单校验提示（核心流程）  
4. 最后替换页面级 Banner/Confirm

**回归要求**
- 覆盖核心模块（组织/审批/表单/系统日志/审计/知识库）  
- 必须使用 MCP E2E 验证并产出报告  
- 关键页面需截图留档

---

**维护者**: FFOA 设计团队 & 前端团队  
**最后更新**: 2026-01-15