Extracting Design Tokens

Learn how to extract design tokens and component usage from CSS files using css-token-extractor

Overview

This project uses JSON files generated by the css-token-extractor npm package to visualize design tokens and their relationships across components.

Installation

Install the css-token-extractor package:

npm install -g css-token-extractor

Or use it directly with npx without installation:

npx css-token-extractor [options]

Basic Usage

Extract design tokens from your CSS files:

css-token-extractor \
  --input ./path/to/your/styles.css \
  --output ./design-tokens.json

Expected Output Format

The extractor generates JSON files with the following structure:

{
  "--token-name": {
    "value": " #ffffff",
    "type": "color",
    "usedIn": [
      "component-class-1",
      "component-class-2"
    ]
  },
  "--token-reference": {
    "refersTo": [
      "--token-name"
    ],
    "usedIn": [
      "component-class-3"
    ]
  }
}
Key fields:
  • value: The actual CSS value (for primitive tokens)
  • type: Token type (color, dimension, typography, etc.)
  • refersTo: Array of tokens this token references (for alias tokens)
  • usedIn: Array of CSS class names where the token is used

Integration Steps

1. Extract Tokens

Run the extractor on your design system CSS files:

css-token-extractor \
  --input ./design-system/styles.css \
  --output ./my-design-tokens.json

2. Validate Output

Ensure your JSON file matches the expected format with:

  • Token names as top-level keys
  • Either value + type OR refersTo
  • usedIn array with component class names

3. Add to Assets Directory

Copy your generated JSON file to the assets directory:

cp my-design-tokens.json ./assets/

4. Update Service Configuration

Add your design system to lib/design-tokens-service.ts:

case 'my-design-system':
  tokens = await import('@/assets/my-design-tokens.json');
  break;

5. Create Route Page

Create a new route at app/design-systems/my-design-system/page.tsx:

import DesignSystemFlow from "@/components/flow/design-system-flow";

export default function MyDesignSystemPage() {
  return <DesignSystemFlow designSystem="my-design-system" />;
}

Advanced Configuration

For additional options and configuration, refer to the css-token-extractor documentation.

Note: The --input flag accepts a single CSS file path. If you need to extract from multiple files, you can either:

  • Concatenate your CSS files first
  • Import all your styles into a single entry CSS file
  • Run the extractor multiple times and merge the JSON outputs

Example: Carbon Design System

Here's how the Carbon Design System tokens were extracted:

css-token-extractor \
  --input ./node_modules/@carbon/styles/css \
  --output ./assets/carbon-design-tokens.json

This generated tokens like --cds-layer, --cds-field, etc., along with their usage in components like cds--btn, cds--modal.

Troubleshooting

Missing Component Usage

Ensure the extractor is configured to capture component usage data. The visualizer relies on the usedIn field in the JSON to show relationships between tokens and components.

Invalid JSON Format

Validate your JSON structure. Each token must have either value and type, or refersTo for alias tokens.

No Tokens Found

Check that your CSS uses CSS custom properties (variables) in the format --token-name. The extractor only works with CSS variables.

Resources