设计系统对齐

Token 主线（设计 → 构建 → 运行）

  [ Figma / 设计库：语义与 primitive ]
        │
        ▼
  ┌─────────────┐     Style Dictionary / Tokens Studio / 主题 JSON
  │  Token 构建  │──── 命名：color.text.default、space.3（团队字典）
  └─────────────┘
        │
        ▼
  ┌─────────────┐     CSS 变量、Tailwind extend、组件库 theme
  │  运行时消费  │──── 禁止散落 hex；暗色用同一语义键切换
  └─────────────┘
        │
        ▼
  ┌─────────────┐     Story / 文档站点 / PR 截图对比设计稿
  │  验收与文档  │──── 变体表 + 节点 ID / 链接可追溯
  └─────────────┘

Design Token CSS 变量定义

/* Design Token 完整 CSS 变量定义（颜色/间距/字体/阴影）*/
:root {
  /* 颜色 - primitive tokens（不直接使用）*/
  --color-blue-50:  #eff6ff;
  --color-blue-500: #3b82f6;
  --color-blue-700: #1d4ed8;
  --color-gray-50:  #f9fafb;
  --color-gray-900: #111827;

  /* 颜色 - semantic tokens（组件消费这层）*/
  --color-bg-primary:      var(--color-gray-50);
  --color-bg-elevated:     #ffffff;
  --color-text-primary:    var(--color-gray-900);
  --color-text-muted:      #6b7280;
  --color-brand:           var(--color-blue-500);
  --color-brand-hover:     var(--color-blue-700);
  --color-border:          #e5e7eb;
  --color-focus-ring:      rgba(59, 130, 246, 0.35);

  /* 间距 - 4px 栅格系统 */
  --space-1: 0.25rem;   /* 4px  */
  --space-2: 0.5rem;    /* 8px  */
  --space-3: 0.75rem;   /* 12px */
  --space-4: 1rem;      /* 16px */
  --space-6: 1.5rem;    /* 24px */
  --space-8: 2rem;      /* 32px */

  /* 字体 */
  --font-family-sans: 'Inter', system-ui, sans-serif;
  --font-family-mono: 'JetBrains Mono', ui-monospace, monospace;
  --font-size-sm:   0.875rem;  /* 14px */
  --font-size-base: 1rem;      /* 16px */
  --font-size-lg:   1.125rem;  /* 18px */
  --font-weight-medium: 500;
  --font-weight-bold:   700;
  --line-height-tight:  1.25;
  --line-height-normal: 1.5;

  /* 阴影 */
  --shadow-sm: 0 1px 2px 0 rgba(0,0,0,0.05);
  --shadow-md: 0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -1px rgba(0,0,0,0.06);

  /* 圆角 */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
}

/* 暗色主题：仅覆盖 semantic tokens，primitive 不变 */
[data-theme="dark"] {
  --color-bg-primary:   #111827;
  --color-bg-elevated:  #1f2937;
  --color-text-primary: #f9fafb;
  --color-text-muted:   #9ca3af;
  --color-border:       #374151;
}

下方色块仅演示本页样式如何消费全局 CSS 变量（随站点明暗主题切换）。

变体系统实现

/* Button variant 系统：primary / secondary / ghost — 映射到 Figma component property */
.btn {
  display: inline-flex;
  align-items: center;
  gap: var(--space-2);
  padding: var(--space-2) var(--space-4);
  font-size: var(--font-size-sm);
  font-weight: var(--font-weight-medium);
  border-radius: var(--radius-md);
  border: 1.5px solid transparent;
  cursor: pointer;
  transition: background 0.15s, color 0.15s, border-color 0.15s;

  /* 焦点环：所有变体统一 */
  &:focus-visible {
    outline: 2px solid var(--color-focus-ring);
    outline-offset: 2px;
  }
}

.btn--primary {
  background: var(--color-brand);
  color: #fff;
  &:hover { background: var(--color-brand-hover); }
}

.btn--secondary {
  background: transparent;
  color: var(--color-brand);
  border-color: var(--color-brand);
  &:hover { background: rgba(59,130,246,0.08); }
}

.btn--ghost {
  background: transparent;
  color: var(--color-text-primary);
  &:hover { background: var(--color-border); }
}

/* 尺寸变体 */
.btn--sm { padding: var(--space-1) var(--space-2); font-size: 0.8rem; }
.btn--lg { padding: var(--space-3) var(--space-6); font-size: var(--font-size-base); }

• 变体轴与设计属性一一对应（如 Button primary / ghost 对应 Figma component property）。
• SKILL 中附对照表或链接，避免 Agent 自创未在库中存在的 variant 名。
• 变更流程：谁审批新 token、如何同步文档与 package 版本。

Style Dictionary 配置：Figma→代码 Token Pipeline

// Style Dictionary 配置：从设计 JSON 生成 CSS 变量
// tokens/config.js
const StyleDictionary = require('style-dictionary');

module.exports = {
  source: ['tokens/**/*.json'],  // Tokens Studio 或 Figma 导出的 JSON
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'color',
      buildPath: 'src/styles/tokens/',
      files: [{ destination: 'tokens.css', format: 'css/variables' }],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'src/styles/tokens/',
      files: [{ destination: 'tokens.js', format: 'javascript/es6' }],
    },
  },
};

// tokens/color.json（设计工具导出格式）
{
  "color": {
    "brand": {
      "value": "#3b82f6",
      "type": "color",
      "description": "主品牌色，对应 Figma: Brand/Primary"
    }
  }
}

// 生成结果：CSS 变量
// :root { --color-brand: #3b82f6; }

暗色模式、对比度与焦点环应遵循 WCAG 与系统内既定 token；新增语义需先检查是否与现有 palette 冲突。

SKILL 片段示例

---
name: design-system-alignment
description: 用设计 Token 与变体映射实现与设计稿一致的 UI
---
# Token 来源与禁止硬编码
1. Token 来源：CSS 变量 / Style Dictionary 产物 / Tailwind theme，三选一并全项目统一
2. 禁止硬编码：颜色/间距/字体/圆角值不得直接写进组件样式
3. 语义层消费：组件引用 --color-brand 而非 --color-blue-500

# 变体与设计属性对照
4. variant 命名与 Figma component property 一一对应，附链接
5. 尺寸变体（sm/md/lg）映射到 Figma size property
6. 禁止 Agent 自创未在设计库中存在的 variant 名

# Token Pipeline
7. 设计工具导出 JSON → Style Dictionary 转换 → CSS 变量 / JS 常量
8. token 变更需走 PR 审批，自动更新 changelog 与版本号
9. CI 对比设计导出与代码 token，漂移超阈值报警

# 主题与对比度
10. 暗色模式仅覆盖 semantic token 层，primitive 不变
11. 对比度：文字与背景至少 4.5:1（WCAG AA），大文字 3:1
12. 焦点环所有交互元素统一样式，不允许 outline:none 无替代

# 文档与验收
13. Story 覆盖：所有 variant × 所有 size × 亮/暗主题
14. 视觉回归测试：PR 截图与设计稿对比
15. 变更流程：新 token 须先在 Figma 创建，再走代码 PR

本站 CSS 变量速查（复制）