# EasyFlow 基础组件规范 v1

## 1. 文档目标

本规范用于统一 EasyFlow 常见组件与页面组合层的视觉气质、尺寸节奏、状态表达和布局原则。

适用范围：

- `easyflow-ui-admin`
- `easyflow-ui-usercenter`
- `easyflow-ui-websdk`

## 2. 组件总原则

EasyFlow 的组件应遵守以下统一气质：

- 柔和但理性
- 轻盈但稳定
- 精致但克制
- 现代但不花哨
- 鲜明但不失控

统一要求：

- 同类组件尺寸档位一致
- 同类组件状态规则一致
- 同类组件交互反馈一致
- 同类组件在不同端只允许密度差异，不允许语言割裂
- 不做传统表单后台式的强框架、重线条、死板排布

补充原则：

- Apple HIG 强调层级、材质、清晰与内容优先，EasyFlow 可大胆借鉴其导航骨架和控制点表达。
- Material Design 3 强调 `color roles`、`tonal surfaces`、`adaptive layouts`，EasyFlow 可大胆借鉴其色彩和表面层组织方式。
- 最终目标不是“像 Apple”或“像 Google”，而是让 EasyFlow 像一个现代工作台，而不是传统管理系统模板。

## 3. 按钮 Button

### 3.1 角色层级

- `Primary`：主操作，如新建、保存、发布、提交、确认
- `Secondary`：辅助操作，如取消、返回、次级入口
- `Ghost`：低干扰操作，如工具栏辅助动作
- `Text`：最弱层级操作，如查看详情、轻跳转
- `Danger`：删除、停用、清空等高风险动作

### 3.2 设计要求

- 主按钮明确，但不刺眼、不厚重、不夸张。
- 同一区域内按钮高度、圆角、左右内边距和图标尺寸统一。
- 图标按钮必须有足够点击热区，不可只按图标本体大小计算。
- 导航骨架中的工具按钮可以更有材质感和触感，但不应厚重、拟物或果冻化。

### 3.3 状态要求

- `hover`：轻微提亮或轻微背景变化
- `active`：轻微下压感或更深一档颜色
- `focus`：清晰焦点环
- `disabled`：降低对比度并禁用交互
- `loading`：保留按钮宽度，不发生跳变

### 3.4 禁止事项

- 一个区域同时出现多个同权重主按钮
- 用危险红色做普通主操作
- 用超大圆角和重阴影制造主操作感

## 4. 输入类组件 Input / Select / DatePicker / Search

### 4.1 统一要求

- 高度和按钮保持统一档位
- 占位文案、前后缀图标、清空按钮间距一致
- 默认边框克制，focus 时明确但不过亮

### 4.2 搜索框

- 搜索是效率辅助，不应默认比主按钮更抢眼。
- 搜索图标优先弱化，placeholder 保持清楚但不过深。
- 高级筛选展开后，信息层级仍需清晰，不形成工具栏拥堵。
- 在现代工作台场景中，搜索入口可使用轻玻璃、轻染色和更圆润的容器，但应作为“柔和工具”而不是“表单输入框”。

### 4.3 校验与提示

- 错误提示应紧邻字段出现
- 描述文案优先解释“为什么错”和“怎么改”
- 成功态与错误态使用统一结构，不因页面定制

## 5. 标签 Tag / Badge / Status

### 5.1 使用原则

- 标签用于分类、状态、轻量属性展示，不承担主要信息块角色。
- 状态标签优先语义明确，而不是丰富多彩。

### 5.2 视觉要求

- 默认低饱和背景 + 清晰文字
- 相同状态在不同页面使用相同颜色和风格
- 控制一页中高彩状态标签的数量
- 状态表达仍以语义优先，但当前态、品牌态和重点态可以更鲜明，不必做得过灰。

## 6. 卡片 Card / Panel

### 6.1 使用原则

- 卡片和面板用于承载内容分组，不应形成“层层包裹”的视觉噪音。
- 一个页面尽量维持一种主容器语言。

### 6.2 结构建议

- 头部：标题 + 摘要 / 操作
- 内容：主体信息
- 底部：补充信息或收尾动作

### 6.3 视觉要求

- 主要通过内边距、标题层级、弱分隔建立结构
- 弱边框或极轻阴影即可，不做厚重悬浮卡片
- 正文主面板应保持清晰稳定，导航骨架和轻浮层才是更适合使用轻玻璃和柔和悬浮感的位置。

## 7. 弹窗 Modal / 抽屉 Drawer / 浮层 Popover

### 7.1 总原则

- 浮层是为了帮助完成任务，不是为了制造空间戏剧性。
- 同类浮层的头部、说明区、底部操作区和关闭行为保持一致。

### 7.2 弹窗

- 适合短流程确认、中小表单、明确单任务场景
- 标题清楚，说明短而直接
- 底部按钮顺序稳定，避免不同页面顺序漂移

### 7.3 抽屉

- 适合中等复杂度编辑、详情查看、分步信息处理
- 内容区滚动、头部固定、底部操作区布局应保持稳定

### 7.4 Popover / Dropdown

- 只承载轻量选择、操作列表和局部补充信息
- 避免承载过长表单或复杂业务流程

## 8. 表格 Table

### 8.1 总体原则

- 表格优先服务检索、比较和快速操作
- 密度应克制统一，不要有的列很松，有的区域很挤

