npm package: @integrantlabs/design-tokens
Description: Design tokens for Integrant AI component libraries - colors, typography, spacing, and theming
Author: ge-hall
Latest version: 0.1.0

# @integrantlabs/design-tokens

> **✅ COMPLETE** - Design tokens for the Integrant AI component libraries - providing consistent theming, colors, typography, spacing, and styling across React and Vue implementations.

**Issue #75 Status**: All acceptance criteria completed - Design token system fully operational!

## 🎨 **What Are Design Tokens?**

Design tokens are the visual design decisions of a design system, represented as data. They provide a single source of truth for colors, typography, spacing, shadows, and other design elements across all components and platforms.

## 🚀 **Key Features**

- **🎯 CSS Variables**: Dynamic theming with runtime theme switching
- **⚡ Tailwind Integration**: First-class Tailwind CSS support  
- **🌓 Light/Dark Themes**: Built-in light and dark theme support
- **📱 Responsive Design**: Mobile-first responsive breakpoints
- **♿ Accessibility**: WCAG 2.1 AA compliant color contrasts
- **🔧 TypeScript**: Full TypeScript support with type safety

## 📦 **Installation**

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

## 🎨 **Usage**

### CSS Variables (Recommended)

```css
/* Import the CSS variables */
@import '@integrantlabs/design-tokens/css/tokens.css';

/* Use semantic color variables that change with theme */
.my-component {
  background-color: var(--integrant-bg-primary);
  color: var(--integrant-text-primary);
  border: 1px solid var(--integrant-border-default);
}
```

### Tailwind CSS Integration

```javascript
// tailwind.config.js
const { generateTailwindConfig } = require('@integrant-ai/design-tokens');

module.exports = {
  ...generateTailwindConfig(),
  content: [
    './src/**/*.{js,ts,jsx,tsx,vue}',
    // ... your content paths
  ],
};
```

### JavaScript/TypeScript

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

// Use design tokens in your components
const primaryColor = colors.primary[500]; // #3b82f6
const baseFontSize = typography.fontSize.base; // ['1rem', { lineHeight: '1.5rem' }]
const mediumSpacing = spacing[4]; // '1rem' (16px)
```

## 🌈 **Design Token Categories**

### Colors
- **Primary**: Brand colors (#3b82f6 blue palette)
- **Secondary**: Neutral slate/gray colors  
- **Semantic**: Success, error, warning, info colors
- **Gray**: Comprehensive grayscale from 50-950

### Typography
- **Font Families**: Sans (Inter), Mono (JetBrains Mono), Serif
- **Font Sizes**: xs (12px) to 9xl (128px)
- **Font Weights**: 100-900 scale
- **Line Heights**: Tight, normal, relaxed options
- **Letter Spacing**: Fine-tuned spacing options

### Spacing
- **Scale**: 4px grid system (0.5 = 2px, 1 = 4px, 2 = 8px, etc.)
- **Range**: px to 96 (384px) with logical increments
- **Usage**: Padding, margins, gaps, positioning

### Other Tokens
- **Border Radius**: From 2px to full rounded
- **Shadows**: Subtle to dramatic depth effects  
- **Z-Index**: Layering scale for components
- **Animation**: Duration and easing curves
- **Breakpoints**: Responsive design breakpoints

## 🌓 **Theming**

### Automatic Theme Detection

The design tokens automatically respect system theme preferences:

```css
/* Light theme (default) */
:root {
  --integrant-bg-primary: #f9fafb;
  --integrant-text-primary: #111827;
}

/* Dark theme (system preference) */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) {
    --integrant-bg-primary: #111827;
    --integrant-text-primary: #f9fafb;
  }
}
```

### Manual Theme Control

```javascript
// Set theme manually
document.documentElement.setAttribute('data-theme', 'dark');

// Toggle theme
const currentTheme = document.documentElement.getAttribute('data-theme');
const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
document.documentElement.setAttribute('data-theme', newTheme);
```

## 🎯 **Semantic Color System**

Instead of using specific color values, use semantic aliases that adapt to themes:

```css
/* ✅ Good - Uses semantic colors that adapt to theme */
.button {
  background-color: var(--integrant-bg-secondary);
  color: var(--integrant-text-primary);
  border: 1px solid var(--integrant-border-default);
}

