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

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

Basic Usage

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'
          }
        }
      }
    })
  ]
})

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

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:

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

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

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

Opacity Support

Color tokens support opacity modifiers:

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

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

Directional Support

Spacing tokens work with all directional variants:

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

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

// 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

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