design-token-extractor

name	design-token-extractor
description	Extracts design tokens from images and generates CSS custom properties, atomic utility classes (Tailwind-style), and platform-specific formats following W3C standards and modern CSS best practices.
version	0.2.0
license	Complete terms in LICENSE.txt

Overview

This skill automates the extraction of design tokens from images and mockups, converting them into standards-compliant formats including W3C DTCG JSON, CSS custom properties, SCSS variables, and comprehensive atomic utility classes (Tailwind-style). It generates modern, accessible design systems with cascade layers, container queries, responsive variants, and state management.

New in v0.2.0: Comprehensive atomic utility class generation with Tailwind-style naming, including color, spacing (with logical properties), typography, and layout utilities, plus full support for container query variants, state variants (hover/focus/active), and dark mode.

When to Use This Skill

Invoke this skill when you need to:

• Extract design tokens from UI mockups, screenshots, or design files
• Convert visual design elements into CSS custom properties or SCSS variables
• Generate atomic utility classes (Tailwind-style) from design tokens
• Create utility-first design systems with comprehensive responsive and state variants
• Generate W3C DTCG-compliant token JSON from design artifacts
• Create cross-platform design tokens (web, iOS, Android)
• Validate existing tokens against W3C specifications
• Implement design systems with modern CSS features (cascade layers, container queries, logical properties)

Workflow

1. Image Analysis and Token Identification

Action: When the user provides an image or design mockup, analyze and identify token categories.

Token Categories:

• Colors (primary, secondary, neutral palettes with semantic roles)
• Typography (font families, sizes, weights, line-heights using scale ratios)
• Spacing (mathematical progression scales: 0.25rem, 0.5rem, 1rem, 1.5rem, 2rem)
• Dimensions (border radius, shadows, dimensional properties)
• Motion (animation durations and easing functions if present)

2. Token Extraction

Action: Extract tokens following W3C Design Tokens Community Group standards.

Extraction Process:

• Use semantic, hierarchical naming with kebab-case
• Apply mathematical progressions for scales (1.25x, 1.5x, 2x)
• Structure using cascade layers (@layer reset, tokens, components, utilities)
• Ensure WCAG 2.2 compliance (4.5:1 contrast for normal text, 3:1 for large text)

3. Format Selection

Prompt for Output Format:

Ask the user which format to generate (if not specified):

• W3C JSON - Design Tokens Community Group specification format
• CSS - CSS custom properties with cascade layers
• CSS (Full) - CSS with cascade layers + generated atomic utilities
• Utilities - Standalone atomic utility classes (Tailwind-style)
• SCSS - SCSS variables and mixins
• iOS - Swift/UIKit format
• Android - Kotlin/XML resources

New Utility Formats:

• utilities - Comprehensive Tailwind-style atomic utilities (standalone file)
• css-layers-full - Complete design system with tokens AND generated utilities

Both utility formats include:

• Color utilities (text, bg, border, fill, stroke)
• Spacing utilities with logical properties (padding, margin, gap)
• Typography utilities (font family, size, weight, line-height)
• Layout utilities (border-radius, shadows, dimensions)
• Container query variants (sm, md, lg, xl breakpoints)
• State variants (hover, focus, active)
• Dark mode variants
• Accessibility variants (reduced-motion, forced-colors)

4. Output Generation

Action: Generate output using appropriate templates with variable substitution.

Default Output Location: src/styles/ (unless the user specifies a different path)

Templates Available:

• templates/w3c-tokens.template.json - W3C DTCG format
• templates/css-variables.template.css - CSS custom properties
• templates/css-layers.template.css - Cascade layers implementation
• templates/documentation.template.md - Token documentation

Variable Substitution:

• {{TOKEN_NAME}} - Token identifier
• {{TOKEN_VALUE}} - Token value
• {{TOKEN_TYPE}} - Token type (color, dimension, etc.)
• {{TOKEN_DESCRIPTION}} - Token description
• {{COLOR_PRIMARY_500}}, {{SPACING_MD}}, etc. - Specific token values

5. Validation

Action: Validate generated tokens against W3C DTCG specification.

Execute Validation Script:

