saltcat-design-system-unocss-preset

UnoCSS preset that integrates the saltcat design system with the Wind4 preset, providing a seamless way to use design tokens in your UnoCSS configuration with advanced features like automatic palette generation, easing functions, and accessibility support.

Features

• Design System Integration: Automatically converts saltcat design system tokens to UnoCSS theme configuration
• Wind4 Compatibility: Built on top of the popular @unocss/preset-wind for full utility coverage
• Flexible Configuration: Customizable prefix/postfix for design system tokens
• TypeScript Support: Full TypeScript definitions included
• Theme Support: Supports multiple themes from the design system
• Automatic Palette Generation: Generate color palettes using saltcat-color-palette (optional)
• Easing Functions: Add smooth animation easing using saltcat-easing (optional)
• Accessibility Features: Built-in contrast checking and WCAG compliance (optional)
• Multi-Theme Support: Light/dark mode and custom theme variants

Installation

npm install saltcat-design-system-unocss-preset

Peer Dependencies

This preset requires the following peer dependencies:

npm install unocss@^66.1.2 saltcat-design-system@^0.2.0

Optional Dependencies

For enhanced features, you can install optional dependencies:

# For automatic color palette generation
npm install saltcat-color-palette@^0.3.0

# For easing functions in animations
npm install saltcat-easing@^0.2.1

Usage

Basic Usage

import { defineConfig } from 'unocss'
import { presetDesignSystem } from 'saltcat-design-system-unocss-preset'

export default defineConfig({
  presets: [
    presetDesignSystem()
  ]
})

With Design System Configuration

import { defineConfig } from 'unocss'
import { presetDesignSystem } from 'saltcat-design-system-unocss-preset'
import DesignSystem from 'saltcat-design-system'

const ds = new DesignSystem({
  tokens: {
    colors: {
      primary: '#0066cc',
      secondary: '#6c757d'
    },
    spacing: {
      small: '0.5rem',
      medium: '1rem',
      large: '2rem'
    }
  }
})

export default defineConfig({
  presets: [
    presetDesignSystem({
      designSystem: ds,
      prefix: 'ds',
      postfix: ''
    })
  ]
})

Advanced Configuration

import { defineConfig } from 'unocss'
import { presetDesignSystem } from 'saltcat-design-system-unocss-preset'
import DesignSystem from 'saltcat-design-system'

const designSystem = new DesignSystem({
  // Your design system configuration
})

export default defineConfig({
  presets: [
    presetDesignSystem({
      designSystem,
      prefix: 'my',        // Custom prefix for tokens
      postfix: '-custom',  // Custom postfix for tokens
      windOptions: {       // Options passed to @unocss/preset-wind
        dark: 'class'      // Enable dark mode with class strategy
      },
      palette: {           // Enable automatic palette generation
        enabled: true,
        algorithm: 'analogous',
        shades: 9
      },
      easing: {            // Enable easing functions
        enabled: true,
        functions: ['ease-in-out', 'ease-in', 'ease-out']
      },
      accessibility: {     // Enable accessibility features
        enabled: true,
        minContrastRatio: 4.5
      },
      theme: {             // Enable multi-theme support
        enabled: true,
        themes: ['light', 'dark'],
        defaultTheme: 'light'
      }
    })
  ]
})

API

presetDesignSystem(options?)

Creates an UnoCSS preset that combines the Wind4 preset with design system tokens and optional advanced features.

Parameters

• options (optional): Configuration object
  • designSystem (optional): DesignSystem instance from saltcat-design-system
  • prefix (optional, default: 'ds'): Prefix for design system tokens
  • postfix (optional, default: ''): Postfix for design system tokens
  • windOptions (optional): Options to pass to the underlying Wind preset
  • palette (optional): Palette generation options
    • enabled (boolean, default: false): Enable automatic palette generation
    • shades (number, default: 9): Number of shades to generate per color
    • algorithm (string, default: 'analogous'): Palette generation algorithm
  • easing (optional): Easing function options
    • enabled (boolean, default: false): Enable easing functions
    • functions (string[], default: ['ease-in-out', 'ease-in', 'ease-out']): Easing functions to include
  • accessibility (optional): Accessibility options
    • enabled (boolean, default: false): Enable accessibility features
    • minContrastRatio (number, default: 4.5): Minimum contrast ratio for WCAG AA compliance
  • theme (optional): Theme options
    • enabled (boolean, default: false): Enable multiple theme support
    • defaultTheme (string, default: 'light'): Default theme name
    • themes (string[], default: ['light', 'dark']): Available themes

Returns

Promise

Example

const preset = presetDesignSystem({
  designSystem: myDesignSystem,
  prefix: 'brand',
  postfix: '-token'
})

Configuration Options

Design System Integration

When a designSystem instance is provided, the preset will:

• Extract colors, typography, spacing, and other design tokens
• Convert them to UnoCSS theme format
• Merge with the Wind4 preset theme
• Make tokens available as CSS variables and utility classes

Token Mapping

Design system tokens are mapped to UnoCSS theme categories:

• colors.* → theme.colors
• fontFamily.* → theme.fontFamily
• fontSize.* → theme.fontSize
• spacing.* → theme.spacing
• borderRadius.* → theme.borderRadius
• boxShadow.* → theme.boxShadow
• borderWidth.* → theme.borderWidth
• lineHeight.* → theme.lineHeight
• letterSpacing.* → theme.letterSpacing

Prefix/Postfix Customization

// With prefix: 'brand' and postfix: '-v2'
presetDesignSystem({
  designSystem: ds,
  prefix: 'brand',
  postfix: '-v2'
})

// Results in tokens like:
// brand-primary-v2, brand-secondary-v2, etc.

Advanced Features

Palette Generation

When palette.enabled is true, the preset will automatically generate color palettes for each color in your design system:

presetDesignSystem({
  designSystem: ds,
  palette: {
    enabled: true,
    algorithm: 'complementary', // 'analogous', 'complementary', 'triadic', 'split-complementary'
    shades: 12 // Number of shades to generate
  }
})

This adds a palettes object to your theme containing generated color variations.

Easing Functions

When easing.enabled is true, the preset includes easing functions for smooth animations:

presetDesignSystem({
  designSystem: ds,
  easing: {
    enabled: true,
    functions: ['ease-in-out', 'ease-in', 'ease-out', 'ease-elastic']
  }
})

This adds an easing object to your theme with CSS easing function values.

Accessibility Features

When accessibility.enabled is true, the preset performs contrast checking:

presetDesignSystem({
  designSystem: ds,
  accessibility: {
    enabled: true,
    minContrastRatio: 4.5 // WCAG AA standard
  }
})

This adds an accessibility object with contrast compliance information.

Multi-Theme Support

When theme.enabled is true, the preset supports multiple themes:

presetDesignSystem({
  designSystem: ds,
  theme: {
    enabled: true,
    themes: ['light', 'dark', 'high-contrast'],
    defaultTheme: 'light'
  }
})

This adds themes and defaultTheme to your theme configuration.

Dependencies

• saltcat-design-system: Core design system library
• @unocss/preset-wind: Underlying Wind4 preset
• saltcat-color-palette (optional): Automatic color palette generation
• saltcat-easing (optional): Easing functions for animations

Requirements

• Node.js >= 14.0.0
• UnoCSS >= 66.1.2
• saltcat-design-system >= 0.2.0
• saltcat-color-palette >= 0.3.0 (optional)
• saltcat-easing >= 0.2.1 (optional)

License

MIT