9.7 KiB
9.7 KiB
EasyFlow 基础组件规范 v1
1. 文档目标
本规范用于统一 EasyFlow 常见组件与页面组合层的视觉气质、尺寸节奏、状态表达和布局原则。
适用范围：
easyflow-ui-admineasyflow-ui-usercentereasyflow-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 列表页
推荐结构：
- 页面标题
- 说明或摘要
- 工具栏
- 表格 / 卡片列表
- 分页 / 列表底部说明
要求：
- 列表页应尽量摆脱传统“标题下方一整排表单 + 粗边框表格”的后台感。
- 可以通过更轻的工具栏、更开阔的内容面、更清晰的主操作强调来提升活力。
14.2 详情页
推荐结构：
- 标题与主操作
- 摘要信息
- 主内容区
- 次级面板区
14.3 配置页
- 优先按模块分组，而不是长表单堆叠
- 危险配置、基础配置、实验性配置层级明确分开
15. 三端差异建议
15.1 Admin
- 更紧凑
- 更强调检索、管理、批量操作和信息秩序
- 但视觉上应更像“现代工作台”，而不是“传统表单管理系统”
- 导航骨架允许轻度液态玻璃、更鲜明的品牌当前态和更通透的控制层表达
15.2 User Center
- 更轻松
- 更强调个人任务、引导和可读性
15.3 Web SDK
- 更轻、更简、更对话化
- 但按钮、输入、面板、标签与状态反馈必须保持同源
16. 交付检查重点
做组件或页面时，至少确认：
- 是否符合
冷静智能主题 - 是否复用了统一 Token 与公共组件
- 是否保持组件族一致
- 是否补齐了状态与异步反馈
- 是否在不同尺寸下仍然清晰、顺手、不拥挤