Design Tokens 规范
本规范定义 Web App 的视觉 token 体系，包括颜色、字体、字号、间距、圆角、边框、阴影、动效、断点与图表配色。页面与组件不得直接依赖临时字面量样式，必须通过语义 token 使用统一的视觉语言。
1. Token 体系设计原则
- 页面与业务组件只消费语义 token，不直接消费品牌字面量。
- token 的命名应以语义为中心，而不是以颜色名称或页面名称为中心。
- 同一语义只能有一个主推荐 token，避免并列近义命名。
- token 必须可映射到当前
web/app/globals.css 的 CSS variable 体系。
- token 的新增、删除和重命名必须同步更新 Handbook 与实现。
2. Token 分层模型
设计系统中的 token 应分为三层：
- Source layer：品牌与基础色值、基础尺寸、基础时长。
- Semantic layer：
background、foreground、primary、border、surface、success 一类面向语义的命名。
- Implementation layer：落地为
web/app/globals.css 中的 CSS variables 与受控 utility class。
页面代码只允许使用 semantic layer，不允许在 JSX 中自行创建新的视觉语义。
3. 颜色 Token 表
3.1 Canvas / Surface
| Token |
语义用途 |
Light 值 |
允许场景 |
实现落点 |
备注 |
background |
全局主画布 |
#eef1fb |
页面背景、壳层背景 |
--background / --color-background |
从现有 landing 基调收敛 |
surface |
主内容承载层 |
#ffffff |
卡片、表单、主面板 |
--card / --color-card |
主要信息容器 |
surface-muted |
次级表面 |
#f8f9fd |
辅助块、次级说明容器 |
新增 semantic token |
替代页面局部浅灰背景 |
surface-elevated |
强层级浮层 |
rgba(255,255,255,0.86) |
浮层、摘要卡、轻玻璃面板 |
新增 semantic token |
应与 blur 一起使用 |
popover |
叠层容器 |
#ffffff |
popover、dropdown、dialog |
--popover |
与 surface 接近但优先级更高 |
3.2 Text
| Token |
语义用途 |
Light 值 |
允许场景 |
实现落点 |
备注 |
foreground |
主阅读文本 |
#08112a |
标题、正文、主数据 |
--foreground / --color-foreground |
主阅读层 |
muted-foreground |
次级文本 |
#5a6680 |
辅助文案、说明文、占位文案 |
--muted-foreground |
低优先级内容 |
technical-label |
技术注释文本 |
#45515e |
mono 标签、trace、code meta |
新增 semantic token |
避免复用普通 muted 文本 |
inverse-foreground |
深底浅字 |
#ffffff |
深色 CTA、深色底 banner |
semantic alias |
用于反白场景 |
3.3 Brand / Interaction
| Token |
语义用途 |
Light 值 |
允许场景 |
实现落点 |
备注 |
primary |
主交互强调色 |
#2855f5 |
主按钮、主链接、主 focus |
--primary / --color-primary |
统一品牌蓝 |
primary-hover |
主交互 hover |
#1e45e0 |
hover 态 |
semantic alias |
页面不得硬编码 |
primary-active |
主交互 active |
#1838cc |
pressed 态 |
semantic alias |
页面不得硬编码 |
primary-soft |
轻强调背景 |
#eef2ff |
icon tray、selected soft state |
semantic alias |
轻量品牌承托层 |
primary-glow |
品牌辉光 |
rgba(40,85,245,0.18) |
hero/auth/summary glow |
semantic alias |
不可滥用在 dense data 页面 |
focus-ring |
焦点环 |
rgba(40,85,245,0.18) |
focus-visible |
--ring / semantic alias |
替代页面局部 ring recipe |
3.4 Border / Feedback / Chart
| Token |
语义用途 |
Light 值 |
允许场景 |
实现落点 |
备注 |
border |
默认边框 |
rgba(8,17,42,0.09) |
卡片、输入框、分割线 |
--border / --color-border |
主边界语言 |
border-strong |
强分隔 |
rgba(8,17,42,0.16) |
高优先级结构边界 |
新增 semantic token |
不作为默认边框 |
success |
成功反馈 |
#0fb981 |
success badge、验证成功 |
--success |
状态色 |
warning |
警示反馈 |
#f59e0b |
warning 提示 |
--warning |
状态色 |
info |
信息提示 |
#2855f5 |
info banner、hint |
--info |
可与 primary 同源 |
destructive |
错误/危险 |
#d4183d |
destructive 操作、错误提示 |
--destructive |
状态色 |
chart-1 ~ chart-5 |
主图表序列 |
见实现 |
图表系列色 |
--chart-* |
应保持对比与秩序 |
4. Typography Token 表
| Token / Style |
字体 |
权重 |
尺寸 |
行高 |
Tracking |
场景 |
替换说明 |
display-xl |
Fraunces |
600 |
56-64px |
1.02 |
-0.03em |
hero / 空状态大标题 |
仅展示用途 |
display-lg |
Fraunces |
600 |
40-48px |
1.08 |
-0.02em |
关键区块标题 |
不能用于 dense page |
heading-lg |
DM Sans |
600 |
28-32px |
1.15 |
-0.02em |
页面一级标题 |
App 主标题 |
heading-md |
DM Sans |
600 |
22-24px |
1.2 |
-0.01em |
面板标题 |
内容区块 |
section-title |
DM Sans |
600 |
18-20px |
1.3 |
-0.01em |
子区块标题 |
高频使用 |
body-md |
DM Sans |
400 |
14-16px |
1.55 |
0 |
正文 |
默认 body |
body-sm |
DM Sans |
400 |
13-14px |
1.5 |
0 |
次级正文 |
辅助说明 |
meta |
DM Sans |
500 |
12px |
1.4 |
0.01em |
元信息、辅助标签 |
替换零散 11px 正文 |
eyebrow |
Mono |
500 |
10-11px |
1.3 |
0.18em |
小写标题、系统标签 |
统一替代 ad hoc uppercase label |
code-sm |
Mono |
500 |
11-12px |
1.45 |
0 |
SQL、trace、timestamp |
技术文本 |
metric-lg |
DM Sans |
700 |
24-28px |
1.1 |
-0.02em |
指标值、关键数字 |
数字优先 |
字体使用规则
- DM Sans 是默认 UI / body 字体。
- Fraunces 只用于展示性标题和有限高强调区域。
- Mono 只用于技术语义，不应用作普通描述文本。
- 不允许继续在页面中自由定义
text-[10px]、text-[11px] 作为长期方案。
5. Spacing Token 表
| Token |
值 |
语义用途 |
常见组合 |
space-2 |
0.5rem |
紧密间距 |
icon + label |
space-3 |
0.75rem |
小模块垂直节奏 |
badge row |
space-4 |
1rem |
默认组件间距 |
form stack |
space-5 |
1.25rem |
卡片内部舒适间距 |
card section |
space-6 |
1.5rem |
主要区块内边距 |
summary block |
space-8 |
2rem |
页面级区块间距 |
panel stack |
space-10 |
2.5rem |
大区块间距 |
overview sections |
content-max |
80rem |
主内容最大宽度 |
overview / landing-like sections |
shell-gutter |
1rem / 1.5rem |
app shell 内边距 |
responsive shell |
6. Radius / Border / Elevation Token 表
6.1 Radius
| Token |
值 |
用途 |
radius-sm |
12px |
输入框、badge、小按钮 |
radius-md |
16px |
默认按钮、导航块、内嵌卡片 |
radius-lg |
20px |
主卡片、浮层、摘要面板 |
radius-pill |
999px |
状态 pill、chip |
6.2 Border / Elevation
| Token |
值 |
用途 |
限制 |
border-default |
1px / rgba(8,17,42,0.09) |
默认结构边界 |
常规使用 |
border-strong |
1px / rgba(8,17,42,0.16) |
强结构边界 |
仅结构强调 |
shadow-sm |
0 1px 3px rgba(8,17,42,0.04) |
轻量控件 |
不用于大卡片 |
shadow-md |
0 4px 16px rgba(8,17,42,0.06) |
默认卡片 |
主内容块 |
shadow-lg |
0 8px 30px rgba(8,17,42,0.08) |
浮层 / 强调面板 |
稀缺使用 |
shadow-brand-glow |
0 24px 64px rgba(40,85,245,0.10) |
品牌高亮 |
仅 auth/summary/hero-like surfaces |
7. Motion / Breakpoint / Z-Index Token 表
7.1 Motion
| Token |
时长 |
Easing |
用途 |
Reduced Motion |
motion-micro |
150-180ms |
ease-out |
hover / focus / subtle toggle |
直接淡化 |
motion-state |
180-220ms |
ease-out |
pressed / open / close |
降为 opacity transition |
motion-panel |
240-320ms |
cubic-bezier(0.25,0.46,0.45,0.94) |
panel reveal |
保留最小移动 |
motion-stagger |
500-720ms |
cubic-bezier(0.25,0.46,0.45,0.94) |
section entrance |
改为静态显示 |
7.2 Breakpoints / Z-Index
| Token |
值 |
用途 |
bp-sm |
640px |
移动端增强布局 |
bp-md |
768px |
平板布局 |
bp-lg |
1024px |
desktop shell |
bp-xl |
1280px |
宽屏分析面 |
z-header |
30 |
顶部导航 |
z-sidebar |
20 |
左侧栏 |
z-popover |
40 |
popover / dropdown |
z-modal |
50 |
dialog / sheet |
z-toast |
60 |
toast / notification |
8. 旧值迁移映射
| 旧实现 |
新 token |
影响区域 |
优先级 |
#2855f5 in JSX |
primary |
auth、landing-like blocks、CTA |
P0 |
#1e45e0 / #1838cc |
primary-hover / primary-active |
按钮状态 |
P0 |
text-[10px] |
eyebrow / meta |
session/chat/results |
P0 |
text-[11px] |
meta / code-sm |
session/chat/results |
P0 |
var(--landing-*) page-only usage |
unified semantic tokens |
landing-derived surfaces |
P1 |
| 页面局部 shadow recipe |
shadow-sm / shadow-md / shadow-lg |
auth、cards、results |
P1 |
9. 实现约束
- token 的实现源头统一落在
web/app/globals.css。
- 页面 JSX 中不允许直接新增新的品牌色或状态色字面量。
- 共享组件只能消费 semantic token，不得反向依赖页面私有 CSS 变量。
- dark mode 在本规范中只记录为后续派生任务，不在本轮给出完整配色表。