design-token-extractor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Token Extractor

Design Token 提取器

Extract design tokens from any source and structure them into a portable, multi-format token system.

从任意来源提取设计令牌，并将其构建为可移植的多格式令牌系统。

Step 1: Identify Source Material

步骤1：识别源材料

Accept any of:

CSS files (scan for repeated values)
Tailwind
```
tailwind.config.js
```
or
```
tailwind.config.ts
```
Figma variable exports (JSON)
Design descriptions ("primary blue is #2563eb, used for buttons and links")
Screenshots (extract approximate values)
Existing component code

支持以下任意来源：

CSS文件（扫描重复值）
Tailwind
```
tailwind.config.js
```
或
```
tailwind.config.ts
```
Figma变量导出文件（JSON格式）
设计描述文本（如“主蓝色为#2563eb，用于按钮和链接”）
截图（提取近似值）
现有组件代码

Step 2: Token Categories

步骤2：令牌分类

Extract tokens in this hierarchy:

按照以下层级提取令牌：

Primitive Tokens (raw values — never use directly in components)

Primitive Tokens（原始值——切勿在组件中直接使用）

color.blue.50 → #eff6ff
color.blue.500 → #3b82f6
color.blue.900 → #1e3a8a
space.1 → 4px
space.2 → 8px
font-size.sm → 14px
font-size.base → 16px
border-radius.sm → 4px
border-radius.md → 8px
duration.fast → 150ms
duration.base → 250ms

color.blue.50 → #eff6ff
color.blue.500 → #3b82f6
color.blue.900 → #1e3a8a
space.1 → 4px
space.2 → 8px
font-size.sm → 14px
font-size.base → 16px
border-radius.sm → 4px
border-radius.md → 8px
duration.fast → 150ms
duration.base → 250ms

Semantic Tokens (reference primitives — use these in components)

Semantic Tokens（引用原始值——在组件中使用此类令牌）

color.background.default → color.neutral.50
color.background.subtle → color.neutral.100
color.text.primary → color.neutral.900
color.text.secondary → color.neutral.500
color.text.disabled → color.neutral.300
color.border.default → color.neutral.200
color.interactive.primary → color.blue.600
color.interactive.primary.hover → color.blue.700
color.interactive.destructive → color.red.600
space.component.padding.sm → space.3
space.component.padding.md → space.4
space.layout.section → space.16

color.background.default → color.neutral.50
color.background.subtle → color.neutral.100
color.text.primary → color.neutral.900
color.text.secondary → color.neutral.500
color.text.disabled → color.neutral.300
color.border.default → color.neutral.200
color.interactive.primary → color.blue.600
color.interactive.primary.hover → color.blue.700
color.interactive.destructive → color.red.600
space.component.padding.sm → space.3
space.component.padding.md → space.4
space.layout.section → space.16

Component Tokens (specific overrides — use sparingly)

Component Tokens（特定覆盖值——谨慎使用）

button.height.md → 40px
button.padding.x → space.4
card.radius → border-radius.lg
input.border.color → color.border.default

button.height.md → 40px
button.padding.x → space.4
card.radius → border-radius.lg
input.border.color → color.border.default

Step 3: Output Formats

步骤3：输出格式

Always output all three formats:

始终输出以下三种格式：

CSS Custom Properties

css

/* primitives */
:root {
  --color-blue-500: #3b82f6;
  --space-4: 16px;
}

/* semantic */
:root {
  --color-interactive-primary: var(--color-blue-500);
  --space-component-padding-md: var(--space-4);
}

css

/* primitives */
:root {
  --color-blue-500: #3b82f6;
  --space-4: 16px;
}

/* semantic */
:root {
  --color-interactive-primary: var(--color-blue-500);
  --space-component-padding-md: var(--space-4);
}

Tailwind Config Extension

Tailwind配置扩展

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        'interactive-primary': 'var(--color-interactive-primary)',
        'text-primary': 'var(--color-text-primary)',
      },
      spacing: {
        'component-md': 'var(--space-component-padding-md)',
      }
    }
  }
}

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        'interactive-primary': 'var(--color-interactive-primary)',
        'text-primary': 'var(--color-text-primary)',
      },
      spacing: {
        'component-md': 'var(--space-component-padding-md)',
      }
    }
  }
}

Style Dictionary JSON (W3C Design Tokens format)

Style Dictionary JSON（W3C Design Tokens格式）

json

{
  "color": {
    "interactive": {
      "primary": {
        "$value": "{color.blue.500}",
        "$type": "color",
        "$description": "Primary interactive element color — buttons, links, focus rings"
      }
    }
  }
}

json

{
  "color": {
    "interactive": {
      "primary": {
        "$value": "{color.blue.500}",
        "$type": "color",
        "$description": "Primary interactive element color — buttons, links, focus rings"
      }
    }
  }
}

Consistency Audit

一致性审核

After extracting tokens, report:

Duplicate values: Same hex used with different names
Near-duplicates: Values within 10% of each other (e.g.,
```
#374151
```
and
```
#3f4451
```
)
Unmapped values: Hardcoded values in components that have no token
Unused tokens: Tokens defined but not referenced

提取令牌后，需报告以下内容：

重复值：同一十六进制值使用不同名称
近似重复值：数值差异在10%以内的值（如
```
#374151
```
和
```
#3f4451
```
）
未映射值：组件中未对应任何令牌的硬编码值
未使用令牌：已定义但未被引用的令牌

Naming Conventions

命名规范

Use kebab-case
Semantic tokens:
```
{category}.{property}.{variant}.{state}
```
No color names in semantic tokens (
```
interactive-primary
```
not
```
blue-button
```
)
States:
```
default
```
,
```
hover
```
,
```
active
```
,
```
disabled
```
,
```
focus
```
Scale:
```
xs
```
,
```
sm
```
,
```
md
```
,
```
lg
```
,
```
xl
```
,
```
2xl
```

使用短横线命名法（kebab-case）
语义令牌：
```
{category}.{property}.{variant}.{state}
```
语义令牌中不得包含颜色名称（如使用
```
interactive-primary
```
而非
```
blue-button
```
）
状态值：
```
default
```
、
```
hover
```
、
```
active
```
、
```
disabled
```
、
```
focus
```
尺寸等级：
```
xs
```
、
```
sm
```
、
```
md
```
、
```
lg
```
、
```
xl
```
、
```
2xl
```