npm package: @itzcull/unocss-preset-tokens
Description: UnoCSS preset for semantic design tokens with comprehensive utility classes
Author: Will Cullen
Latest version: 1.0.1

# UnoCSS Preset Tokens

A UnoCSS preset for semantic design tokens, allowing you to apply different sets of color and dimension values for specific kinds of CSS properties.

## Features

- **Property-specific tokens**: Different token sets for backgrounds, text, borders, shadows, rings, and more
- **Granular control**: Apply specific spacing tokens to gaps, padding, margins, and other properties
- **Contextual sizing**: Different sizing tokens for widths, heights, containers, and components
- **CSS Variables**: Automatic CSS variable generation for all tokens
- **TypeScript support**: Full type safety and autocomplete for token configurations
- **TailwindCSS compatibility**: Comprehensive utility classes matching TailwindCSS patterns

## Installation

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

## Basic Usage

```typescript
import { presetTokens } from '@itzcull/unocss-preset-tokens'
// uno.config.ts
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetTokens({
      tokens: {
        colors: {
          background: {
            surface: '#ffffff',
            muted: '#f5f5f5',
            accent: '#0066cc'
          },
          text: {
            primary: '#000000',
            muted: '#666666',
            inverse: '#ffffff'
          }
        },
        spacing: {
          gap: {
            section: '4rem',
            card: '1.5rem',
            tight: '0.5rem'
          }
        },
        sizing: {
          width: {
            container: '72rem',
            card: '24rem',
            sidebar: '18rem'
          }
        }
      }
    })
  ]
})
```

```html
<!-- Use your semantic tokens in HTML -->
<div class="bg-surface text-primary gap-section w-container p-card">
  <h1 class="text-primary">Welcome</h1>
  <p class="text-muted">This uses semantic color tokens</p>
</div>
```

## Token Categories

### Colors

Property-specific color tokens allow you to define different color palettes for different CSS properties:

```
typescript
colors: {
  background: {
    surface: '#ffffff',
    muted: '#f5f5f5',
    accent: '#0066cc'
  },
  text: {
    primary: '#000000',
    muted: '#666666',
    link: '#0066cc'
  },
  border: {
    subtle: '#e5e5e5',
    strong: '#cccccc',
    focus: '#0066cc'
  },
  shadow: {
    subtle: 'rgba(0,0,0,0.05)',
    medium: 'rgba(0,0,0,0.15)'
  }
}
```

**Available color categories:**
- `background` → `bg-{token}` (e.g., `bg-surface`, `bg-accent`)
- `text` → `text-{token}` (e.g., `text-primary`, `text-muted`)
- `border` → `border-{token}` (e.g., `border-subtle`, `border-focus`)
- `shadow` → `shadow-{token}` (e.g., `shadow-subtle`)
- `ring` → `ring-{token}` (e.g., `ring-focus`)
- `fill` → `fill-{token}` (SVG fills)
- `stroke` → `stroke-{token}` (SVG strokes)

### Spacing

Define contextual spacing tokens for different spacing properties:

```
typescript
spacing: {
  gap: {
    tight: '0.5rem',
    normal: '1rem',
    section: '4rem'
  },
  padding: {
    card: '1.5rem',
    section: '4rem',
    page: '2rem'
  },
  margin: {
    section: '4rem',
    auto: 'auto'
  }
}
```

**Available spacing categories:**
- `gap` → `gap-{token}`, `gap-x-{token}`, `gap-y-{token}`
- `padding` → `p-{token}`, `px-{token}`, `py-{token}`, `pt-{token}`, etc.
- `margin` → `m-{token}`, `mx-{token}`, `my-{token}`, `mt-{token}`, etc.
- `inset` → `inset-{token}`, `top-{token}`, `right-{token}`, etc.
- `space` → `space-x-{token}`, `space-y-{token}`

### Sizing

Contextual sizing tokens for different sizing contexts:

```
typescript
sizing: {
  width: {
    container: '72rem',
    sidebar: '18rem',
    content: '42rem'
  },
  height: {
    header: '4rem',
    hero: '32rem'
  },
  size: {
    icon: '1.5rem',
    avatar: '3rem',
    button: '2.5rem'
  }
}
```

**Available sizing categories:**
- `width` → `w-{token}` (e.g., `w-container`, `w-sidebar`)
- `height` → `h-{token}` (e.g., `h-header`, `h-hero`)
- `size` → `size-{token}` (sets both width and height)
- `minWidth` → `min-w-{token}`
- `maxWidth` → `max-w-{token}`
- `minHeight` → `min-h-{token}`
- `maxHeight` → `max-h-{token}`
- `container` → `container-{token}`

### Other Token Categories