/* ❌ Avoid - Fixed colors that don't adapt to theme */
.button {
  background-color: #ffffff;
  color: #111827;
  border: 1px solid #e5e7eb;
}
```

### Available Semantic Variables

**Backgrounds:**
- `--integrant-bg-primary` - Main background color
- `--integrant-bg-secondary` - Card/surface backgrounds  
- `--integrant-bg-tertiary` - Subtle background variations
- `--integrant-bg-overlay` - Modal/overlay backgrounds

**Text:**
- `--integrant-text-primary` - Main text color
- `--integrant-text-secondary` - Subdued text
- `--integrant-text-muted` - Placeholder/disabled text
- `--integrant-text-inverse` - Text on dark backgrounds

**Borders:**
- `--integrant-border-default` - Standard border color
- `--integrant-border-muted` - Subtle borders
- `--integrant-border-strong` - Emphasis borders

## ⚡ **Tailwind CSS Usage**

### Component Classes

```jsx
// Using Tailwind with design tokens
<button className="bg-primary-500 text-white px-4 py-2 rounded-md hover:bg-primary-600 focus:ring-2 focus:ring-primary-500/50">
  Primary Button
</button>

// Using semantic colors
<div className="bg-secondary text-primary-semantic border border-default-semantic rounded-lg p-6">
  <h2 className="text-lg font-semibold text-primary-semantic">Card Title</h2>
  <p className="text-secondary-semantic">Card content that adapts to theme.</p>
</div>
```

### Responsive Design

```jsx
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 sm:gap-6 lg:gap-8">
  <div className="p-4 sm:p-6 bg-surface-raised rounded-lg shadow-sm hover:shadow-md transition-shadow">
    Responsive card
  </div>
</div>
```

## 📁 **File Structure**

```
@integrant-ai/design-tokens/
├── dist/
│   ├── index.js           # Main JS export
│   ├── index.d.ts         # TypeScript declarations
│   └── tailwind.config.js # Generated Tailwind config
├── css/
│   ├── tokens.css         # CSS variables  
│   └── base.css          # Base styles
├── tokens.json           # JSON format tokens
├── meta.json            # Package metadata
└── README.md
```

## 🔧 **Development**

```bash
# Install dependencies
npm install

# Build all formats
npm run build

# Generate CSS and JSON
npm run build:tokens

# Type checking
npm run typecheck

# Linting
npm run lint
```

## 🎯 **Integration Examples**

### React Component with Tailwind

```tsx
import React from 'react';

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  className?: string;
}

export function Button({ 
  variant = 'primary', 
  size = 'md', 
  children, 
  className,
  ...props 
}: ButtonProps) {
  const baseClasses = 'inline-flex items-center justify-center font-medium rounded-md transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2';
  
  const variantClasses = {
    primary: 'bg-primary text-white hover:bg-primary-600 focus:ring-primary/50',
    secondary: 'bg-secondary text-primary-semantic hover:bg-secondary-600 focus:ring-secondary/50',
    ghost: 'text-primary hover:bg-primary-50 focus:ring-primary/50'
  };
  
  const sizeClasses = {
    sm: 'px-3 py-1.5 text-sm',
    md: 'px-4 py-2 text-base',
    lg: 'px-6 py-3 text-lg'
  };
  
  return (
    <button 
      className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]} ${className || ''}`}
      {...props}
    >
      {children}
    </button>
  );
}
```

### Vue Component with Design Tokens

```vue
<template>
  <button 
    :class="buttonClasses"
    @click="$emit('click')"
  >
    <slot />
  </button>
</template>

<script setup lang="ts">
import { computed } from 'vue';

interface Props {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
}

const props = withDefaults(defineProps<Props>(), {
  variant: 'primary',
  size: 'md'
});

const buttonClasses = computed(() => {
  const base = 'inline-flex items-center justify-center font-medium rounded-md transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2';
  
  const variants = {
    primary: 'bg-primary text-white hover:bg-primary-600 focus:ring-primary/50',
    secondary: 'bg-secondary text-primary-semantic hover:bg-secondary-600 focus:ring-secondary/50',
    ghost: 'text-primary hover:bg-primary-50 focus:ring-primary/50'
  };
  
  const sizes = {
    sm: 'px-3 py-1.5 text-sm',
    md: 'px-4 py-2 text-base',
    lg: 'px-6 py-3 text-lg'
  };
  
  return `${base} ${variants[props.variant]} ${sizes[props.size]}`;
});
</script>
```

## 📜 **License**

MIT © [Integrant AI](https://github.com/ge-hall/integrant-ai-platform)