npm package: @itzcull/tokens-core
Description: Core design tokens for UnoCSS
Author: Will Cullen
Latest version: 0.0.2

# @itzcull/tokens-core

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

## Installation

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

## Usage

### Basic Setup

```ts
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

```ts
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:

```css
: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:

```html
<!-- 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:

```html
<!-- 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:

```html
<!-- 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

```html
<!-- 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

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

### W3C DTCG Dimension Format

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

### Simple String Values

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

## Token References

Use curly brace syntax to reference other tokens:

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

## Configuration Options

```ts
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

```ts
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