EasyFlow/docs/design/design-tokens-draft.md

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. 推荐目录与命名方向

建议未来逐步按以下能力组织：

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 字体族

--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

--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

--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

--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

--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

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