design-token-extractor

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.