### 8.2 设计要求

- 表头、行高、单元格内边距、状态标签、行内操作维持统一节奏
- 行 hover 应轻，不造成过强闪烁
- 行内操作不应在未 hover 时完全不可发现

### 8.3 长列表策略

- 默认考虑分页、筛选、排序
- 数据量大时优先评估虚拟滚动或懒加载
- 表格工具栏与筛选区视作统一效率区域，不割裂设计

## 9. 工具栏 Toolbar / 筛选区 Filter Bar

### 9.1 总原则

- 工具栏服务任务效率，不应变成页面视觉中心。
- 搜索、筛选、批量操作、导入导出、主操作要形成明确优先级。

### 9.2 推荐布局

- 左侧：页面标题补充信息或筛选条件
- 右侧：主操作、次级操作
- 搜索与筛选默认退后于主操作

### 9.3 设计要求

- 避免同时叠加过多输入框、下拉、标签和按钮
- 高级筛选建议折叠或分层展示

### 9.4 现代工作台工具栏

- 工具栏不应看起来像一排传统表单控件堆叠。
- 可用更开放的留白、更柔和的按钮组、更轻的搜索容器来提升现代感。
- 应优先减少“每个操作一个线框框”的传统后台视觉。
- 在 toB 页面中，工具栏要更像操作系统级控制层，而不是审批系统式字段条。

## 10. Tabs / Breadcrumb / 导航类组件

### 10.1 Tabs

- 用于同级内容切换，不用于承载复杂操作入口
- 当前态应清晰，但不依赖厚重背景或夸张动画
- 标签过多时优先滚动或收纳，不压缩到难读

### 10.2 Breadcrumb

- 只表达路径，不承载大量操作
- 当前页层级清晰，前层级适度弱化

### 10.3 导航

- 导航风格轻量，重点是帮助定位，不抢占内容区注意力
- 选中态与 hover 态要统一，避免不同模块风格分裂

### 10.4 现代导航骨架

- 顶栏、侧栏、tab、breadcrumb、搜索入口、工具按钮应被视为统一导航骨架系统。
- 默认允许轻度液态玻璃、柔和模糊、弱染色和轻悬浮。
- 当前态可以更鲜明、更像“现代工作台中的激活项”，而不是传统树菜单里一条蓝字。
- 导航骨架的任务是“提升流动感和定位感”，不是把页面切成一块块硬区域。

## 11. 表单 Form

### 11.1 结构原则

- 标签、字段、说明、错误、帮助信息保持稳定顺序
- 长表单按逻辑分组，避免一屏超长无层次

### 11.2 交互要求

- 提交时必须有 loading、防重复提交和错误回填
- 必填项策略统一，不做页面级个性化表达
- 表单保存失败必须说明原因和可恢复路径

## 12. 空状态 / 错误状态 / 无权限状态

### 12.1 空状态

必须同时包含：

- 当前为空的原因
- 一句简洁说明
- 明确的下一步动作

### 12.2 错误状态

必须同时包含：

- 错误说明
- 重试或返回路径
- 必要时的诊断信息入口

### 12.3 无权限状态

- 明确告诉用户为什么不可访问
- 指向申请权限、联系管理员或返回路径

## 13. AI 相关组件

### 13.1 对话与消息区

- AI 输出区域应强调可读性与节奏，不做过度聊天气泡装饰
- 系统消息、用户消息、工具状态、执行结果要有清晰区分

### 13.2 工作流 / Agent 状态块

- 优先表达当前步骤、执行状态、结果摘要、错误恢复
- 用结构和状态说明表达过程，不靠大面积特效制造“智能感”

### 13.3 知识 / 检索 / 引用信息

- 应有稳定的辅助信息样式
- 引用、命中来源、分块信息不应与主回答混成一层

## 14. 页面组合层建议

### 14.1 列表页

推荐结构：

1. 页面标题
2. 说明或摘要
3. 工具栏
4. 表格 / 卡片列表
5. 分页 / 列表底部说明

要求：

- 列表页应尽量摆脱传统“标题下方一整排表单 + 粗边框表格”的后台感。
- 可以通过更轻的工具栏、更开阔的内容面、更清晰的主操作强调来提升活力。

### 14.2 详情页

推荐结构：

1. 标题与主操作
2. 摘要信息
3. 主内容区
4. 次级面板区

### 14.3 配置页

- 优先按模块分组，而不是长表单堆叠
- 危险配置、基础配置、实验性配置层级明确分开

## 15. 三端差异建议

### 15.1 Admin

- 更紧凑
- 更强调检索、管理、批量操作和信息秩序
- 但视觉上应更像“现代工作台”，而不是“传统表单管理系统”
- 导航骨架允许轻度液态玻璃、更鲜明的品牌当前态和更通透的控制层表达

### 15.2 User Center

- 更轻松
- 更强调个人任务、引导和可读性

### 15.3 Web SDK

- 更轻、更简、更对话化
- 但按钮、输入、面板、标签与状态反馈必须保持同源

## 16. 交付检查重点

做组件或页面时，至少确认：

- 是否符合 `冷静智能` 主题
- 是否复用了统一 Token 与公共组件
- 是否保持组件族一致
- 是否补齐了状态与异步反馈
- 是否在不同尺寸下仍然清晰、顺手、不拥挤