python scripts/validate_tokens.py --input tokens.json [--strict]

Validation Checks:

• Required properties ($value, $type) present
• Valid token types (color, dimension, fontFamily, etc.)
• Proper alias token references
• Accessibility compliance (contrast ratios, motion preferences)

Error Handling:

• Report specific validation errors
• Suggest corrections
• Re-validate after fixes

6. Load References (As Needed)

Action: Load reference documentation only when detailed specifications are needed.

When to Load:

• User asks about W3C token format or validation errors → load references/w3c-dtcg-spec.md
• User needs CSS best practices or modern features → load references/css-standards.md
• User asks about accessibility or WCAG compliance → load references/accessibility-guidelines.md

Token Extraction Guidelines

Extract Design Elements

Follow W3C token categories:

• Colors: Primary, secondary, neutral palettes with semantic roles
• Typography: Font families, sizes, weights, line-heights using scale ratios (1.25x, 1.5x)
• Spacing: Mathematical progression scales (0.25rem, 0.5rem, 1rem, 1.5rem, 2rem)
• Dimensions: Border radius, shadows, and other dimensional properties
• Motion: Animation durations and easing functions if present

Token Organization

Structure using cascade layers (@layer reset, tokens, components, utilities). For detailed CSS standards, load references/css-standards.md.

Responsive Tokens

• Use container query units (cqi, cqb) for intrinsic sizing
• Create fluid typography: clamp(1rem, 2.5cqi, 1.5rem)
• Define breakpoint-agnostic spacing scales

Accessibility Requirements

Ensure WCAG 2.2 compliance:

• 4.5:1 contrast for normal text, 3:1 for large text
• Focus indicators meet 3:1 contrast against adjacent colors
• Motion tokens respect prefers-reduced-motion

For details, load references/accessibility-guidelines.md.

Using Bundled Resources

Scripts

Execute Python scripts for deterministic tasks. All output defaults to src/styles/ unless otherwise specified.

extract_tokens.py - Extract tokens from image analysis

# Default output to src/styles/tokens.json
python scripts/extract_tokens.py --input-image <path> --output src/styles/tokens.json

transform_tokens.py - Transform between formats (JSON → CSS/SCSS/iOS/Android/Utilities)

# Generate CSS custom properties (default to src/styles/)
python scripts/transform_tokens.py --input tokens.json --format css --output src/styles/tokens.css

# Generate standalone atomic utilities (default to src/styles/)
python scripts/transform_tokens.py --input tokens.json --format utilities --output src/styles/utilities.css

# Generate complete design system (tokens + utilities, default to src/styles/)
python scripts/transform_tokens.py --input tokens.json --format css-layers-full --output src/styles/design-system.css

generate_utilities.py - Generate atomic utility classes from tokens

# Generate utilities with default configuration (default to src/styles/)
python scripts/generate_utilities.py --input tokens.json --output src/styles/utilities.css

# Generate utilities with custom configuration
python scripts/generate_utilities.py --input tokens.json --output src/styles/utilities.css --config config.json

validate_tokens.py - Validate against W3C DTCG specification

python scripts/validate_tokens.py --input tokens.json [--strict]

Templates

Generate consistent output using templates with {{VARIABLE}} substitution:

• templates/w3c-tokens.template.json - W3C DTCG format
• templates/css-variables.template.css - CSS custom properties
• templates/css-layers.template.css - Cascade layers implementation
• templates/documentation.template.md - Token documentation

Common variables: {{TOKEN_NAME}}, {{TOKEN_VALUE}}, {{TOKEN_TYPE}}, {{TOKEN_DESCRIPTION}}, {{COLOR_PRIMARY_500}}, {{SPACING_MD}}, etc.

References

Load reference files when detailed information is needed:

• references/w3c-dtcg-spec.md - W3C Design Tokens specification (~1k words)
  • Search for: $value, $type, composite tokens, alias tokens
• references/css-standards.md - Modern CSS features (~1.3k words)
  • Search for: @layer, @container, logical properties, cascade layers
• references/accessibility-guidelines.md - WCAG 2.2 compliance (~1.3k words)
  • Search for: contrast ratio, focus indicators, prefers-reduced-motion

