design-tokens

设计令牌

通过计算而非猜测，生成字号比例、调色板、间距系统和暗色模式衍生色。包含 WCAG 对比度检查、系统化间距网格，以及可用于生产环境的 CSS/Tailwind 输出。

适用场景

• 用户正在为新项目搭建设计系统
• 用户需要字号比例、调色板或间距系统
• 用户需要符合 WCAG 标准的颜色组合
• 用户希望从浅色调色板推导出暗色模式颜色
• 用户询问“设计令牌”或“主题设置”
• 构建 Tailwind 配置或 CSS 自定义属性

核心理念

• 计算优先于审美。 比例应遵循既定比率，而非采用随意的数值。
• 默认考虑无障碍性。 每种文字/背景组合都必须通过 WCAG AA 标准。
• 系统化。 每个数值都应能通过基础值和比率推导得出。
• 可移植。 输出为 CSS 自定义属性、Tailwind 配置或 JSON 令牌。

---

生成字号比例

计算公式

fontSize = baseFontSize × ratio^step

推荐比率

比率	名称	数值	最适用场景
小二度	1.067	紧凑，差异最小	密集型 UI、仪表板
大二度	1.125	渐变细微	应用、数据密集型界面
小三度	1.200	均衡、通用	大多数网站、SaaS
大三度	1.250	层级清晰	营销网站、博客
纯四度	1.333	对比强烈	编辑类内容、落地页
增四度	1.414	效果突出	大胆的设计、作品集
纯五度	1.500	效果非常突出	主视觉区块占比较大的设计

生成比例尺

给定一个基准字号（通常为 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）。

行高规则

字号	行高	用途
≤ 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	展示/主视觉文字

经验法则： 字号越大，行高越小。

字间距规则

尺寸	字间距	原因
小号文字（≤14px）	0.01–0.02em	稍微加宽，提升可读性
正文	0em（正常）	保持默认
子标题	-0.01em	稍微收紧
标题	-0.02em 到 -0.03em	随字号增大而收紧
展示文字	-0.03em 到 -0.05em	大字号下收紧字距

字重搭配

角色	字重	Tailwind
正文	400（常规）	font-normal
正文强调	500（中等）	font-medium
子标题	600（半粗）	font-semibold
标题	700（粗体）	font-bold
展示文字	800（特粗）	font-extrabold

输出示例（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 */
}

---

生成调色板

步骤 1：选择基色

每个调色板都需要：

令牌	用途	示例
primary	主要品牌色、CTA	品牌色
neutral	文字、边框、背景	灰色（暖色/冷色/纯灰）
success	成功状态	绿色
warning	警示状态	琥珀色/黄色
error	危险操作状态	红色
info	信息提示	蓝色（可与主色重叠）

步骤 2：生成明暗色阶（50–950）

为每种基色生成包含 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%。

步骤 3：语义令牌映射

将各级色阶映射到语义角色：

/* 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;

---

WCAG 对比度检查

公式

对比度 = (L1 + 0.05) / (L2 + 0.05)

其中，L1 = 较亮颜色的相对亮度，L2 = 较暗颜色的相对亮度。

相对亮度

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

WCAG 要求

级别	比率	适用范围
AA 普通文本	≥ 4.5:1	正文（< 18px 或 < 14px 粗体）
AA 大号文本	≥ 3:1	≥ 18px 常规字重或 ≥ 14px 粗体
AAA 普通文本	≥ 7:1	增强的无障碍性
AA UI 组件	≥ 3:1	边框、图标、焦点环

快速参考（白色 #FFFFFF 上的中性色）

色阶	约略对比度	是否通过
300	~2.5:1	❌ 仅用于装饰
400	~3.5:1	✅ 大号文本、UI
500	~4.5:1	✅ AA 正文文本
600	~6:1	✅ AA，舒适易读
700	~8:1	✅ AAA 正文文本

以编程方式检查对比度

生成调色板时，务必验证：

1. text (900) 在 bg (50) 上 → 必须 ≥ 4.5:1
2. text-muted (500) 在 bg (50) 上 → 必须 ≥ 4.5:1
3. primary (600) 在 white 上 → 必须 ≥ 4.5:1
4. primary-text 在 primary (600) 上 → 必须 ≥ 4.5:1
5. border (200) 在 bg (50) 上 → 必须 ≥ 3:1

如果某种组合未通过，就将较深的颜色加深一个色阶，直到通过为止。

---

间距系统

以 4 为基数的比例（推荐）

所有数值都是 4px 的倍数。规律清晰、保持一致，并且适用于大多数字号。

: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 的默认比例完全一致。

间距使用指南

场景	间距	数值
行内图标间距	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

容器宽度比例

令牌	宽度	用途
sm	640px	窄内容（身份验证表单）
md	768px	博客文章、文档
lg	1024px	应用布局
xl	1280px	宽布局
2xl	1536px	全宽仪表板

---

深色模式推导

反转模式

不要手动挑选深色模式的颜色，而要用系统化的方式推导：

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)

**规则：**背景色阶反转（50↔950、100↔900、200↔800）。文本色阶也类似反转。中间色阶（400–600）则移动约 1–2 个色阶。

深色模式下的主色

• 使用更浅的色阶：用 primary-400 或 primary-500 替代 primary-600
• 在深色背景上稍微降低饱和度（避免视觉疲劳）
• 验证其与 neutral-900 或 neutral-950 背景之间的对比度

深色模式的语义令牌

/* 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);
}

其优势在于：组件引用的是语义令牌，而不是原始色阶。切换主题只需替换令牌映射。

---

输出格式

CSS 自定义属性

:root {
  /* Type */
  --font-size-base: 1rem;
  --font-size-lg: 1.2rem;
  /* Colors */
  --color-primary-500: hsl(220, 80%, 50%);
  /* Spacing */
  --space-4: 1rem;
}

Tailwind 配置

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 设计令牌（W3C 格式）

{
  "color": {
    "primary": {
      "500": { "$value": "hsl(220, 80%, 50%)", "$type": "color" }
    }
  },
  "fontSize": {
    "base": { "$value": "1rem", "$type": "dimension" }
  }
}

---

分步设置完整的设计令牌

1. **询问：**项目是什么类型？（营销网站、SaaS 应用、仪表板？）
2. **字号比例：**根据项目类型选择比例 → 生成比例尺
3. **颜色：**获取品牌色 → 为主色、中性色和语义色生成色阶
4. **验证对比度：**根据 WCAG AA 检查所有文本/背景组合
5. **间距：**使用以 4 为基数的比例（与 Tailwind 保持一致）
6. **深色模式：**使用反转模式从浅色调色板推导
7. **输出：**生成 CSS 自定义属性和/或 Tailwind 配置

示例

示例 1：“为 SaaS 仪表板设置设计令牌”

• 字号比例：小三度（1.2），基准字号为 16px — 层级清晰但不过分突出
• 颜色：从品牌蓝生成，使用暖灰色作为中性色
• 间距：以 4 为基数（Tailwind 默认值）
• 深色模式：完整推导

示例 2：“我需要根据这个品牌色生成调色板：#6366F1”

• 解析 HSL：约 239°、84%、67%
• 使用色阶生成方法生成 50–950 色阶
• 映射语义令牌
• 验证所有文本/背景组合的 WCAG 对比度
• 输出为 CSS + Tailwind 配置

示例 3：“为博客创建字号比例”

• 比例：大三度（1.25）——为编辑内容提供清晰的层级
• 基准：18px（略大，适合长文阅读）
• 为每个级别生成包含行高和字间距的比例