EasyFlow/docs/design/component-guidelines.md

EasyFlow 基础组件规范 v1

1. 文档目标

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

适用范围：

• easyflow-ui-admin
• easyflow-ui-usercenter
• easyflow-ui-websdk

2. 组件总原则

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 设计要求

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

10. Tabs / Breadcrumb / 导航类组件

10.1 Tabs

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

10.2 Breadcrumb

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

10.3 导航

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

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 与公共组件
• 是否保持组件族一致
• 是否补齐了状态与异步反馈
• 是否在不同尺寸下仍然清晰、顺手、不拥挤