When to load references:

• User asks about W3C token format or validation errors → load w3c-dtcg-spec.md
• User needs CSS best practices or modern features → load css-standards.md
• User asks about accessibility or WCAG compliance → load accessibility-guidelines.md

Atomic Utility Class Generation

Overview

The skill generates comprehensive Tailwind-style atomic utility classes from extracted design tokens. These utilities enable rapid prototyping and utility-first development with full support for responsive variants, state management, and accessibility.

Generated Utility Categories

Color Utilities

Text Colors:

.text-primary-500 { color: var(--color-primary-500); }
.text-neutral-900 { color: var(--color-neutral-900); }

Background Colors:

.bg-surface-elevated { background-color: var(--color-surface-elevated); }
.bg-primary-500 { background-color: var(--color-primary-500); }

Border Colors:

.border-accent-600 { border-color: var(--color-accent-600); }

SVG Colors:

.fill-primary-500 { fill: var(--color-primary-500); }
.stroke-neutral-900 { stroke: var(--color-neutral-900); }

Spacing Utilities (Logical Properties)

Padding:

.p-md { padding: var(--spacing-scale-md); }
.px-lg { padding-inline: var(--spacing-scale-lg); }  /* horizontal */
.py-sm { padding-block: var(--spacing-scale-sm); }   /* vertical */
.pt-xs { padding-block-start: var(--spacing-scale-xs); }  /* top */

Margin:

.m-md { margin: var(--spacing-scale-md); }
.mx-auto { margin-inline: auto; }  /* center horizontally */
.my-lg { margin-block: var(--spacing-scale-lg); }

Gap (for Grid/Flexbox):

.gap-md { gap: var(--spacing-scale-md); }
.gap-x-sm { column-gap: var(--spacing-scale-sm); }
.gap-y-lg { row-gap: var(--spacing-scale-lg); }

Typography Utilities

Font Family:

.font-display { font-family: var(--font-family-display); }
.font-body { font-family: var(--font-family-body); }

Font Size:

.text-xl { font-size: var(--font-size-xl); }
.text-base { font-size: var(--font-size-base); }

Font Weight:

.font-bold { font-weight: var(--font-weight-bold); }
.font-medium { font-weight: var(--font-weight-medium); }

Line Height:

.leading-tight { line-height: var(--line-height-tight); }
.leading-relaxed { line-height: var(--line-height-relaxed); }

Layout Utilities

Border Radius:

.rounded-md { border-radius: var(--border-radius-md); }
.rounded-full { border-radius: var(--border-radius-full); }

Shadows:

.shadow-md { box-shadow: var(--shadow-md); }
.shadow-elevated { box-shadow: var(--shadow-elevated); }

Utility Variants

Container Query Variants

Apply utilities at specific container sizes (responsive design):

<div class="text-base md:text-lg lg:text-xl">
  Text that grows with container size
</div>

<div class="p-sm md:p-md lg:p-lg">
  Padding that increases at larger container sizes
</div>

Breakpoints:

• sm: - 640px
• md: - 768px
• lg: - 1024px
• xl: - 1280px

State Variants

Hover:

<button class="bg-primary-500 hover:bg-primary-600">
  Button with hover state
</button>

<a class="text-neutral-700 hover:text-primary-500">
  Link with hover color
</a>

Focus:

<input class="outline-neutral-300 focus:outline-primary-500">

<button class="focus:bg-primary-700">
  Button with focus state
</button>

Active:

<button class="bg-primary-500 active:bg-primary-700">
  Button with active/pressed state
</button>

Dark Mode Variants

<div class="bg-white dark:bg-neutral-900
            text-neutral-900 dark:text-neutral-100">
  Content that adapts to dark mode
</div>

<p class="text-neutral-700 dark:text-neutral-300">
  Body text with dark mode support
</p>

Usage Examples

Utility-First Card Component

