From 76c2954a706d848054661604f9bc209a8ebe8ffd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=99=88=E5=AD=90=E9=BB=98?= <925456043@qq.com>
Date: Fri, 6 Mar 2026 14:39:14 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E4=BA=A7=E5=93=81?=
 =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E8=A7=84=E8=8C=83=E7=9F=A5=E8=AF=86=E5=BA=93?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增产品主题、色彩体系与三端一致性规范\n- 补充 Design Tokens 草案与基础组件规范\n- 补充交互与动效规范及设计文档索引
---
 docs/design/README.md                        |  84 +++++
 docs/design/component-guidelines.md          | 292 ++++++++++++++++
 docs/design/design-tokens-draft.md           | 341 +++++++++++++++++++
 docs/design/easyflow-product-design-spec.md  | 305 +++++++++++++++++
 docs/design/interaction-motion-guidelines.md | 261 ++++++++++++++
 5 files changed, 1283 insertions(+)
 create mode 100644 docs/design/README.md
 create mode 100644 docs/design/component-guidelines.md
 create mode 100644 docs/design/design-tokens-draft.md
 create mode 100644 docs/design/easyflow-product-design-spec.md
 create mode 100644 docs/design/interaction-motion-guidelines.md

diff --git a/docs/design/README.md b/docs/design/README.md
new file mode 100644
index 0000000..8880358
--- /dev/null
+++ b/docs/design/README.md
@@ -0,0 +1,84 @@
+# EasyFlow 设计文档索引
+
+本目录用于沉淀 EasyFlow 的长期设计资产，作为产品、设计、前端共同维护的正式知识库。
+
+## 文档清单
+
+### 1. 产品主题与总规范
+
+- [easyflow-product-design-spec.md](./easyflow-product-design-spec.md)
+
+适用场景：
+
+- 统一产品主题和体验方向
+- 定义品牌气质、色彩哲学、UI 风格、交互哲学与三端一致性
+
+### 2. Design Tokens 草案
+
+- [design-tokens-draft.md](./design-tokens-draft.md)
+
+适用场景：
+
+- 设计 Token 规划
+- 前端变量命名、主题映射与公共层沉淀
+- 浅色 / 深色主题统一策略
+
+### 3. 基础组件规范
+
+- [component-guidelines.md](./component-guidelines.md)
+
+适用场景：
+
+- 按钮、输入框、卡片、表格、抽屉、弹窗、标签等组件统一
+- 页面工具栏、筛选区、空状态等常见组合层设计
+
+### 4. 交互与动效规范
+
+- [interaction-motion-guidelines.md](./interaction-motion-guidelines.md)
+
+适用场景：
+
+- 表单交互、异步反馈、危险操作、状态页
+- 页面切换、面板出现、微交互、动效时长与缓动策略
+
+## 使用建议
+
+### 产品 / 设计讨论
+
+优先阅读：
+
+1. `easyflow-product-design-spec.md`
+2. `component-guidelines.md`
+3. `interaction-motion-guidelines.md`
+
+### 前端实现
+
+优先阅读：
+
+1. `easyflow-product-design-spec.md`
+2. `design-tokens-draft.md`
+3. `component-guidelines.md`
+4. `interaction-motion-guidelines.md`
+
+### 主题或视觉重构
+
+优先阅读：
+
+1. `easyflow-product-design-spec.md`
+2. `design-tokens-draft.md`
+3. `component-guidelines.md`
+
+## 与 easyflow-ui skill 的关系
+
+本目录是 EasyFlow 的正式设计知识库。
+
+`.codex/skills/easyflow-ui/` 是任务执行入口，负责：
+
+- 告诉后续 UI / 前端任务先读哪些文档
+- 约束改动应该落在哪一层
+- 提供执行流程、自检清单与交付要求
+
+两者关系如下：
+
+- `docs/design/`：完整规范与长期资产
+- `.codex/skills/easyflow-ui/`：高频规则、任务流程、引用入口
diff --git a/docs/design/component-guidelines.md b/docs/design/component-guidelines.md
new file mode 100644
index 0000000..3597fcf
--- /dev/null
+++ b/docs/design/component-guidelines.md
@@ -0,0 +1,292 @@
+# 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 与公共组件
+- 是否保持组件族一致
+- 是否补齐了状态与异步反馈
+- 是否在不同尺寸下仍然清晰、顺手、不拥挤
diff --git a/docs/design/design-tokens-draft.md b/docs/design/design-tokens-draft.md
new file mode 100644
index 0000000..8e2be44
--- /dev/null
+++ b/docs/design/design-tokens-draft.md
@@ -0,0 +1,341 @@
+# EasyFlow Design Tokens 草案 v1
+
+## 1. 文档目标
+
+本草案用于定义 EasyFlow 后续主题系统、设计变量与公共层实现的统一方向，指导 `@core/base/design`、`@core/ui-kit` 与 `effects/*` 中的 Token 沉淀方式。
+
+本草案不要求一次性重构所有现有 Token，而是用于：
+
+- 为后续主题统一提供命名和分层标准
+- 为设计与前端提供同一套语义映射
+- 为浅色 / 深色、三端统一和组件族一致性提供基础
+
+## 2. Token 设计原则
+
+### 2.1 先语义，后数值
+
+优先暴露“用途”而不是“值”。
+
+推荐：
+
+- `--color-primary`
+- `--color-text-strong`
+- `--radius-panel`
+
+不推荐直接在页面层使用：
+
+- `#1677FF`
+- `16px`
+- `0 20px 40px ...`
+
+### 2.2 全局 Token 与组件 Token 分层
+
+建议分为三层：
+
+1. `Foundation Tokens`
+   - 原始色阶、字号、间距、圆角、阴影、时长、z-index
+2. `Semantic Tokens`
+   - 主色、文本、背景、边框、状态、焦点、浮层等产品语义
+3. `Component Alias Tokens`
+   - 按钮、输入框、卡片、表格、抽屉、弹窗等组件专用映射
+
+### 2.3 页面不直接发明视觉体系
+
+页面层可消费组件 Token 或语义 Token，不直接定义新的品牌色、中性色、阴影和圆角体系。
+
+## 3. 推荐目录与命名方向
+
+建议未来逐步按以下能力组织：
+
+```text
+design-tokens/
+  color/
+    foundation.css
+    semantic-light.css
+    semantic-dark.css
+  radius.css
+  shadow.css
+  spacing.css
+  typography.css
+  motion.css
+  z-index.css
+  component/
+    button.css
+    input.css
+    panel.css
+    modal.css
+    table.css
+```
+
+若短期内不拆文件，也建议先遵守同样的命名语义。
+
+## 4. 色彩 Token 草案
+
+### 4.1 品牌色
+
+| Token | 值 | 说明 |
+| --- | --- | --- |
+| `--color-primary` | `#1677FF` | 主按钮、选中态、焦点、关键链接 |
+| `--color-primary-hover` | `#3D8BFF` | 主按钮悬停 |
+| `--color-primary-active` | `#0F5FD6` | 主按钮按下 |
+| `--color-primary-soft` | `#EAF3FF` | 品牌浅底 |
+| `--color-primary-foreground` | `#FFFFFF` | 品牌色上的文字 |
+
+### 4.2 中性色
+
+| Token | 值 | 说明 |
+| --- | --- | --- |
+| `--color-bg-app` | `#F6F8FB` | 页面背景 |
+| `--color-bg-canvas` | `#F2F5F9` | 内容画布或区域底色 |
+| `--color-bg-panel` | `#FFFFFF` | 卡片、面板、弹窗主背景 |
+| `--color-bg-subtle` | `#F8FAFD` | 次层背景 |
+| `--color-bg-hover` | `#EEF3F9` | hover 背景 |
+| `--color-border` | `#DCE3EC` | 常规边框 |
+| `--color-border-strong` | `#CBD6E2` | 稍强边框 |
+| `--color-divider` | `#E6EDF5` | 分割线 |
+| `--color-text-strong` | `#1C2430` | 主文本 |
+| `--color-text` | `#334154` | 正文 |
+| `--color-text-secondary` | `#5B6574` | 次文本 |
+| `--color-text-muted` | `#8691A2` | 辅助文本 |
+| `--color-text-disabled` | `#A7B1BF` | 禁用文本 |
+
+### 4.3 语义色
+
+| Token | 值 | 说明 |
+| --- | --- | --- |
+| `--color-success` | `#2FA36B` | 成功 |
+| `--color-success-soft` | `#EAF8F1` | 成功浅底 |
+| `--color-warning` | `#D89A27` | 警告 |
+| `--color-warning-soft` | `#FFF6E5` | 警告浅底 |
+| `--color-danger` | `#D84F5F` | 错误 / 危险 |
+| `--color-danger-soft` | `#FDECEF` | 错误浅底 |
+| `--color-info` | `#4B83D8` | 信息 |
+| `--color-info-soft` | `#EEF4FF` | 信息浅底 |
+
+### 4.4 深色模式建议
+
+深色模式不是简单反相，建议维持以下结构：
+
+- `--color-bg-app-dark`: 石墨深灰
+- `--color-bg-panel-dark`: 比背景略亮一层
+- `--color-border-dark`: 低对比灰蓝
+- `--color-text-strong-dark`: 高亮浅灰
+- `--color-primary-dark`: 延续主蓝，但不大幅提高饱和度
+
+## 5. 圆角 Token 草案
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `--radius-xs` | `8px` | 标签、小型徽标 |
+| `--radius-sm` | `10px` | 按钮、输入框 |
+| `--radius-md` | `12px` | 下拉面板、工具条 |
+| `--radius-lg` | `16px` | 卡片、主面板 |
+| `--radius-xl` | `20px` | 抽屉、弹窗 |
+| `--radius-pill` | `999px` | 胶囊标签、分段控件 |
+
+说明：
+
+- 圆角应该柔和但理性，不做玩具化超大圆角。
+- 页面层禁止新增“只适合本页”的圆角数值。
+
+## 6. 阴影 Token 草案
+
+| Token | 建议值 | 用途 |
+| --- | --- | --- |
+| `--shadow-sm` | `0 10px 24px -24px rgba(18, 36, 62, 0.18)` | 基础卡片 |
+| `--shadow-md` | `0 18px 36px -28px rgba(18, 36, 62, 0.22)` | 菜单、浮层 |
+| `--shadow-lg` | `0 28px 56px -32px rgba(18, 36, 62, 0.26)` | 弹窗、抽屉 |
+
+说明：
+
+- 阴影用于表达层级，不用于制造厚重“高级感”。
+- 同一页面内避免多套阴影并存。
+
+## 7. 间距 Token 草案
+
+使用 8pt 体系，建议保留以下档位：
+
+| Token | 值 |
+| --- | --- |
+| `--space-1` | `4px` |
+| `--space-2` | `8px` |
+| `--space-3` | `12px` |
+| `--space-4` | `16px` |
+| `--space-5` | `20px` |
+| `--space-6` | `24px` |
+| `--space-8` | `32px` |
+| `--space-10` | `40px` |
+| `--space-12` | `48px` |
+
+说明：
+
+- `12px` 和 `20px` 可用于组件内部微调。
+- 页面主节奏优先使用 `8 / 16 / 24 / 32`。
+
+## 8. 字体 Token 草案
+
+### 8.1 字体族
+
+```text
+--font-family-sans:
+  "PingFang SC", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+```
+
+### 8.2 字号层级
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `--font-size-xs` | `12px` | 辅助说明、标签 |
+| `--font-size-sm` | `13px` | 次级信息 |
+| `--font-size-base` | `14px` | 正文 |
+| `--font-size-md` | `16px` | 表单标题、小区块标题 |
+| `--font-size-lg` | `18px` | 页面次标题 |
+| `--font-size-xl` | `20px` | 页面标题 |
+| `--font-size-2xl` | `24px` | 首页或核心模块标题 |
+
+### 8.3 字重建议
+
+| Token | 值 |
+| --- | --- |
+| `--font-weight-regular` | `400` |
+| `--font-weight-medium` | `500` |
+| `--font-weight-semibold` | `600` |
+
+说明：
+
+- 常规产品界面避免大量 `700` 字重。
+- 强调信息优先通过层级和留白表达，而不是一味加粗。
+
+## 9. 动效 Token 草案
+
+### 9.1 时长
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `--motion-duration-fast` | `120ms` | 微交互 |
+| `--motion-duration-base` | `160ms` | hover / focus / icon 变化 |
+| `--motion-duration-medium` | `220ms` | 面板切换 |
+| `--motion-duration-slow` | `280ms` | 弹窗 / 抽屉 |
+
+### 9.2 缓动
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `--motion-ease-standard` | `cubic-bezier(0.2, 0, 0, 1)` | 常规过渡 |
+| `--motion-ease-decelerate` | `cubic-bezier(0.16, 1, 0.3, 1)` | 进入动画 |
+| `--motion-ease-accelerate` | `cubic-bezier(0.3, 0, 1, 1)` | 离开动画 |
+
+说明：
+
+- 尽量统一到有限几档，不在组件里各自发明缓动函数。
+- 当前仓库已有若干 `transition.css` 和 `ui.css` 动效定义，后续应逐步向统一 Token 收口。
+
+## 10. z-index Token 草案
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `--z-base` | `1` | 常规内容 |
+| `--z-dropdown` | `1000` | 下拉、浮层 |
+| `--z-sticky` | `1100` | 吸顶工具条 |
+| `--z-overlay` | `1900` | 遮罩 |
+| `--z-popup` | `2000` | 弹窗、抽屉 |
+| `--z-toast` | `2100` | 全局消息 |
+
+## 11. 组件别名 Token 草案
+
+### 11.1 Button
+
+```text
+--button-height-sm: 32px
+--button-height-md: 36px
+--button-height-lg: 40px
+--button-radius: var(--radius-sm)
+--button-primary-bg: var(--color-primary)
+--button-primary-hover-bg: var(--color-primary-hover)
+--button-primary-active-bg: var(--color-primary-active)
+```
+
+### 11.2 Input
+
+```text
+--input-height-md: 40px
+--input-radius: var(--radius-sm)
+--input-bg: var(--color-bg-panel)
+--input-border: var(--color-border)
+--input-border-focus: var(--color-primary)
+--input-placeholder: var(--color-text-muted)
+```
+
+### 11.3 Panel
+
+```text
+--panel-radius: var(--radius-lg)
+--panel-bg: var(--color-bg-panel)
+--panel-border: var(--color-divider)
+--panel-shadow: var(--shadow-sm)
+```
+
+### 11.4 Modal / Drawer
+
+```text
+--overlay-bg: rgba(15, 23, 42, 0.4)
+--modal-radius: var(--radius-xl)
+--modal-bg: var(--color-bg-panel)
+--modal-shadow: var(--shadow-lg)
+```
+
+## 12. 与当前仓库的映射建议
+
+当前仓库已存在如下方向的变量：
+
+- `--primary`
+- `--background`
+- `--surface-*`
+- `--text-*`
+- `--shadow-*`
+- `--nav-*`
+- `--toolbar-*`
+
+建议演进方式：
+
+1. 先保留当前 Token 命名，避免一次性大改。
+2. 在公共层补充新的语义映射表。
+3. 新组件优先消费新语义 Token。
+4. 历史组件在重构时逐步迁移，不做无收益的全面替换。
+
+## 13. 落地策略
+
+### 13.1 应落在 `@core/base/design`
+
+- 色彩、圆角、阴影、间距、字号、动效、z-index 等基础 Token
+- 浅色 / 深色语义映射
+- 全局过渡与基础状态规则
+
+### 13.2 应落在 `@core/ui-kit`
+
+- 组件别名 Token
+- 组件尺寸、状态、变体和内部布局规则
+
+### 13.3 应落在 `effects/*`
+
+- 页面工具栏
+- 筛选区
+- 面板骨架
+- 列表页组合层
+
+### 13.4 不应落在页面层
+
+- 品牌主色
+- 新的边框体系
+- 新的圆角体系
+- 新的阴影体系
+- 新的动效时长或缓动
+
+## 14. 后续建议
+
+后续若进入真正的 Token 落地阶段，建议补充：
+
+- `Token -> CSS Variable` 对照表
+- `Token -> Figma Variable` 对照表
+- 浅色 / 深色完整 token matrix
+- 组件别名 token 实际代码映射表
diff --git a/docs/design/easyflow-product-design-spec.md b/docs/design/easyflow-product-design-spec.md
new file mode 100644
index 0000000..cf45cbb
--- /dev/null
+++ b/docs/design/easyflow-product-design-spec.md
@@ -0,0 +1,305 @@
+# EasyFlow 产品设计规范 v1
+
+## 1. 文档目的
+
+本规范用于统一 EasyFlow 的产品主题、视觉语言、交互哲学与前端实现方向，作为管理端、用户端、Web SDK 以及后续设计资产沉淀的共同依据。
+
+目标不是追求“更花哨”的界面，而是建立一套长期稳定、可复用、可演进的产品设计系统，让 EasyFlow 在不同模块、不同端上都保持一致的气质、手感与可信度。
+
+## 2. 设计主题
+
+### 2.1 主题名称
+
+`冷静智能`
+
+### 2.2 一句话定义
+
+EasyFlow 是一个克制、可信、现代、交互友好的智能工作台。
+
+### 2.3 品牌气质关键词
+
+- 清晰
+- 秩序
+- 安静
+- 智能
+- 可信
+- 精致
+- 顺手
+
+### 2.4 明确避免的方向
+
+- 赛博霓虹、强对比、高饱和炫技风格
+- 过度玻璃拟态、厚重阴影、复杂渐变堆叠
+- 为了“科技感”牺牲信息层级和可读性
+- 为了“高级感”弱化交互反馈或降低操作效率
+
+## 3. 产品体验目标
+
+EasyFlow 需要同时承载企业级管理平台与 AI 应用开发平台的双重身份，因此整体体验必须同时传达以下四类感受：
+
+- `专业可信`：让用户敢于在系统中管理流程、配置智能体和处理业务数据。
+- `结构清晰`：让复杂能力在页面中仍然容易理解、容易导航、容易操作。
+- `智能高效`：让 AI、工作流、知识库等能力体现为效率提升，而不是额外复杂度。
+- `交互温和`：让反馈及时、稳定、低打扰，减少紧张感和误操作成本。
+
+## 4. 核心设计原则
+
+### 4.1 清晰优先
+
+先让用户看懂页面层级、当前状态、下一步动作，再追求视觉表现。
+
+### 4.2 安静高效
+
+界面不喧宾夺主，主任务、主操作与主信息始终占据视觉优先级。
+
+### 4.3 统一胜过局部惊艳
+
+单页的“特别设计”如果破坏了全局一致性，不应视为正向设计资产。
+
+### 4.4 细节有温度
+
+hover、focus、loading、空状态、错误状态、成功反馈等细节必须被完整设计，而不是只补主界面。
+
+### 4.5 动效服务理解
+
+动画用于帮助用户理解状态变化、层级切换和空间关系，不用于炫技或制造噪音。
+
+### 4.6 AI 也要可信
+
+AI 能力的表达应克制、专业、可预期，重点是流程可理解、状态可感知、结果可恢复。
+
+## 5. 色彩体系
+
+### 5.1 主色方案
+
+EasyFlow v1 使用 `冷静智能蓝` 作为统一品牌色策略。
+
+### 5.2 核心色值
+
+| Token | 用途 | 建议值 |
+| --- | --- | --- |
+| Primary | 品牌主色 / 主操作 / 当前态 | `#1677FF` |
+| Primary Hover | 主操作悬停 | `#3D8BFF` |
+| Primary Active | 主操作按下 | `#0F5FD6` |
+| Brand Soft Surface | 品牌浅底 | `#EAF3FF` |
+| App Background | 页面背景 | `#F6F8FB` |
+| Panel Background | 面板/卡片背景 | `#FFFFFF` |
+| Text Strong | 强文本 | `#1C2430` |
+| Text Secondary | 次文本 | `#5B6574` |
+| Border | 常规描边 | `#DCE3EC` |
+
+### 5.3 使用规则
+
+- 品牌色仅用于主按钮、选中态、焦点态、关键链接、核心数据高亮与重要反馈。
+- 页面大面积区域以中性色为主，不使用大面积纯品牌色铺底。
+- 色彩比例建议控制为：`70% 中性背景 + 20% 结构层级色 + 10% 品牌强调色`。
+- 成功、警告、错误色属于语义系统，不参与品牌表达，不作为页面主装饰色。
+- 深色模式延续同一品牌策略，但背景使用石墨深灰体系，避免纯黑带来的生硬与失真。
+
+### 5.4 语义色原则
+
+- 成功：偏冷静绿色，强调完成与正常状态，不使用荧光绿。
+- 警告：中低饱和暖黄，用于风险提醒，不制造焦虑。
+- 错误：克制红色，用于错误、删除、失败、危险动作。
+- 信息：浅蓝或冷灰蓝，用于说明、提示、引导，不抢主操作注意力。
+
+## 6. UI 视觉语言
+
+### 6.1 总体风格
+
+EasyFlow 的界面风格定义为：
+
+- 扁平
+- 轻层级
+- 弱描边
+- 轻阴影
+- 大留白
+- 强对齐
+- 少装饰
+
+### 6.2 层级建立方式
+
+- 优先依赖留白、分组、对齐、字号、字重和弱分隔线建立层次。
+- 少用“卡片套卡片”“面板套面板”建立结构。
+- 避免粗边框、重阴影、过多色块同时出现。
+
+### 6.3 字体与信息层级
+
+- 中文优先系统中文字体链，默认以 `PingFang SC` 体验为参考。
+- 西文、数字、代码信息优先复用系统字体链，保持现代、稳定与跨端一致性。
+- 页面至少保证标题、区块标题、正文、辅助说明四级文字层级。
+- 弱信息不靠缩得过小来退让，而靠颜色、字重和间距让位。
+
+### 6.4 圆角策略
+
+EasyFlow 的圆角应柔和但理性，不追求玩具感或夸张圆润。
+
+建议档位：
+
+- 按钮 / 输入框：`10px`
+- 下拉面板 / 工具条 / 小型容器：`12px`
+- 卡片 / 页面面板：`16px`
+- 弹窗 / 抽屉 / 高阶浮层：`20px`
+- 徽标 / 标签胶囊：`999px` 或 `8px`
+
+### 6.5 阴影策略
+
+阴影只承担“层级提示”功能，不承担风格表达主角。
+
+建议仅保留三档：
+
+- 基础层：弱阴影，仅用于卡片和轻微浮起场景
+- 浮层：用于下拉、Popover、菜单、选择面板
+- 模态层：用于弹窗、抽屉、全局悬浮区
+
+### 6.6 描边策略
+
+- 描边尽量细、淡、统一，优先作为结构辅助线而不是视觉主角。
+- 相邻容器尽量通过背景层差和留白区分，而不是每层都画边框。
+- 输入类组件可使用更清晰但不刺眼的边框和焦点环。
+
+## 7. 组件气质与统一手感
+
+### 7.1 按钮
+
+- 主按钮明确，但不依赖过饱和颜色或异常尺寸制造存在感。
+- 次级按钮、幽灵按钮、文本按钮的优先级稳定，不随页面作者习惯漂移。
+- 同一区域内按钮高度、圆角、图标尺寸、左右留白必须属于同一档位体系。
+
+### 7.2 输入类组件
+
+- 输入框、选择器、日期选择器、搜索框与相邻按钮在高度和节奏上保持一致。
+- 占位文案、前后缀图标、清空按钮的灰度和间距统一。
+- 校验、禁用、只读、加载中的状态风格不能因页面不同而改变。
+
+### 7.3 卡片与面板
+
+- 页面应尽量维持一种主容器语言。
+- 卡片与面板优先使用内边距、弱分隔和标题层级建立结构。
+- 同类弹窗、抽屉、操作面板的头部、说明区和底部操作区保持稳定模板。
+
+### 7.4 表格、筛选区与工具栏
+
+- 搜索、筛选、批量操作、表格头和分页应被视为同一组效率组件。
+- 搜索与筛选默认低于主操作位，不抢“新建、保存、发布、提交”等核心动作。
+- 表格密度既不能松散拖沓，也不能压缩到难读难点。
+
+### 7.5 标签、徽标与状态
+
+- 状态展示优先语义明确、饱和度受控。
+- 避免在同一页面出现大量高彩色标签争夺注意力。
+- 成功、失败、处理中、草稿等状态造型与颜色映射保持统一。
+
+## 8. 页面骨架与信息层级
+
+### 8.1 页面推荐结构
+
+大部分业务页面优先遵循以下顺序：
+
+1. 标题区
+2. 说明区或关键摘要
+3. 工具栏 / 主要操作区
+4. 核心内容区
+5. 辅助说明或次级信息区
+
+### 8.2 主次关系
+
+- 主操作在用户预期位置稳定出现，减少跨页面学习成本。
+- 次级动作、帮助说明、附属信息应主动退后。
+- 响应式下优先保持层级和操作顺序，再压缩尺寸与布局。
+
+## 9. 交互哲学
+
+### 9.1 总体方向
+
+EasyFlow 的交互应是“顺手”的，而不是“会玩”的。
+
+### 9.2 必备交互要求
+
+- 所有交互控件必须具备 hover、active、focus、disabled 状态。
+- 所有异步流程必须具备 loading、防重复提交、成功反馈和失败恢复路径。
+- 表单校验应就近展示并可执行，不让用户自己猜测修复方式。
+- 危险操作必须有确认、反馈和可恢复思路。
+- 空状态、错误状态、无权限状态、无数据状态必须提供解释和下一步动作。
+
+### 9.3 键盘与可访问性
+
+- 默认支持 Tab 键导航。
+- 关键操作与对话框保持 Enter / Esc 行为清晰。
+- 焦点样式必须明显，不可依赖颜色轻微变化蒙混通过。
+
+## 10. 动效规范
+
+### 10.1 动效关键词
+
+- 细腻
+- 短促
+- 稳定
+- 不变形
+
+### 10.2 推荐时长
+
+- 微交互：`120ms - 160ms`
+- 面板切换：`180ms - 240ms`
+- 弹窗 / 抽屉：`220ms - 280ms`
+
+### 10.3 推荐形式
+
+- 透明度变化
+- 轻微位移
+- 轻微缩放
+
+### 10.4 明确避免
+
+- 弹跳
+- 果冻式形变
+- 长时间缓动
+- 多段复杂动画
+- 与业务无关的装饰性动画
+
+## 11. 三端统一策略
+
+### 11.1 必须统一
+
+- 色彩体系
+- 圆角体系
+- 阴影与描边规则
+- 字体层级
+- 按钮、输入框、弹窗、标签等基础组件手感
+- 动效节奏和反馈逻辑
+
+### 11.2 允许差异
+
+- 页面密度
+- 页面骨架
+- 内容布局方式
+- 业务语气与引导方式
+
+### 11.3 分端建议
+
+- Admin：更克制、更紧凑、更强调秩序与效率
+- User Center：更友好、稍轻松，但保持同一设计语言
+- Web SDK：更轻、更简、更对话化，但控件和反馈必须同源
+
+## 12. AI 能力的专属表达
+
+- AI 模块允许比传统管理模块多一点蓝青高亮感，但不能脱离全局视觉语言。
+- 智能体、工作流、知识检索、执行状态等内容，重点体现“过程清晰、状态可感知、失败可恢复”。
+- 不把 AI 能力包装成神秘黑盒，不使用夸张视觉掩盖复杂性。
+
+## 13. 前端落地要求
+
+- 颜色、圆角、阴影、间距、字号、动效时长统一沉淀到 Token 与公共层。
+- 同类视觉规则影响多个页面时，优先下沉到 `@core/base/design`、`@core/ui-kit` 或 `effects/*`。
+- 页面层只负责编排业务内容，不重复发明基础组件风格。
+- 若本次任务无法完成视觉、交互或响应式验证，交付说明中必须明确缺失项。
+
+## 14. 后续演进建议
+
+建议在本规范基础上继续沉淀以下资产：
+
+- Design Tokens 详细清单
+- 基础组件视觉与交互规范
+- 页面骨架模板库
+- 空状态 / 错误状态 / 引导状态模板
+- AI 模块专属状态与流程表达规范
diff --git a/docs/design/interaction-motion-guidelines.md b/docs/design/interaction-motion-guidelines.md
new file mode 100644
index 0000000..7f2ec16
--- /dev/null
+++ b/docs/design/interaction-motion-guidelines.md
@@ -0,0 +1,261 @@
+# EasyFlow 交互与动效规范 v1
+
+## 1. 文档目标
+
+本规范用于统一 EasyFlow 的操作反馈、异步流程、状态恢复、键盘可达性与动效系统，确保界面既现代流畅，又稳定可信。
+
+## 2. 交互哲学
+
+EasyFlow 的交互原则是：
+
+- 顺手
+- 可预期
+- 低打扰
+- 可恢复
+
+界面应始终让用户知道：
+
+- 我现在在哪
+- 当前发生了什么
+- 下一步可以做什么
+- 出错了如何恢复
+
+## 3. 交互优先级规则
+
+### 3.1 主操作稳定
+
+- 同类页面主操作位置尽量固定
+- 主操作数量尽量少，避免多个并列主按钮
+
+### 3.2 次级操作退后
+
+- 搜索、筛选、帮助、导出等默认低于主任务
+- 危险操作不与主操作并列抢权重
+
+### 3.3 反馈先于装饰
+
+- 任何视觉变化都应优先承担反馈职责
+- 不为“好看”增加没有业务意义的动画
+
+## 4. 表单交互规范
+
+### 4.1 基本要求
+
+- 字段标签清晰
+- 帮助信息紧邻字段
+- 错误提示就近展示
+- 提交后有明确状态反馈
+
+### 4.2 校验策略
+
+- 优先在字段级提示错误
+- 文案要能指导修改，而不是只提示“输入有误”
+- 对高风险或高成本字段，必要时增加确认步骤
+
+### 4.3 提交流程
+
+表单提交必须覆盖：
+
+- 提交中 loading
+- 防重复点击
+- 成功提示
+- 失败原因
+- 保留或恢复用户已填内容
+
+## 5. 列表与批量操作规范
+
+### 5.1 列表交互
+
+- 排序、筛选、分页、搜索需保持稳定顺序
+- 列表刷新不应导致明显跳闪
+- 行 hover 反馈应轻量但可感知
+
+### 5.2 批量操作
+
+- 进入批量态后，当前选中数量要清楚
+- 高风险批量操作必须确认
+- 批量完成后需反馈结果摘要
+
+## 6. 状态反馈规范
+
+### 6.1 Loading
+
+- 短操作可用按钮 loading 或局部 skeleton
+- 中长操作应提供区域级反馈
+- 不要让全页面频繁闪动式 loading 干扰操作
+
+### 6.2 Success
+
+- 成功反馈应简洁明确
+- 成功后如果有下一步建议，可轻量提示
+
+### 6.3 Error
+
+- 错误要说明原因，至少说明失败发生在哪
+- 可恢复错误必须给出重试路径
+- 不可恢复错误也应给出返回或联系支持路径
+
+### 6.4 Empty
+
+- 解释为什么为空
+- 提供推荐操作
+- 保持视觉克制，不用过重插画制造噪音
+
+## 7. 危险操作规范
+
+以下场景默认视为危险操作：
+
+- 删除
+- 清空
+- 停用
+- 覆盖
+- 批量不可逆处理
+
+要求：
+
+- 二次确认
+- 文案明确说明影响范围
+- 按钮层级清晰，不允许误触
+- 完成后提供结果反馈
+
+## 8. 键盘与可访问性
+
+### 8.1 键盘可达性
+
+- Tab 顺序合理
+- 对话框支持 Esc 关闭
+- 主操作支持 Enter 快捷确认时，要避免误触发
+
+### 8.2 焦点样式
+
+- 必须清晰可见
+- 不依赖微弱颜色变化
+- 不得被自定义样式覆盖消失
+
+### 8.3 语义结构
+
+- 表单、表格、弹窗、导航使用语义化结构
+- 图标按钮必须有可访问名称
+
+## 9. 动效总原则
+
+EasyFlow 的动效关键词固定为：
+
+- 细腻
+- 短促
+- 稳定
+- 不变形
+
+动效作用：
+
+- 帮助理解层级变化
+- 帮助理解状态切换
+- 帮助降低跳变感
+
+## 10. 动效时长与缓动
+
+### 10.1 推荐时长
+
+- 微交互：`120ms - 160ms`
+- 常规切换：`180ms - 240ms`
+- 弹窗 / 抽屉：`220ms - 280ms`
+
+### 10.2 推荐缓动
+
+- 常规：`cubic-bezier(0.2, 0, 0, 1)`
+- 进入：`cubic-bezier(0.16, 1, 0.3, 1)`
+- 离开：`cubic-bezier(0.3, 0, 1, 1)`
+
+### 10.3 禁止事项
+
+- 弹跳
+- 果冻式形变
+- 过长动画
+- 多段花哨运动
+- 与业务无关的常驻装饰动画
+
+## 11. 推荐动效模式
+
+### 11.1 Hover
+
+- 颜色轻微变化
+- 背景轻微提亮
+- 轻微阴影或轻微上浮
+
+### 11.2 Focus
+
+- 清晰焦点环
+- 轻量边框强化
+
+### 11.3 面板出现
+
+- 淡入 + 轻微位移
+- 避免大幅滑入造成压迫感
+
+### 11.4 弹窗 / 抽屉
+
+- 淡入 + 轻微缩放或轻微滑入
+- 遮罩过渡应与内容同步，不可明显割裂
+
+### 11.5 列表更新
+
+- 避免整表闪烁刷新
+- 局部更新优先于全局重新挂载
+
+## 12. 页面级体验规范
+
+### 12.1 页面切换
+
+- 保持节奏轻，优先稳定而不是显著
+- 页面标题、工具栏、内容区切换不应各自动太多
+
+### 12.2 骨架屏与占位
+
+- 骨架屏结构应接近真实布局
+- 不要用与实际结构完全不一致的占位图形
+
+### 12.3 响应式行为
+
+- 优先保持信息层级和操作顺序
+- 不要简单缩小所有控件到影响手感
+- 小屏下优先重排而不是一味压缩
+
+## 13. AI 模块交互建议
+
+### 13.1 生成中
+
+- 应让用户知道系统正在做什么
+- 若耗时较长，可显示阶段性状态或进度提示
+
+### 13.2 工具调用 / 工作流执行
+
+- 优先呈现当前步骤、结果和异常信息
+- 不要让执行过程完全黑盒化
+
+### 13.3 失败恢复
+
+- 失败后提供重试、编辑输入、查看错误原因等恢复路径
+- 对话和流程记录尽量保留，避免用户重新来过
+
+## 14. 与当前代码的演进建议
+
+当前设计层已有：
+
+- `transition.css`
+- `ui.css`
+- 若干组件内联 `transition-*` 规则
+
+建议后续演进：
+
+1. 先统一动效时长和缓动命名
+2. 再逐步收敛组件内散落的 transition 写法
+3. 最终沉淀为基础动效 token 和少量标准过渡模式
+
+## 15. 交付时必须说明
+
+如果任务涉及交互、状态、表单、浮层或动效改动，交付说明必须补充：
+
+- 交互变化服务了什么任务目标
+- 是否补齐了 loading、失败恢复与空状态
+- 动效是否符合“细腻、短促、稳定、不变形”
+- 是否影响键盘可达性、焦点样式或响应式表现