npm package: @kodexalabs/design-tokens
Description: Unified design token system for KodexaLabs projects
Author: KodexaLabs
Latest version: 2.0.0

# @kodexalabs/design-tokens

> **⚠️ DEPRECATED:** This package has been replaced by [`@kodexalabs/asd-tokens`](https://www.npmjs.com/package/@kodexalabs/asd-tokens).
> 
> Please migrate to the new package for the latest design tokens, fonts, and utilities.
> 
> **Migration:**
> ```bash
> # Remove old package
> pnpm remove @kodexalabs/design-tokens
> 
> # Install new package
> pnpm add @kodexalabs/asd-tokens
> ```
> 
> **Update imports:**
> ```typescript
> // Old
> import { designTokens } from '@kodexalabs/design-tokens';
> 
> // New
> import { designTokens } from '@kodexalabs/asd-tokens';
> ```

---

## Legacy Documentation

Unified design token system for all KodexaLabs projects. Provides a single source of truth for colors, typography, spacing, and more across your entire design system.

## Features

- 🎨 **Unified Color System** - Pure black foundation with white accent, success lime, muted gray, and monochrome logo gradients
- 📐 **Rule of 8 Spacing** - Consistent 8px-based spacing scale
- 🔤 **Fluid Typography** - Responsive type scale using CSS clamp()
- 🌗 **Dark Mode Support** - Built-in light and dark theme variants
- 🎭 **Multiple Export Formats** - TypeScript, CSS variables, Tailwind plugin, JSON
- ⚡ **Tree-shakeable** - Import only what you need
- 🔧 **Runtime Theme Switching** - Apply themes dynamically in the browser

## Installation

```bash
npm install @kodexalabs/design-tokens
```

## Usage

### TypeScript/JavaScript

```typescript
import { designTokens, colors, typography } from '@kodexalabs/design-tokens';

// Use tokens directly
const primaryColor = colors.brand.white.hsl; // 'hsl(0 0% 100%)'
const bodyFont = typography.fontFamily.body;
const spacing = designTokens.spacing[4]; // '2rem' (32px)
```

### CSS Variables

```typescript
import { applyCSSVarsToDocument } from '@kodexalabs/design-tokens/css';

// Apply tokens as CSS variables to document
applyCSSVarsToDocument('light'); // or 'dark'

// Use in your CSS
.button {
  background: var(--color-brand-white);
  padding: var(--spacing-2) var(--spacing-4);
  border-radius: var(--radius-md);
  font-family: var(--typography-font-family-sans);
}
```

### Generate CSS String

```typescript
import { generateCompleteCSS } from '@kodexalabs/design-tokens/css';

// Generate CSS string for injection or file output
const css = generateCompleteCSS();
// Inject into <style> tag or save to file
```

### Tailwind CSS Plugin

```javascript
// tailwind.config.js
import kodexaTokens from '@kodexalabs/design-tokens/tailwind';

export default {
  plugins: [kodexaTokens],
};
```

Now use tokens in your Tailwind classes:

```jsx
<button className="bg-white text-white px-4 py-2 rounded-md shadow-glow">
  Click me
</button>

<div className="text-headline font-bold leading-tight">
  Heading
</div>

<div className="space-y-4 max-w-container">
  Content
</div>
```

### React Theme Provider

```typescript
import { applyCSSVarsToDocument } from '@kodexalabs/design-tokens/css';
import { useEffect } from 'react';

function ThemeProvider({ theme, children }) {
  useEffect(() => {
    applyCSSVarsToDocument(theme);
  }, [theme]);
  
  return <>{children}</>;
}
```

### Next.js Integration

```typescript
// app/layout.tsx
import { generateCompleteCSS } from '@kodexalabs/design-tokens/css';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <style dangerouslySetInnerHTML={{ __html: generateCompleteCSS() }} />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

## Design Tokens

### Colors

#### Brand Colors
- **Background** (`#000000`) - Pure black canvas for the entire system
- **Foreground** (`#FFFFFF`) - High-contrast text on the black foundation
- **White** (`#FFFFFF`) - Primary accent for calls to action
- **White Strong** (`#E5E5E5`) - Elevated accent for hover/active states
- **Success** (`#B5FF5C`) - Success and confirmation signals
- **Muted** (`#8A8D93`) - Secondary text and dividers
- **Logo Primary** (`#FFFFFF`) - Monochrome start for Kodexa wordmark
- **Logo Secondary** (`#E5E5E5`) - Monochrome end for Kodexa wordmark

#### Semantic Colors
- Background, foreground, surface
- Elevation levels (elev1, elev2)
- Text (primary, muted, subtle)
- Border (default, subtle)

#### UI Colors
- Primary, secondary, accent
- Destructive, success, warning, info
- Muted, card, popover
- Input, ring

### Typography

#### Font Families
- **Sans**: Inter (primary UI font)
- **Mono**: SF Mono (code font)
- **Display**: Power Grotesk (large headings)
- **Heading**: Plus Jakarta Sans (section headings)

#### Type Scale (Fluid/Responsive)
- **Micro** - Small labels
- **Caption** - Captions, footnotes
- **Body** - Body text (default)
- **Subhead** - Subheadings
- **Headline** - Section headings
- **Title** - Page titles
- **Display** - Large display text
- **Hero** - Hero sections

#### Font Weights
- Regular (400), Medium (500), Semibold (600), Bold (700), Black (900)

### Spacing (Rule of 8)

- `0` - 0
- `1` - 8px
- `2` - 16px
- `3` - 24px
- `4` - 32px
- `5` - 40px
- `6` - 48px
- `7` - 64px
- `8` - 80px
- `9` - 96px
- `10` - 128px

### Border Radius

- `xs` - 4px
- `sm` - 6px
- `md` - 8px
- `lg` - 12px
- `xl` - 16px
- `2xl` - 24px
- `3xl` - 32px
- `round` - 9999px (pill shape)
- `circle` - 50%

### Shadows

- `xs`, `sm`, `md`, `lg`, `xl`, `2xl` - Standard elevation shadows
- `inner` - Inset shadow
- `glow` - Brand glow effect
- `glow-strong` - Stronger glow effect

### Motion

#### Easing Functions
- **Standard** - `cubic-bezier(0.2, 0.8, 0.2, 1)` - Default easing
- **Emphasized** - `cubic-bezier(0.4, 0, 0.2, 1)` - Emphasized motion
- **Decelerate** - `cubic-bezier(0, 0, 0.2, 1)` - Slow down
- **Accelerate** - `cubic-bezier(0.4, 0, 1, 1)` - Speed up
- **Sharp** - `cubic-bezier(0.4, 0, 0.6, 1)` - Sharp motion

#### Durations
- **Instant** - 50ms
- **Fast** - 120ms
- **Base** - 200ms (default)
- **Slow** - 300ms
- **Slower** - 400ms

### Z-Index Layers

- `bg` - 0 - Background elements
- `base` - 1 - Base content
- `content` - 10 - Main content
- `dropdown` - 100 - Dropdowns
- `sticky` - 200 - Sticky elements
- `overlay` - 500 - Overlays
- `modal` - 1000 - Modals
- `popover` - 1100 - Popovers
- `tooltip` - 1200 - Tooltips
- `toast` - 1300 - Toast notifications

## Utilities

### Create Custom Color Token

```typescript
import { createColorToken } from '@kodexalabs/design-tokens';

const customPink = createColorToken(330, '85%', '60%', '#f25ca2');
```

### Merge Tokens

```typescript
import { mergeTokens, designTokens } from '@kodexalabs/design-tokens';

const customTheme = mergeTokens(designTokens, {
  color: {
    brand: {
      white: createColorToken(0, '0%', '100%', '#ffffff'),
    },
  },
});
```

### Get Token by Path

```typescript
import { getTokenByPath } from '@kodexalabs/design-tokens';

const primaryColor = getTokenByPath('color.brand.white.hsl');
// Returns: 'hsl(0 0% 100%)'
```

### Color Conversion

```typescript
import { hexToHSL, rgbToHSL } from '@kodexalabs/design-tokens';

const hsl1 = hexToHSL('#fd0b6e');
const hsl2 = rgbToHSL(253, 11, 110);
```

## TypeScript Support

Full TypeScript support with type definitions included:

```typescript
import type { DesignTokens, ColorToken } from '@kodexalabs/design-tokens';

const tokens: DesignTokens = designTokens;
const color: ColorToken = colors.brand.white;
```

## Contributing

This package is part of the KodexaLabs design system. For changes or additions, please follow the design system guidelines.

## License

MIT © KodexaLabs