<article class="bg-white dark:bg-neutral-800
                p-lg rounded-lg shadow-md
                border border-neutral-200 dark:border-neutral-700">
  <h2 class="font-display text-2xl font-bold
             text-neutral-900 dark:text-white
             mb-md">
    Card Title
  </h2>
  <p class="text-base leading-relaxed
            text-neutral-700 dark:text-neutral-300
            mb-lg">
    Card content with proper spacing and typography.
  </p>
  <button class="px-lg py-md
                 bg-primary-600 hover:bg-primary-700 active:scale-95
                 text-white rounded-sm font-semibold
                 focus:outline-accent-500">
    Action Button
  </button>
</article>

Responsive Grid Layout

<div class="grid gap-md md:gap-lg
            grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  <div class="p-md bg-neutral-50 dark:bg-neutral-800 rounded-md">
    Grid Item 1
  </div>
  <div class="p-md bg-neutral-50 dark:bg-neutral-800 rounded-md">
    Grid Item 2
  </div>
  <div class="p-md bg-neutral-50 dark:bg-neutral-800 rounded-md">
    Grid Item 3
  </div>
</div>

Configuration Options

Customize utility generation with a config JSON file:

{
  "categories": ["colors", "spacing", "typography", "layout"],
  "variants": ["container", "state", "dark-mode"],
  "prefix": ""
}

Configuration Properties:

• categories - Which utility types to generate (array)
• variants - Which variants to include (array)
• prefix - Optional prefix for all utilities (string, e.g., "tw-")

Example with custom configuration:

python scripts/generate_utilities.py \
  --input tokens.json \
  --output utilities.css \
  --config custom-config.json

Accessibility Features

All generated utilities include automatic accessibility support:

• Reduced Motion: Respects prefers-reduced-motion preference
• Forced Colors: Adapts to high contrast mode
• Dark Mode: Supports prefers-color-scheme: dark
• Logical Properties: Better i18n support (RTL languages)
• Focus Indicators: WCAG-compliant focus states

Modern CSS Features

Generated utilities leverage modern CSS:

• Cascade Layers: Organized with @layer utilities.colors, etc.
• Container Queries: Responsive variants based on container size
• Logical Properties: padding-inline, margin-block for better i18n
• CSS Custom Properties: All values reference design tokens

Browser Support

Target Browsers:

• Chrome/Edge: 88+ (container queries)
• Firefox: 110+
• Safari: 16+

Progressive Enhancement:

• Base utilities work in all browsers with custom property support
• Container query variants gracefully degrade on older browsers

Decision Tree

User provides image/mockup
    ↓
Extract tokens (colors, typography, spacing, dimensions, motion)
    ↓
Format specified?
    ├─ No  → Ask: W3C JSON, CSS, CSS (Full), Utilities, SCSS, iOS, Android?
    └─ Yes → Continue
        ↓
Utility generation requested?
    ├─ Yes → Generate utilities (standalone or with tokens)
    │         ├─ Format: utilities → Standalone atomic utilities
    │         └─ Format: css-layers-full → Tokens + utilities
    └─ No  → Standard token transformation
        ↓
Select template and generate output to src/styles/ (or user-specified path)
    ↓
Validate with validate_tokens.py (if JSON format)
    ↓
Validation passes?
    ├─ Yes → Deliver output with documentation
    └─ No  → Fix errors, re-validate

Naming Conventions

Use semantic, hierarchical naming with kebab-case:

• Colors: --color-{role}-{variant} → --color-primary-500, --color-text-primary
• Typography: --font-{property}-{size} → --font-size-lg, --font-weight-bold
• Spacing: --spacing-{scale}-{size} → --spacing-scale-md, --spacing-fluid-sm
• Dimensions: --{element}-{property} → --border-radius-sm, --shadow-md

Best Practices

1. Semantic naming - Use role-based names (primary/secondary) over descriptive (blue/red)
2. Scale consistency - Use mathematical progressions (1.25x, 1.5x, 2x)
3. Cross-platform - Ensure tokens work across web, mobile, and design tools
4. Accessibility first - Validate contrast ratios and motion preferences
5. Modern CSS - Leverage cascade layers, container queries, logical properties
6. W3C compliance - Follow Design Tokens Community Group specification

Generate modern, standards-compliant tokens that balance cutting-edge CSS features with cross-platform compatibility and accessibility.