```
typescript
// Border tokens
border: {
  radius: {
    card: '0.5rem',
    button: '0.25rem'
  },
  width: {
    thin: '1px',
    thick: '2px'
  }
}

// Typography tokens
typography: {
  fontSize: {
    display: '3rem',
    heading: '2rem',
    body: '1rem'
  },
  fontWeight: {
    display: '700',
    heading: '600',
    body: '400'
  }
}

// Effect tokens
effects: {
  opacity: {
    overlay: '0.9',
    disabled: '0.5'
  },
  blur: {
    backdrop: '8px',
    subtle: '4px'
  }
}
```

## Configuration Options

```typescript
interface PresetTokensOptions {
  tokens?: TokenConfig
  prefix?: string // CSS class prefix (default: '')
  important?: boolean // Add !important to all rules (default: false)
  variablePrefix?: string // CSS variable prefix (default: 'tok')
  classPrefix?: string // CSS class prefix (default: '')
}
```

### CSS Variables

All tokens are automatically converted to CSS variables:

```css
:root {
  --tok-colors-background-surface: #ffffff;
  --tok-colors-text-primary: #000000;
  --tok-spacing-gap-section: 4rem;
  --tok-sizing-width-container: 72rem;
}
```

Utilities reference these variables:

```css
.bg-surface {
  background-color: var(--tok-colors-background-surface);
}

.gap-section {
  gap: var(--tok-spacing-gap-section);
}
```

### Opacity Support

Color tokens support opacity modifiers:

```html
<div class="bg-surface/80 text-primary/60">
  Semi-transparent background and text
</div>
```

### Arbitrary Values

You can still use arbitrary values when tokens don't fit:

```html
<div class="bg-[#ff0000] w-[42rem] p-[2.5rem]">
  Custom values in brackets
</div>
```

### Directional Support

Spacing tokens work with all directional variants:

```html
<div class="px-card py-section mt-auto">
  <!--
    px-card: horizontal padding using 'card' token
    py-section: vertical padding using 'section' token
    mt-auto: top margin using 'auto' token
  -->
</div>
```

## Default Utilities

This preset provides comprehensive utility classes that match TailwindCSS patterns:

- Layout utilities (flexbox, grid, positioning)
- Typography utilities (fonts, text sizing, line height)
- Color utilities (backgrounds, text, borders, shadows)
- Spacing utilities (padding, margin, gap)
- Sizing utilities (width, height, min/max)
- Effect utilities (opacity, blur, transforms)
- Advanced utilities (animations, filters, rings, dividers)

## TypeScript Support

Full TypeScript support with autocompletion:

```typescript
import type { TokenConfig } from '@itzcull/unocss-preset-tokens'

const tokens: TokenConfig = {
  colors: {
    background: {
      // TypeScript will provide autocompletion and validation
    }
  }
}
```

## Migration from Other Systems

### From Design Tokens
```typescript
// Your design tokens
const designTokens = {
  color: {
    background: {
      primary: '#ffffff'
    }
  }
}

// Map to preset tokens structure
presetTokens({
  tokens: {
    colors: {
      background: designTokens.color.background
    }
  }
})
```

### From Tailwind CSS
```
typescript
// Instead of using generic colors everywhere
"bg-gray-100 text-gray-900 border-gray-200"

// Use semantic tokens
"bg-surface text-primary border-subtle"

// Define the mapping in your tokens
tokens: {
  colors: {
    background: { surface: '#f5f5f5' },
    text: { primary: '#111827' },
    border: { subtle: '#e5e7eb' }
  }
}
```

## Examples

### Design System Setup
```typescript
export const designSystemTokens = {
  colors: {
    background: {
      app: '#ffffff',
      surface: '#f9fafb',
      overlay: '#00000080',
      success: '#10b981',
      warning: '#f59e0b',
      error: '#ef4444'
    },
    text: {
      primary: '#111827',
      secondary: '#6b7280',
      tertiary: '#9ca3af',
      inverse: '#ffffff',
      success: '#065f46',
      warning: '#92400e',
      error: '#991b1b'
    },
    border: {
      subtle: '#f3f4f6',
      default: '#d1d5db',
      strong: '#9ca3af',
      success: '#10b981',
      warning: '#f59e0b',
      error: '#ef4444'
    }
  },
  spacing: {
    gap: {
      xs: '0.5rem',
      sm: '1rem',
      md: '1.5rem',
      lg: '2rem',
      xl: '3rem'
    },
    padding: {
      component: '1rem',
      card: '1.5rem',
      section: '4rem',
      page: '2rem'
    }
  },
  sizing: {
    width: {
      sidebar: '16rem',
      content: '42rem',
      container: '72rem'
    },
    height: {
      header: '4rem',
      footer: '8rem'
    }
  }
}
```

## License

MIT