npm package: @itzcull/tokens-brainwave
Description: UnoCSS preset for Untitled UI (Brainwave) design system tokens
Author: Will Cullen
Latest version: 0.0.2

# @itzcull/tokens-brainwave

A comprehensive UnoCSS preset implementing the **Untitled UI** design system (Brainwave) tokens. This package provides a complete set of design tokens extracted from Figma, including colors, typography, spacing, shadows, and more.

## Features

- 🎨 **Complete Color System** - Semantic colors, brand colors, and utility colors
- 📝 **Typography Scale** - Display, text, and utility typography tokens
- 📏 **Spacing System** - Consistent spacing scale for layouts
- 🎯 **Border Radius** - Rounded corner tokens for components
- 🌟 **Shadow System** - Elevation and depth with consistent shadows
- 📱 **Responsive Breakpoints** - Mobile-first responsive design
- 🔧 **Configurable** - Customizable prefix and breakpoints
- 🧩 **CSS Variables** - Runtime theming support

## Installation

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

## Usage

### UnoCSS Configuration

```typescript
import { presetBrainwave } from '@itzcull/tokens-brainwave'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetBrainwave({
      // Optional configuration
      prefix: 'bw', // CSS variable prefix (default: 'bw')
      preflight: true, // Include CSS reset (default: true)
      breakpoints: { // Custom breakpoints (optional)
        'sm': '480px',
        'md': '768px',
        'lg': '1024px',
        'xl': '1280px',
        '2xl': '1536px',
      },
    }),
  ],
})
```

### Using Design Tokens

The preset generates utility classes for all design tokens:

#### Colors
```html
<!-- Background colors -->
<div class="bg-brand-600">Brand background</div>
<div class="bg-success-50">Success background</div>
<div class="bg-gray-100">Neutral background</div>

<!-- Text colors -->
<p class="text-primary">Primary text</p>
<p class="text-brand-600">Brand text</p>
<p class="text-error-600">Error text</p>

<!-- Border colors -->
<div class="border border-gray-200">Bordered element</div>
```

#### Typography
```html
<!-- Typography scales -->
<h1 class="text-display-xl">Display Extra Large</h1>
<h2 class="text-display-sm">Display Small</h2>
<p class="text-text-lg">Large text</p>
<span class="text-text-sm">Small text</span>

<!-- Font weights -->
<p class="font-medium">Medium weight</p>
<p class="font-semibold">Semibold weight</p>
```

#### Spacing
```html
<!-- Padding -->
<div class="p-lg">Large padding</div>
<div class="px-xl py-md">Horizontal XL, Vertical MD</div>

<!-- Margin -->
<div class="m-2xl">Extra large margin</div>
<div class="mt-xs mb-lg">Top XS, Bottom LG</div>

<!-- Gap (for flexbox/grid) -->
<div class="flex gap-md">Medium gap</div>
```

#### Border Radius
```html
<div class="rounded-sm">Small radius</div>
<div class="rounded-lg">Large radius</div>
<div class="rounded-full">Fully rounded</div>
```

#### Shadows
```html
<div class="shadow-sm">Small shadow</div>
<div class="shadow-lg">Large shadow</div>
<div class="shadow-2xl">Extra large shadow</div>
```

## Design Tokens

### Color Palette

#### Base Colors
- `white`, `black`, `transparent`

#### Gray Scale
- `gray-25` through `gray-950`

#### Brand Colors
- `brand-25` through `brand-950`

#### Semantic Colors
- **Success**: `success-25` through `success-950`
- **Warning**: `warning-25` through `warning-950`
- **Error**: `error-25` through `error-950`

#### Utility Colors
- **Blue**: `blue-25` through `blue-950`
- Plus many more color families

#### Semantic Text Colors
- `text-primary`, `text-secondary`, `text-tertiary`
- `text-brand-primary`, `text-brand-secondary`
- `text-error-primary`, `text-warning-primary`, `text-success-primary`

#### Background Colors
- `bg-primary`, `bg-secondary`, `bg-tertiary`
- `bg-brand-solid`, `bg-error-solid`, `bg-success-solid`

### Typography Scale

#### Display Styles
- `display-xl` (60px)
- `display-sm` (30px)
- `display-xs` (24px)

#### Text Styles
- `text-xl` (20px)
- `text-lg` (18px)
- `text-md` (16px)
- `text-sm` (14px)
- `text-xs` (12px)

#### Font Weights
- `regular` (400)
- `medium` (500)
- `semibold` (600)
- `bold` (700)

### Spacing Scale
- `xxs` (2px)
- `xs` (4px)
- `sm` (6px)
- `md` (8px)
- `lg` (12px)
- `xl` (16px)
- `2xl` (20px)
- `3xl` (24px)
- `4xl` (32px)
- `6xl` (48px)
- `7xl` (64px)
- `8xl` (80px)
- `10xl` (128px)

### Border Radius
- `xs` (4px)
- `sm` (6px)
- `md` (8px)
- `lg` (10px)
- `xl` (12px)
- `2xl` (16px)
- `3xl` (20px)
- `full` (9999px)

### Shadow Scale
- `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`

## CSS Variables

All tokens are available as CSS variables with the configurable prefix:

```css
:root {
  /* Colors */
  --bw-color-brand-600: #7f56d9;
  --bw-color-text-primary: #181d27;

  /* Typography */
  --bw-font-size-text-lg: 18px;
  --bw-font-weight-semibold: 600;

  /* Spacing */
  --bw-spacing-lg: 12px;
  --bw-spacing-xl: 16px;

  /* Radius */
  --bw-radius-md: 8px;

  /* Shadows */
  --bw-shadow-lg: 0px 4px 6px -2px rgba(16, 24, 40, 0.03);
}
```

## Direct Token Access

You can also import and use the design tokens directly:

```typescript
import { designTokens } from '@itzcull/tokens-brainwave'

// Access color tokens
console.log(designTokens.colors['brand-600'])

// Access typography tokens
console.log(designTokens.typography['text-lg'])

// Access spacing tokens
console.log(designTokens.spacing.lg)
```

## TypeScript Support

The package includes full TypeScript definitions for all tokens and configuration options:

```typescript
import type { PresetBrainwaveOptions } from '@itzcull/tokens-brainwave'

const config: PresetBrainwaveOptions = {
  prefix: 'custom',
  preflight: false,
  breakpoints: {
    mobile: '375px',
    tablet: '768px',
    desktop: '1200px',
  },
}
```

## Contributing

This package is part of the `@itzcull/tokens` monorepo. The design tokens are extracted from the official Untitled UI Figma file.

## License

MIT