design-tokens

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design 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^step
fontSize = baseFontSize × ratio^step

Recommended Ratios

推荐比率

RatioNameValueBest for
Minor Second1.067Tight, minimal differenceDense UI, dashboards
Major Second1.125Subtle progressionApps, data-heavy interfaces
Minor Third1.200Balanced, versatileMost websites, SaaS
Major Third1.250Clear hierarchyMarketing sites, blogs
Perfect Fourth1.333Strong contrastEditorial, landing pages
Augmented Fourth1.414DramaticBold designs, portfolios
Perfect Fifth1.500Very dramaticHero-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⁶ = 5xl
Round 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 SizeLine HeightUse
≤ 14px1.6–1.7Small text, captions
16–20px1.5–1.6Body text
20–32px1.3–1.4Subheadings
32–48px1.1–1.2Headings
48px+1.0–1.1Display/hero text
Rule of thumb: As font size increases, line height decreases.
字号行高范围适用场景
≤14px1.6–1.7小号文字、说明文字
16–20px1.5–1.6正文内容
20–32px1.3–1.4副标题
32–48px1.1–1.2标题
48px+1.0–1.1展示型/ Hero区域文字
经验法则:字号越大,行高越小。

Letter Spacing Rules

字间距规则

SizeLetter SpacingWhy
Small text (≤14px)
0.01–0.02em
Slightly open for readability
Body text
0em
(normal)
Don't touch it
Subheadings
-0.01em
Slightly tighten
Headings
-0.02em
to
-0.03em
Tighten as size grows
Display text
-0.03em
to
-0.05em
Tight tracking at large sizes
字号范围字间距原因
小号文字(≤14px)
0.01–0.02em
适当拉开提升可读性
正文
0em
(默认)
无需调整
副标题
-0.01em
适当收紧
标题
-0.02em
-0.03em
字号越大,收紧幅度越大
展示型文字
-0.03em
-0.05em
大字号下大幅收紧字距

Font Weight Pairing

字体粗细搭配

RoleWeightTailwind
Body400 (Regular)
font-normal
Body emphasis500 (Medium)
font-medium
Subheading600 (Semibold)
font-semibold
Heading700 (Bold)
font-bold
Display800 (Extrabold)
font-extrabold
角色粗细值Tailwind 类名
正文400(常规)
font-normal
正文强调500(中等)
font-medium
副标题600(半粗)
font-semibold
标题700(粗体)
font-bold
展示型文字800(特粗)
font-extrabold

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:
TokenPurposeExample
primary
Main brand color, CTAsYour brand color
neutral
Text, borders, backgroundsGray (warm/cool/pure)
success
Positive statesGreen
warning
Caution statesAmber/yellow
error
Destructive statesRed
info
InformationalBlue (can overlap primary)
每个调色板需包含以下类型:
令牌用途示例
primary
主品牌色、按钮等交互元素品牌专属颜色
neutral
文字、边框、背景灰色系(暖灰/冷灰/纯灰)
success
成功状态绿色
warning
警告状态琥珀色/黄色
error
危险操作状态红色
info
提示信息蓝色(可与主色重叠)

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:
StepLightness AdjustmentSaturation Adjustment
50+45%-30%
100+38%-25%
200+28%-15%
300+18%-5%
400+8%0%
5000% (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%
5000%(基础值)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_linear

WCAG Requirements

WCAG要求

LevelRatioApplies to
AA Normal Text≥ 4.5:1Body text (< 18px or < 14px bold)
AA Large Text≥ 3:1≥ 18px regular or ≥ 14px bold
AAA Normal Text≥ 7:1Enhanced accessibility
AA UI Components≥ 3:1Borders, 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上的中性色)

ShadeApprox ContrastPasses
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:
  1. text
    (900) on
    bg
    (50) → must be ≥ 4.5:1
  2. text-muted
    (500) on
    bg
    (50) → must be ≥ 4.5:1
  3. primary
    (600) on
    white
    → must be ≥ 4.5:1
  4. primary-text
    on
    primary
    (600) → must be ≥ 4.5:1
  5. border
    (200) on
    bg
    (50) → must be ≥ 3:1
If a combo fails, adjust the darker color one step darker until it passes.

生成调色板时,需验证以下组合:
  1. text
    (900)在
    bg
    (50)上 → 必须≥4.5:1
  2. text-muted
    (500)在
    bg
    (50)上 → 必须≥4.5:1
  3. primary
    (600)在白色上 → 必须≥4.5:1
  4. primary-text
    primary
    (600)上 → 必须≥4.5:1
  5. border
    (200)在
    bg
    (50)上 → 必须≥3:1
若组合不达标,将深色颜色调暗一个层级直至达标。

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

间距使用指南

ContextSpacingValues
Inline icon gapspace-1 to space-24–8px
Button paddingspace-2 × space-48px 16px
Card paddingspace-4 to space-616–24px
Section gap (between elements)space-6 to space-824–32px
Section padding (container)space-12 to space-1648–64px
Page section vertical rhythmspace-16 to space-2464–96px
场景间距范围数值
图标与文字间距space-1至space-24–8px
按钮内边距space-2 × space-48px 16px
卡片内边距space-4至space-616–24px
元素间隙space-6至space-824–32px
容器内边距space-12至space-1648–64px
页面区块垂直间距space-16至space-2464–96px

The Container Width Scale

容器宽度刻度

TokenWidthUse
sm
640pxNarrow content (auth forms)
md
768pxBlog posts, documentation
lg
1024pxApp layouts
xl
1280pxWide layouts
2xl
1536pxFull-width dashboards

令牌宽度适用场景
sm
640px窄内容区(如登录表单)
md
768px博客文章、文档
lg
1024px应用布局
xl
1280px宽布局
2xl
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:
    primary-400
    or
    primary-500
    instead of
    primary-600
  • Reduce saturation slightly for dark backgrounds (avoids eye strain)
  • Verify contrast against
    neutral-900
    or
    neutral-950
    background
  • 使用更浅的色阶:用
    primary-400
    primary-500
    替代
    primary-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

分步指南:完整设计令牌搭建流程

  1. Ask: What's the project? (marketing site, SaaS app, dashboard?)
  2. Type scale: Pick ratio based on project type → generate scale
  3. Colors: Get brand color → generate shade scales for primary + neutral + semantic
  4. Verify contrast: Check all text/bg combos against WCAG AA
  5. Spacing: Use base-4 scale (match Tailwind)
  6. Dark mode: Derive from light palette using inversion pattern
  7. Output: Generate CSS custom properties and/or Tailwind config
  1. 询问:项目类型?(营销网站、SaaS应用、仪表盘?)
  2. 字体比例:根据项目类型选择比率→生成比例
  3. 颜色:获取品牌色→为主色、中性色、语义色生成色调刻度
  4. 对比度验证:检查所有文字/背景组合是否符合WCAG AA标准
  5. 间距:使用基础4px刻度(匹配Tailwind默认)
  6. 深色模式:通过反转模式从浅色配色衍生
  7. 输出:生成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(长文阅读更舒适)
  • 为每个比例生成对应的行高和字距