design-tokens
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDesign Tokens
设计令牌
Generate type scales, color palettes, spacing systems, and dark mode derivations with math — not guessing. Includes WCAG contrast checking, systematic spacing grids, and production-ready CSS/Tailwind output.
通过数学计算而非主观猜测生成字体比例、调色板、间距系统及深色模式配色。包含WCAG对比度检测、系统化间距网格,以及可直接用于生产环境的CSS/Tailwind输出。
When to Use
适用场景
- User is setting up a new project's design system
- User asks for a type scale, color palette, or spacing system
- User needs WCAG-compliant color combinations
- User wants dark mode colors derived from a light palette
- User asks for "design tokens" or "theme setup"
- Building a Tailwind config or CSS custom properties
- 正在为新项目搭建设计系统
- 需要字体比例、调色板或间距系统
- 需要符合WCAG标准的配色组合
- 希望从浅色配色衍生出深色模式配色
- 需求涉及“设计令牌”或“主题搭建”
- 构建Tailwind配置或CSS自定义属性
Core Philosophy
核心原则
- Math over taste. Scales should follow ratios, not arbitrary values.
- Accessibility by default. Every text/background combo must pass WCAG AA.
- Systematic. Every value should be derivable from a base + ratio.
- Portable. Output as CSS custom properties, Tailwind config, or JSON tokens.
- 以数学逻辑替代主观偏好:比例应遵循固定比率,而非任意数值。
- 默认保障无障碍性:所有文字/背景组合必须通过WCAG AA标准。
- 系统化设计:所有数值都应能通过基础值+比率推导得出。
- 可移植性:支持输出为CSS自定义属性、Tailwind配置或JSON令牌。
Type Scale Generation
字体比例生成
The Formula
计算公式
fontSize = baseFontSize × ratio^stepfontSize = baseFontSize × ratio^stepRecommended Ratios
推荐比率
| Ratio | Name | Value | Best for |
|---|---|---|---|
| Minor Second | 1.067 | Tight, minimal difference | Dense UI, dashboards |
| Major Second | 1.125 | Subtle progression | Apps, data-heavy interfaces |
| Minor Third | 1.200 | Balanced, versatile | Most websites, SaaS |
| Major Third | 1.250 | Clear hierarchy | Marketing sites, blogs |
| Perfect Fourth | 1.333 | Strong contrast | Editorial, landing pages |
| Augmented Fourth | 1.414 | Dramatic | Bold designs, portfolios |
| Perfect Fifth | 1.500 | Very dramatic | Hero-heavy designs |
| 比率 | 名称 | 数值 | 适用场景 |
|---|---|---|---|
| 小二度 | 1.067 | 差异细微、紧凑 | 密集型UI、数据仪表盘 |
| 大二度 | 1.125 | 过渡平缓 | 应用程序、数据密集型界面 |
| 小三度 | 1.200 | 平衡通用 | 多数网站、SaaS产品 |
| 大三度 | 1.250 | 层级清晰 | 营销网站、博客 |
| 纯四度 | 1.333 | 对比强烈 | 编辑类内容、着陆页 |
| 增四度 | 1.414 | 视觉冲击力强 | 大胆设计、作品集 |
| 纯五度 | 1.500 | 极具张力 | 主打Hero区域的设计 |
Generating the Scale
生成比例
Given a base size (typically 16px) and a ratio:
Step -2: 16 / ratio² = xs
Step -1: 16 / ratio = sm
Step 0: 16 = base
Step 1: 16 × ratio = lg
Step 2: 16 × ratio² = xl
Step 3: 16 × ratio³ = 2xl
Step 4: 16 × ratio⁴ = 3xl
Step 5: 16 × ratio⁵ = 4xl
Step 6: 16 × ratio⁶ = 5xlRound to nearest 0.5px or convert to rem (÷ 16).
给定基础字号(通常为16px)和比率:
Step -2: 16 / ratio² = xs
Step -1: 16 / ratio = sm
Step 0: 16 = base
Step 1: 16 × ratio = lg
Step 2: 16 × ratio² = xl
Step 3: 16 × ratio³ = 2xl
Step 4: 16 × ratio⁴ = 3xl
Step 5: 16 × ratio⁵ = 4xl
Step 6: 16 × ratio⁶ = 5xl四舍五入到最接近的0.5px,或转换为rem单位(÷16)。
Line Height Rules
行高规则
| Font Size | Line Height | Use |
|---|---|---|
| ≤ 14px | 1.6–1.7 | Small text, captions |
| 16–20px | 1.5–1.6 | Body text |
| 20–32px | 1.3–1.4 | Subheadings |
| 32–48px | 1.1–1.2 | Headings |
| 48px+ | 1.0–1.1 | Display/hero text |
Rule of thumb: As font size increases, line height decreases.
| 字号 | 行高范围 | 适用场景 |
|---|---|---|
| ≤14px | 1.6–1.7 | 小号文字、说明文字 |
| 16–20px | 1.5–1.6 | 正文内容 |
| 20–32px | 1.3–1.4 | 副标题 |
| 32–48px | 1.1–1.2 | 标题 |
| 48px+ | 1.0–1.1 | 展示型/ Hero区域文字 |
经验法则:字号越大,行高越小。
Letter Spacing Rules
字间距规则
| Size | Letter Spacing | Why |
|---|---|---|
| Small text (≤14px) | | Slightly open for readability |
| Body text | | Don't touch it |
| Subheadings | | Slightly tighten |
| Headings | | Tighten as size grows |
| Display text | | Tight tracking at large sizes |
| 字号范围 | 字间距 | 原因 |
|---|---|---|
| 小号文字(≤14px) | | 适当拉开提升可读性 |
| 正文 | | 无需调整 |
| 副标题 | | 适当收紧 |
| 标题 | | 字号越大,收紧幅度越大 |
| 展示型文字 | | 大字号下大幅收紧字距 |
Font Weight Pairing
字体粗细搭配
| Role | Weight | Tailwind |
|---|---|---|
| Body | 400 (Regular) | |
| Body emphasis | 500 (Medium) | |
| Subheading | 600 (Semibold) | |
| Heading | 700 (Bold) | |
| Display | 800 (Extrabold) | |
| 角色 | 粗细值 | Tailwind 类名 |
|---|---|---|
| 正文 | 400(常规) | |
| 正文强调 | 500(中等) | |
| 副标题 | 600(半粗) | |
| 标题 | 700(粗体) | |
| 展示型文字 | 800(特粗) | |
Output Example (CSS Custom Properties)
输出示例(CSS自定义属性)
css
:root {
--font-size-xs: 0.694rem; /* 11.1px */
--font-size-sm: 0.833rem; /* 13.3px */
--font-size-base: 1rem; /* 16px */
--font-size-lg: 1.2rem; /* 19.2px */
--font-size-xl: 1.44rem; /* 23px */
--font-size-2xl: 1.728rem; /* 27.6px */
--font-size-3xl: 2.074rem; /* 33.2px */
--font-size-4xl: 2.488rem; /* 39.8px */
--font-size-5xl: 2.986rem; /* 47.8px */
}css
:root {
--font-size-xs: 0.694rem; /* 11.1px */
--font-size-sm: 0.833rem; /* 13.3px */
--font-size-base: 1rem; /* 16px */
--font-size-lg: 1.2rem; /* 19.2px */
--font-size-xl: 1.44rem; /* 23px */
--font-size-2xl: 1.728rem; /* 27.6px */
--font-size-3xl: 2.074rem; /* 33.2px */
--font-size-4xl: 2.488rem; /* 39.8px */
--font-size-5xl: 2.986rem; /* 47.8px */
}Color Palette Generation
调色板生成
Step 1: Choose Base Colors
步骤1:选择基础色
Every palette needs:
| Token | Purpose | Example |
|---|---|---|
| Main brand color, CTAs | Your brand color |
| Text, borders, backgrounds | Gray (warm/cool/pure) |
| Positive states | Green |
| Caution states | Amber/yellow |
| Destructive states | Red |
| Informational | Blue (can overlap primary) |
每个调色板需包含以下类型:
| 令牌 | 用途 | 示例 |
|---|---|---|
| 主品牌色、按钮等交互元素 | 品牌专属颜色 |
| 文字、边框、背景 | 灰色系(暖灰/冷灰/纯灰) |
| 成功状态 | 绿色 |
| 警告状态 | 琥珀色/黄色 |
| 危险操作状态 | 红色 |
| 提示信息 | 蓝色(可与主色重叠) |
Step 2: Generate Shade Scale (50–950)
步骤2:生成色调刻度(50–950)
For each base color, generate a 10-step shade scale. The base color is typically the 500 step.
Method: HSL manipulation
Starting from the base HSL:
| Step | Lightness Adjustment | Saturation Adjustment |
|---|---|---|
| 50 | +45% | -30% |
| 100 | +38% | -25% |
| 200 | +28% | -15% |
| 300 | +18% | -5% |
| 400 | +8% | 0% |
| 500 | 0% (base) | 0% (base) |
| 600 | -8% | +5% |
| 700 | -18% | +5% |
| 800 | -28% | 0% |
| 900 | -38% | -10% |
| 950 | -45% | -20% |
Clamp all values: lightness 0–100%, saturation 0–100%.
针对每个基础色,生成10个层级的色调刻度。基础色通常对应500层级。
方法:HSL调整
从基础色的HSL值开始:
| 层级 | 亮度调整 | 饱和度调整 |
|---|---|---|
| 50 | +45% | -30% |
| 100 | +38% | -25% |
| 200 | +28% | -15% |
| 300 | +18% | -5% |
| 400 | +8% | 0% |
| 500 | 0%(基础值) | 0%(基础值) |
| 600 | -8% | +5% |
| 700 | -18% | +5% |
| 800 | -28% | 0% |
| 900 | -38% | -10% |
| 950 | -45% | -20% |
所有值限制在合理范围:亮度0–100%,饱和度0–100%。
Step 3: Semantic Token Mapping
步骤3:语义令牌映射
Map shade steps to semantic roles:
css
/* Light mode */
--color-bg: var(--neutral-50);
--color-bg-subtle: var(--neutral-100);
--color-bg-muted: var(--neutral-200);
--color-border: var(--neutral-200);
--color-border-strong: var(--neutral-300);
--color-text-muted: var(--neutral-500);
--color-text-subtle: var(--neutral-600);
--color-text: var(--neutral-900);
--color-text-heading: var(--neutral-950);
--color-primary: var(--primary-600);
--color-primary-hover: var(--primary-700);
--color-primary-bg: var(--primary-50);
--color-primary-text: white;将色调刻度映射到语义角色:
css
/* 浅色模式 */
--color-bg: var(--neutral-50);
--color-bg-subtle: var(--neutral-100);
--color-bg-muted: var(--neutral-200);
--color-border: var(--neutral-200);
--color-border-strong: var(--neutral-300);
--color-text-muted: var(--neutral-500);
--color-text-subtle: var(--neutral-600);
--color-text: var(--neutral-900);
--color-text-heading: var(--neutral-950);
--color-primary: var(--primary-600);
--color-primary-hover: var(--primary-700);
--color-primary-bg: var(--primary-50);
--color-primary-text: white;WCAG Contrast Checking
WCAG对比度检测
The Formula
计算公式
Contrast ratio = (L1 + 0.05) / (L2 + 0.05)
Where L1 = lighter relative luminance, L2 = darker.
对比度比值 = (L1 + 0.05) / (L2 + 0.05)
其中L1 = 较亮颜色的相对亮度,L2 = 较暗颜色的相对亮度。
Relative Luminance
相对亮度
For each channel (R, G, B):
sRGB = channel / 255
linear = sRGB <= 0.04045 ? sRGB / 12.92 : ((sRGB + 0.055) / 1.055) ^ 2.4
L = 0.2126 × R_linear + 0.7152 × G_linear + 0.0722 × B_linear针对每个颜色通道(R, G, B):
sRGB = channel / 255
linear = sRGB <= 0.04045 ? sRGB / 12.92 : ((sRGB + 0.055) / 1.055) ^ 2.4
L = 0.2126 × R_linear + 0.7152 × G_linear + 0.0722 × B_linearWCAG Requirements
WCAG要求
| Level | Ratio | Applies to |
|---|---|---|
| AA Normal Text | ≥ 4.5:1 | Body text (< 18px or < 14px bold) |
| AA Large Text | ≥ 3:1 | ≥ 18px regular or ≥ 14px bold |
| AAA Normal Text | ≥ 7:1 | Enhanced accessibility |
| AA UI Components | ≥ 3:1 | Borders, icons, focus rings |
| 级别 | 比值 | 适用范围 |
|---|---|---|
| AA级常规文字 | ≥4.5:1 | 正文(<18px 或 <14px粗体) |
| AA级大号文字 | ≥3:1 | ≥18px常规或 ≥14px粗体 |
| AAA级常规文字 | ≥7:1 | 增强无障碍性场景 |
| AA级UI组件 | ≥3:1 | 边框、图标、焦点环 |
Quick Reference (Neutral on White #FFFFFF)
快速参考(白色背景#FFFFFF上的中性色)
| Shade | Approx Contrast | Passes |
|---|---|---|
| 300 | ~2.5:1 | ❌ Decorative only |
| 400 | ~3.5:1 | ✅ Large text, UI |
| 500 | ~4.5:1 | ✅ AA body text |
| 600 | ~6:1 | ✅ AA comfortable |
| 700 | ~8:1 | ✅ AAA body text |
| 色调 | 近似对比度 | 是否达标 |
|---|---|---|
| 300 | ~2.5:1 | ❌ 仅适用于装饰 |
| 400 | ~3.5:1 | ✅ 大号文字、UI组件 |
| 500 | ~4.5:1 | ✅ AA级正文标准 |
| 600 | ~6:1 | ✅ AA级舒适阅读标准 |
| 700 | ~8:1 | ✅ AAA级正文标准 |
Checking Contrast Programmatically
程序化对比度检测
When generating palettes, always verify:
- (900) on
text(50) → must be ≥ 4.5:1bg - (500) on
text-muted(50) → must be ≥ 4.5:1bg - (600) on
primary→ must be ≥ 4.5:1white - on
primary-text(600) → must be ≥ 4.5:1primary - (200) on
border(50) → must be ≥ 3:1bg
If a combo fails, adjust the darker color one step darker until it passes.
生成调色板时,需验证以下组合:
- (900)在
text(50)上 → 必须≥4.5:1bg - (500)在
text-muted(50)上 → 必须≥4.5:1bg - (600)在白色上 → 必须≥4.5:1
primary - 在
primary-text(600)上 → 必须≥4.5:1primary - (200)在
border(50)上 → 必须≥3:1bg
若组合不达标,将深色颜色调暗一个层级直至达标。
Spacing System
间距系统
Base-4 Scale (Recommended)
基础4px刻度(推荐)
Everything is a multiple of 4px. Predictable, consistent, works with most font sizes.
css
:root {
--space-0: 0px;
--space-0.5: 2px;
--space-1: 4px;
--space-1.5: 6px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 20px;
--space-6: 24px;
--space-8: 32px;
--space-10: 40px;
--space-12: 48px;
--space-16: 64px;
--space-20: 80px;
--space-24: 96px;
--space-32: 128px;
}This matches Tailwind's default scale exactly.
所有间距均为4px的倍数。可预测、一致性强,适配多数字号。
css
:root {
--space-0: 0px;
--space-0.5: 2px;
--space-1: 4px;
--space-1.5: 6px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 20px;
--space-6: 24px;
--space-8: 32px;
--space-10: 40px;
--space-12: 48px;
--space-16: 64px;
--space-20: 80px;
--space-24: 96px;
--space-32: 128px;
}与Tailwind默认刻度完全匹配。
Spacing Usage Guide
间距使用指南
| Context | Spacing | Values |
|---|---|---|
| Inline icon gap | space-1 to space-2 | 4–8px |
| Button padding | space-2 × space-4 | 8px 16px |
| Card padding | space-4 to space-6 | 16–24px |
| Section gap (between elements) | space-6 to space-8 | 24–32px |
| Section padding (container) | space-12 to space-16 | 48–64px |
| Page section vertical rhythm | space-16 to space-24 | 64–96px |
| 场景 | 间距范围 | 数值 |
|---|---|---|
| 图标与文字间距 | space-1至space-2 | 4–8px |
| 按钮内边距 | space-2 × space-4 | 8px 16px |
| 卡片内边距 | space-4至space-6 | 16–24px |
| 元素间隙 | space-6至space-8 | 24–32px |
| 容器内边距 | space-12至space-16 | 48–64px |
| 页面区块垂直间距 | space-16至space-24 | 64–96px |
The Container Width Scale
容器宽度刻度
| Token | Width | Use |
|---|---|---|
| 640px | Narrow content (auth forms) |
| 768px | Blog posts, documentation |
| 1024px | App layouts |
| 1280px | Wide layouts |
| 1536px | Full-width dashboards |
| 令牌 | 宽度 | 适用场景 |
|---|---|---|
| 640px | 窄内容区(如登录表单) |
| 768px | 博客文章、文档 |
| 1024px | 应用布局 |
| 1280px | 宽布局 |
| 1536px | 全屏仪表盘 |
Dark Mode Derivation
深色模式配色衍生
The Inversion Pattern
反转模式
Don't manually pick dark mode colors. Derive them systematically:
Light mode → Dark mode
neutral-50 (bg) → neutral-950 (bg)
neutral-100 (bg-subtle) → neutral-900 (bg-subtle)
neutral-200 (border) → neutral-800 (border)
neutral-300 (border-strong) → neutral-700 (border-strong)
neutral-500 (text-muted) → neutral-400 (text-muted)
neutral-600 (text-subtle) → neutral-300 (text-subtle)
neutral-900 (text) → neutral-50 (text)
neutral-950 (heading) → neutral-50 (heading)The rule: Background shades flip (50↔950, 100↔900, 200↔800). Text shades flip similarly. Middle shades (400–600) shift by ~1–2 steps.
无需手动选择深色模式配色,通过系统化方式衍生:
浅色模式 → 深色模式
neutral-50 (背景) → neutral-950 (背景)
neutral-100 (次要背景) → neutral-900 (次要背景)
neutral-200 (边框) → neutral-800 (边框)
neutral-300 (粗边框) → neutral-700 (粗边框)
neutral-500 (次要文字) → neutral-400 (次要文字)
neutral-600 (辅助文字) → neutral-300 (辅助文字)
neutral-900 (正文) → neutral-50 (正文)
neutral-950 (标题) → neutral-50 (标题)规则:背景色阶反转(50↔950、100↔900、200↔800)。文字色阶同理反转。中间色阶(400–600)调整1–2个层级。
Primary Color in Dark Mode
深色模式下的主色
- Use a lighter step: or
primary-400instead ofprimary-500primary-600 - Reduce saturation slightly for dark backgrounds (avoids eye strain)
- Verify contrast against or
neutral-900backgroundneutral-950
- 使用更浅的色阶:用或
primary-400替代primary-500primary-600 - 略微降低饱和度,避免深色背景下刺眼
- 验证与或
neutral-900背景的对比度neutral-950
Semantic Tokens for Dark Mode
深色模式的语义令牌
css
/* Light */
:root {
--color-bg: var(--neutral-50);
--color-text: var(--neutral-900);
--color-primary: var(--primary-600);
}
/* Dark */
.dark {
--color-bg: var(--neutral-950);
--color-text: var(--neutral-50);
--color-primary: var(--primary-400);
}The beauty: components reference semantic tokens, never raw shades. Switching themes is just swapping the token mapping.
css
/* 浅色模式 */
:root {
--color-bg: var(--neutral-50);
--color-text: var(--neutral-900);
--color-primary: var(--primary-600);
}
/* 深色模式 */
.dark {
--color-bg: var(--neutral-950);
--color-text: var(--neutral-50);
--color-primary: var(--primary-400);
}优势:组件引用语义令牌而非原始色阶,切换主题仅需更换令牌映射关系。
Output Formats
输出格式
CSS Custom Properties
CSS自定义属性
css
:root {
/* Type */
--font-size-base: 1rem;
--font-size-lg: 1.2rem;
/* Colors */
--color-primary-500: hsl(220, 80%, 50%);
/* Spacing */
--space-4: 1rem;
}css
:root {
/* 字体 */
--font-size-base: 1rem;
--font-size-lg: 1.2rem;
/* 颜色 */
--color-primary-500: hsl(220, 80%, 50%);
/* 间距 */
--space-4: 1rem;
}Tailwind Config
Tailwind配置
js
module.exports = {
theme: {
extend: {
fontSize: {
'xs': '0.694rem',
'sm': '0.833rem',
'base': '1rem',
'lg': '1.2rem',
'xl': '1.44rem',
},
colors: {
primary: {
50: 'hsl(220, 50%, 95%)',
500: 'hsl(220, 80%, 50%)',
900: 'hsl(220, 60%, 15%)',
},
},
},
},
}js
module.exports = {
theme: {
extend: {
fontSize: {
'xs': '0.694rem',
'sm': '0.833rem',
'base': '1rem',
'lg': '1.2rem',
'xl': '1.44rem',
},
colors: {
primary: {
50: 'hsl(220, 50%, 95%)',
500: 'hsl(220, 80%, 50%)',
900: 'hsl(220, 60%, 15%)',
},
},
},
},
}JSON Design Tokens (W3C Format)
JSON设计令牌(W3C格式)
json
{
"color": {
"primary": {
"500": { "$value": "hsl(220, 80%, 50%)", "$type": "color" }
}
},
"fontSize": {
"base": { "$value": "1rem", "$type": "dimension" }
}
}json
{
"color": {
"primary": {
"500": { "$value": "hsl(220, 80%, 50%)", "$type": "color" }
}
},
"fontSize": {
"base": { "$value": "1rem", "$type": "dimension" }
}
}Step-by-Step: Full Design Token Setup
分步指南:完整设计令牌搭建流程
- Ask: What's the project? (marketing site, SaaS app, dashboard?)
- Type scale: Pick ratio based on project type → generate scale
- Colors: Get brand color → generate shade scales for primary + neutral + semantic
- Verify contrast: Check all text/bg combos against WCAG AA
- Spacing: Use base-4 scale (match Tailwind)
- Dark mode: Derive from light palette using inversion pattern
- Output: Generate CSS custom properties and/or Tailwind config
- 询问:项目类型?(营销网站、SaaS应用、仪表盘?)
- 字体比例:根据项目类型选择比率→生成比例
- 颜色:获取品牌色→为主色、中性色、语义色生成色调刻度
- 对比度验证:检查所有文字/背景组合是否符合WCAG AA标准
- 间距:使用基础4px刻度(匹配Tailwind默认)
- 深色模式:通过反转模式从浅色配色衍生
- 输出:生成CSS自定义属性和/或Tailwind配置
Examples
示例
Example 1: "Set up design tokens for a SaaS dashboard"
示例1:“为SaaS仪表盘搭建设计令牌”
- Type: Minor Third (1.2) ratio, 16px base — clear hierarchy without being dramatic
- Colors: Generate from brand blue, warm gray neutral
- Spacing: Base-4 (Tailwind default)
- Dark mode: Full derivation
- 字体比例:小三度(1.2)比率,16px基础值→层级清晰且不过于夸张
- 颜色:从品牌蓝色生成,搭配暖灰色中性色
- 间距:基础4px刻度(Tailwind默认)
- 深色模式:完整衍生配色
Example 2: "I need a color palette from this brand color: #6366F1"
示例2:“基于品牌色#6366F1生成调色板”
- Parse HSL: ~239°, 84%, 67%
- Generate 50–950 scale using the shade generation method
- Map semantic tokens
- Verify WCAG contrast for all text/bg combos
- Output as CSS + Tailwind config
- 解析HSL:~239°, 84%, 67%
- 使用色调生成方法生成50–950刻度
- 映射语义令牌
- 验证所有文字/背景组合的WCAG对比度
- 输出为CSS + Tailwind配置
Example 3: "Create a type scale for a blog"
示例3:“为博客创建字体比例”
- Ratio: Major Third (1.25) — strong hierarchy for editorial content
- Base: 18px (slightly larger for long-form reading)
- Generate scale with line-height and letter-spacing for each step
- 比率:大三度(1.25)→编辑类内容层级区分明显
- 基础值:18px(长文阅读更舒适)
- 为每个比例生成对应的行高和字距