# 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 实际代码映射表