404 lines
12 KiB
Markdown
404 lines
12 KiB
Markdown
# EasyFlow Design Tokens 草案 v1
|
||
|
||
## 1. 文档目标
|
||
|
||
本草案用于定义 EasyFlow 后续主题系统、设计变量与公共层实现的统一方向，指导 `@core/base/design`、`@core/ui-kit` 与 `effects/*` 中的 Token 沉淀方式。
|
||
|
||
本草案不要求一次性重构所有现有 Token，而是用于：
|
||
|
||
- 为后续主题统一提供命名和分层标准
|
||
- 为设计与前端提供同一套语义映射
|
||
- 为浅色 / 深色、三端统一和组件族一致性提供基础
|
||
- 为 EasyFlow 从传统管理后台视觉演进到现代工作台视觉提供稳定底座
|
||
|
||
## 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，不直接定义新的品牌色、中性色、阴影和圆角体系。
|
||
|
||
### 2.4 Token 必须服务现代工作台体验
|
||
|
||
Token 不只是为了“统一”，还要确保 EasyFlow 能稳定呈现更现代的产品气质。
|
||
|
||
应优先支持：
|
||
|
||
- 更鲜明的品牌色角色，而不是只剩一个主按钮蓝
|
||
- 更清晰的表面层级，而不是靠边框堆结构
|
||
- 更轻的导航骨架材质，如轻度液态玻璃、弱染色表面、轻悬浮
|
||
- 更开放的大屏工作台布局，而不是传统表单后台的硬切分区
|
||
|
||
## 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-container` | `#DDEBFF` | 品牌容器 / 当前态柔和承载面 |
|
||
| `--color-primary-foreground` | `#FFFFFF` | 品牌色上的文字 |
|
||
|
||
补充：
|
||
|
||
- 参考 Material Design 3 的 `color roles` 思路，品牌色不应只出现在按钮，还应进入导航当前态、局部染色表面、焦点和关键反馈。
|
||
- 参考 Apple 导航骨架表达，品牌色进入表面层时应优先使用低浓度容器色，而不是整块纯色铺底。
|
||
|
||
### 4.2 中性色
|
||
|
||
| Token | 值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `--color-bg-app` | `#F6F8FB` | 页面背景 |
|
||
| `--color-bg-canvas` | `#F2F5F9` | 内容画布或区域底色 |
|
||
| `--color-bg-panel` | `#FFFFFF` | 卡片、面板、弹窗主背景 |
|
||
| `--color-bg-subtle` | `#F8FAFD` | 次层背景 |
|
||
| `--color-bg-elevated` | `#FCFDFF` | 轻浮起表面 |
|
||
| `--color-bg-glass` | `rgba(255,255,255,0.72)` | 轻度液态玻璃表面 |
|
||
| `--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`: 延续主蓝，但不大幅提高饱和度
|
||
|
||
### 4.5 导航与骨架表面 Token 草案
|
||
|
||
这组 Token 用于支撑顶栏、侧栏、tab、搜索入口、浮层等“现代工作台骨架”。
|
||
|
||
| Token | 建议值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `--color-nav-surface` | `rgba(255,255,255,0.78)` | 导航主表面 |
|
||
| `--color-nav-surface-subtle` | `rgba(255,255,255,0.64)` | 导航次层表面 |
|
||
| `--color-nav-item-hover` | `rgba(22,119,255,0.08)` | 导航 hover |
|
||
| `--color-nav-item-active` | `rgba(22,119,255,0.14)` | 导航当前态容器 |
|
||
| `--color-nav-item-active-text` | `#125ACC` | 导航当前态文字 |
|
||
| `--color-nav-muted-text` | `#536174` | 导航弱文本 |
|
||
| `--color-glass-border` | `rgba(255,255,255,0.68)` | 玻璃表面边界高光 |
|
||
|
||
说明：
|
||
|
||
- 这组 Token 不鼓励厚边框和强高光，而是为“轻度液态玻璃 + 柔和染色 + 轻悬浮”提供统一语义。
|
||
- 页面层不得自己发明玻璃 rgba 值，应优先回到 Token。
|
||
|
||
## 5. 圆角 Token 草案
|
||
|
||
| Token | 值 | 用途 |
|
||
| --- | --- | --- |
|
||
| `--radius-xs` | `8px` | 标签、小型徽标 |
|
||
| `--radius-sm` | `10px` | 按钮、输入框 |
|
||
| `--radius-md` | `12px` | 下拉面板、工具条 |
|
||
| `--radius-lg` | `16px` | 卡片、主面板 |
|
||
| `--radius-xl` | `20px` | 抽屉、弹窗 |
|
||
| `--radius-pill` | `999px` | 胶囊标签、分段控件 |
|
||
|
||
说明：
|
||
|
||
- 圆角应该柔和但理性，不做玩具化超大圆角。
|
||
- 页面层禁止新增“只适合本页”的圆角数值。
|
||
- 导航工具按钮、搜索入口、轻浮层控制点可适度更圆润，但必须通过共享 Token 表达，而不是页面层临时放大圆角。
|
||
|
||
## 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)` | 弹窗、抽屉 |
|
||
| `--shadow-glass` | `0 18px 40px -30px rgba(18, 36, 62, 0.2)` | 玻璃骨架 / 导航悬浮 |
|
||
|
||
说明：
|
||
|
||
- 阴影用于表达层级，不用于制造厚重“高级感”。
|
||
- 同一页面内避免多套阴影并存。
|
||
- 对导航骨架，优先使用轻玻璃阴影和表面层差，而不是把阴影做厚。
|
||
|
||
## 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 Navigation Shell
|
||
|
||
```text
|
||
--nav-surface: var(--color-nav-surface)
|
||
--nav-surface-subtle: var(--color-nav-surface-subtle)
|
||
--nav-item-hover-bg: var(--color-nav-item-hover)
|
||
--nav-item-active-bg: var(--color-nav-item-active)
|
||
--nav-item-active-text: var(--color-nav-item-active-text)
|
||
--nav-item-muted-text: var(--color-nav-muted-text)
|
||
--nav-glass-border: var(--color-glass-border)
|
||
--nav-shadow: var(--shadow-glass)
|
||
--nav-radius: var(--radius-lg)
|
||
--nav-control-radius: var(--radius-pill)
|
||
```
|
||
|
||
说明：
|
||
|
||
- 这组别名 Token 服务顶栏、侧栏、Tab、Breadcrumb、全局搜索、工具按钮等统一导航骨架。
|
||
- 导航骨架的现代感必须来自统一别名 Token，而不是页面层散落的 rgba、blur、shadow 临时值。
|
||
|
||
### 11.4 Panel
|
||
|
||
```text
|
||
--panel-radius: var(--radius-lg)
|
||
--panel-bg: var(--color-bg-panel)
|
||
--panel-border: var(--color-divider)
|
||
--panel-shadow: var(--shadow-sm)
|
||
```
|
||
|
||
### 11.5 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 实际代码映射表
|