@itzcull/tokens-core

A powerful UnoCSS preset generator that converts Design Tokens Format compliant tokens into comprehensive Tailwind CSS-like utility classes.

Installation

npm install @itzcull/tokens-core
# or
pnpm add @itzcull/tokens-core
# or
yarn add @itzcull/tokens-core

Usage

Basic Setup

import { defineDesignTokenPreset } from '@itzcull/tokens-core'
import { defineConfig } from 'unocss'

// Define your design tokens following Design Tokens Format spec
const tokens = {
  color: {
    primary: {
      $type: 'color',
      $value: '#3b82f6'
    },
    secondary: {
      $type: 'color',
      $value: '{color.primary}' // Token reference
    }
  },
  spacing: {
    sm: {
      $type: 'dimension',
      $value: '1rem'
    },
    md: {
      $type: 'dimension',
      $value: '1.5rem'
    }
  },
  typography: {
    'font-sans': {
      $type: 'fontFamily',
      $value: ['Inter', 'system-ui', 'sans-serif']
    }
  }
}

export default defineConfig({
  presets: [
    defineDesignTokenPreset(tokens)({
      prefix: 'dt' // Optional: adds 'dt-' prefix to CSS variables
    })
  ]
})

Advanced Usage with Token References

const tokens = {
  colors: {
    palette: {
      '$type': 'color',
      'blue-500': {
        $value: '#3b82f6'
      }
    },
    semantic: {
      $type: 'color',
      primary: {
        $value: '{colors.palette.blue-500}'
      }
    }
  },
  spacing: {
    $type: 'dimension',
    base: {
      $value: {
        value: 16,
        unit: 'px'
      }
    },
    large: {
      $value: '{spacing.base}'
    }
  }
}

Generated CSS Variables

The preset automatically generates CSS variables from your tokens:

:root {
  --colors-primary: rgb(51, 102, 204);
  --colors-secondary: #64748b;
  --spacing-small: 8px;
  --spacing-medium: 1rem;
  --typography-fontFamily-sans: "Inter", system-ui, sans-serif;
  --typography-fontSize-base: 16px;
}

Generated Utility Classes

Color Utilities

From color tokens, the preset generates:

<!-- Text colors -->
<div class="text-colors-primary">Primary text</div>
<div class="text-primary">Primary text (short form)</div>

<!-- Background colors -->
<div class="bg-colors-primary">Primary background</div>
<div class="bg-primary">Primary background (short form)</div>

<!-- Border colors -->
<div class="border-colors-primary">Primary border</div>
<div class="border-primary">Primary border (short form)</div>

Spacing Utilities

From spacing tokens, the preset generates:

<!-- Padding -->
<div class="p-spacing-small">Small padding</div>
<div class="p-small">Small padding (short form)</div>

<!-- Margin -->
<div class="m-spacing-medium">Medium margin</div>
<div class="m-medium">Medium margin (short form)</div>

<!-- Gap -->
<div class="gap-spacing-large">Large gap</div>
<div class="gap-large">Large gap (short form)</div>

Typography Utilities

From typography tokens, the preset generates:

<!-- Font family -->
<div class="font-typography-fontFamily-sans">Sans font</div>
<div class="font-sans">Sans font (short form)</div>

<!-- Font size -->
<div class="text-typography-fontSize-base">Base font size</div>
<div class="text-base">Base font size (short form)</div>

<!-- Font weight -->
<div class="font-typography-fontWeight-bold">Bold font</div>
<div class="font-bold">Bold font (short form)</div>

Other Utilities

<!-- Border radius -->
<div class="rounded-borderRadius-medium">Medium border radius</div>
<div class="rounded-medium">Medium border radius (short form)</div>

<!-- Box shadow -->
<div class="shadow-shadow-elevated">Elevated shadow</div>
<div class="shadow-elevated">Elevated shadow (short form)</div>

<!-- Duration/Animation -->
<div class="duration-duration-fast">Fast duration</div>
<div class="transition-fast">Fast transition (short form)</div>

<!-- Opacity -->
<div class="opacity-opacity-subtle">Subtle opacity</div>
<div class="opacity-subtle">Subtle opacity (short form)</div>

Supported Token Types

The preset supports all W3C DTCG token types:

Basic Types

• color: Generates text, background, and border utilities
• dimension: Used for spacing, font sizes, border radius, etc.
• fontFamily: Generates font-family utilities
• fontWeight: Generates font-weight utilities
• number: Used for line-height, opacity, etc.
• duration: Generates animation and transition duration utilities
• cubicBezier: Generates timing function utilities

Composite Types

• shadow: Generates box-shadow utilities
• border: Generates comprehensive border utilities
• typography: Generates combined typography utilities
• transition: Generates transition utilities
• gradient: Generates gradient utilities

Token Value Formats

W3C DTCG Color Format

{
  "primary": {
    "$type": "color",
    "$value": {
      "colorSpace": "srgb",
      "components": [0.2, 0.4, 0.8],
      "alpha": 0.9
    }
  }
}

W3C DTCG Dimension Format

{
  "spacing": {
    "$type": "dimension",
    "$value": {
      "value": 16,
      "unit": "px"
    }
  }
}

Simple String Values

{
  "color": {
    "$type": "color",
    "$value": "#3b82f6"
  }
}

Token References

Use curly brace syntax to reference other tokens:

{
  "base": {
    "$type": "color",
    "$value": "#3b82f6"
  },
  "primary": {
    "$type": "color",
    "$value": "{base}"
  }
}

Configuration Options

interface PresetDesignTokensOptions<T extends JSONTokenTree> {
  tokens: T // Your design tokens object
  variablePrefix?: string // Prefix for CSS variables (default: '')
  exposePrimitives?: boolean // Whether to expose primitive tokens (future feature)
}

TypeScript Support

The preset is fully typed and works with TypeScript out of the box. The JSONTokenTree type ensures your tokens follow the W3C DTCG specification.

Examples

Complete Design System

const designSystem = {
  colors: {
    $type: 'color',
    neutral: {
      50: { $value: '#fafafa' },
      500: { $value: '#737373' },
      900: { $value: '#171717' }
    },
    primary: {
      500: { $value: '#3b82f6' }
    }
  },
  spacing: {
    $type: 'dimension',
    xs: { $value: { value: 4, unit: 'px' } },
    sm: { $value: { value: 8, unit: 'px' } },
    md: { $value: { value: 16, unit: 'px' } },
    lg: { $value: { value: 24, unit: 'px' } }
  },
  typography: {
    fontFamily: {
      $type: 'fontFamily',
      sans: { $value: ['Inter', 'system-ui'] },
      mono: { $value: ['Fira Code', 'monospace'] }
    },
    fontSize: {
      $type: 'dimension',
      sm: { $value: { value: 14, unit: 'px' } },
      base: { $value: { value: 16, unit: 'px' } },
      lg: { $value: { value: 18, unit: 'px' } }
    }
  }
}

This generates utilities like:

• text-primary-500, bg-neutral-50, border-neutral-900
• p-md, m-lg, gap-sm
• font-sans, font-mono
• text-base, text-lg

License

MIT