docs: 新增产品设计规范知识库

- 新增产品主题、色彩体系与三端一致性规范\n- 补充 Design Tokens 草案与基础组件规范\n- 补充交互与动效规范及设计文档索引
2026-03-06 14:39:14 +08:00
parent 265bb79ba3
commit 76c2954a70
5 changed files with 1283 additions and 0 deletions
--- a/docs/design/design-tokens-draft.md
+++ 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 实际代码映射表