@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

npm install @integrantlabs/design-tokens

🎨 Usage

CSS Variables (Recommended)

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

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

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:

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

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

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

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

<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

# 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

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

<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