@youwen/ai-design-system/README.md

Enterprise AI-driven design system with comprehensive design tokens

# @youwen/ai-design-system

🎨 Enterprise AI-driven design system with comprehensive design tokens, built for modern React applications.

## ✨ Features

- 🎯 **Comprehensive Design Tokens** - Color, typography, spacing, layout, and more
- 🌈 **Multi-theme Support** - Blue, Green, Purple, Amber themes with light/dark modes
- 📐 **4-Slot Layout System** - Precise 430×225px containers with 195×97px slots
- 📱 **Responsive Design** - Mobile, tablet, desktop breakpoints with layout constraints
- ♿ **Accessibility First** - WCAG 2.1 AA compliant with built-in validation
- 🔧 **TypeScript Native** - Full type safety and IntelliSense support
- 🎨 **OKLCH Color Space** - Modern color system for better gradients
- 🔄 **CSS Variables** - Dynamic theme switching capability

## 📦 Installation

```bash
npm install @youwen/ai-design-system
# or
yarn add @youwen/ai-design-system
# or
pnpm add @youwen/ai-design-system
```

## 🚀 Quick Start

### Basic Theme Setup

```typescript
import { ThemeManager, generateCSSVariables } from '@youwen/ai-design-system';

// Initialize theme manager
const themeManager = new ThemeManager();

// Apply blue theme in dark mode
themeManager.setTheme('blue');
themeManager.setMode('dark');
```

### Using Design Tokens

```typescript
import { 
  designTokens, 
  aiLayout, 
  aiSpacing,
  ResponsiveManager 
} from '@youwen/ai-design-system';

// Access foundation tokens
const primaryColor = designTokens.foundation.colors.brand.blue[500];
const containerPadding = aiSpacing.core.md; // 15px

// Use layout tokens
const containerSize = aiLayout.dimensions.container;
// { width: 430, height: 225 }

// Responsive utilities
const responsiveManager = new ResponsiveManager();
const currentBreakpoint = responsiveManager.getCurrentBreakpoint();
```

### CSS Variables Integration

```css
:root {
  /* Auto-generated theme variables */
  --primary: oklch(0.50 0.30 240);
  --background: oklch(0.05 0 0);
  --foreground: oklch(0.98 0 0);
  
  /* Widget-specific variables */
  --widget-font-big: 40px;
  --widget-line-height-big: 28px;
  --widget-container-padding: 15px;
}

.my-component {
  background-color: var(--background);
  color: var(--foreground);
  padding: var(--widget-container-padding);
}
```

## 🎨 Theme System

### Available Themes

- **Blue**: Primary AI system theme
- **Green**: Environmental/energy theme  
- **Purple**: AI/analytics theme
- **Amber**: Warning/alert theme

### Theme Switching

```typescript
// Programmatic theme switching
themeManager.setTheme('green');
themeManager.setMode('light');

// Toggle dark/light mode
themeManager.toggleMode();

// Get current theme info
const currentTheme = themeManager.getCurrentTheme();
const currentMode = themeManager.getCurrentMode();
```

## 📐 Layout System

### 4-Slot Container System

```typescript
import { aiLayout } from '@youwen/ai-design-system';

// Standard container dimensions
const container = aiLayout.dimensions.container;
// { width: 430, height: 225 }

// Slot dimensions  
const slot = aiLayout.dimensions.widgetSmall;
// { width: 195, height: 97 }

// 15 supported layout combinations
// Single slots: leftTop, rightTop, leftBottom, rightBottom
// Dual slots: horizontal pairs, vertical pairs
// Triple slots: L-shapes, T-shapes
// Quad slot: all four positions
```

### Responsive Breakpoints

```typescript
import { ResponsiveManager, breakpoints } from '@youwen/ai-design-system';

// Breakpoint definitions
// Mobile: 0-767px (single slot only)
// Tablet: 768-1023px (dual slots allowed)  
// Desktop: 1024-1439px (all layouts)
// Desktop Large: 1440px+ (all layouts)

const manager = new ResponsiveManager();
const config = manager.getResponsiveConfig('container');
```

## 🔤 Typography System

### Widget Typography Scale

```typescript
import { semanticTokens } from '@youwen/ai-design-system';

// Widget-specific font sizes
const typography = semanticTokens.typography.widget;

// Big: 40px/28px - Primary data display
// Medium: 24px/17px - Secondary information  
// Small: 16px/11px - Body content
// Mini: 10px/7px - Helper text (accessibility warning)
```

### Font Family

```css
font-family: "Scto Grotesk A", "Inter", ui-sans-serif, system-ui, sans-serif;
```

## 🎯 Spacing System

### Core Spacing Scale

```typescript
import { aiSpacing } from '@youwen/ai-design-system';

// Base unit: 15px (container padding)
// Scale: 5px, 10px, 15px, 20px, 30px, 45px, 60px

// Component-specific spacing
const containerPadding = aiSpacing.component.container.padding; // 15px
const textGap = aiSpacing.gap.text.line; // 10px
const itemSpacing = aiSpacing.gap.normal; // 10px
```

## ♿ Accessibility Features

### Color Contrast

- **Normal text**: 4.5:1 minimum contrast ratio
- **Large text**: 3.0:1 minimum contrast ratio  
- **UI components**: 3.0:1 minimum contrast ratio

### Touch Targets

- **Minimum size**: 44×44px
- **Recommended size**: 48×48px
- **Adjacent spacing**: 8px minimum

### Validation Tools

```typescript
import { AccessibilityValidator } from '@youwen/ai-design-system';

const validator = new AccessibilityValidator();
const result = validator.validateContrast(foregroundColor, backgroundColor, fontSize);
```

## 🛠 Advanced Usage

### Custom CSS Variables

```typescript
import { generateCSSVariables } from '@youwen/ai-design-system';

// Generate CSS variables for any theme/mode combination
const variables = generateCSSVariables('purple', 'dark');

// Apply to document root
Object.entries(variables).forEach(([key, value]) => {
  document.documentElement.style.setProperty(key, value);
});
```

### Tailwind CSS Integration

```typescript
import { generateTailwindConfig } from '@youwen/ai-design-system';

// tailwind.config.js
module.exports = {
  ...generateTailwindConfig(),
  // Your other Tailwind config
};
```

## 📚 Component Examples

### Themed Button

```tsx
import React from 'react';
import { designTokens } from '@youwen/ai-design-system';

const ThemedButton = ({ children, variant = 'primary' }) => {
  const buttonTokens = designTokens.component.button[variant];
  
  return (
    <button
      style={{
        backgroundColor: 'var(--primary)',
        color: 'var(--primary-foreground)',
        padding: buttonTokens.padding,
        borderRadius: buttonTokens.borderRadius,
        height: buttonTokens.height,
        // ... other styles from tokens
      }}
    >
      {children}
    </button>
  );
};
```

### Widget Container

```tsx
import React from 'react';
import { aiLayout, aiSpacing } from '@youwen/ai-design-system';

const WidgetContainer = ({ children, layout = 'single' }) => {
  const containerStyle = {
    width: aiLayout.dimensions.container.width,
    height: aiLayout.dimensions.container.height,
    padding: aiSpacing.component.container.padding,
    backgroundColor: 'var(--widget-background)',
    border: '1px solid var(--widget-border)',
    borderRadius: '10px'
  };

  return (
    <div style={containerStyle}>
      {children}
    </div>
  );
};
```

## 🔧 TypeScript Support

Full TypeScript definitions included:

```typescript
import type {
  ThemeName,
  ThemeMode,
  DesignTokens,
  AIDimension,
  AISpacing,
  BreakpointName
} from '@youwen/ai-design-system';
```

## 📖 API Reference

### Core Exports

- `ThemeManager` - Theme and mode management
- `ResponsiveManager` - Breakpoint and layout utilities
- `AccessibilityValidator` - A11y validation tools
- `designTokens` - Complete design token system
- `aiLayout` - Layout dimensions and positioning
- `aiSpacing` - Spacing and gap definitions
- `generateCSSVariables` - CSS variable generation
- `generateTailwindConfig` - Tailwind configuration

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

MIT © [youwen.wang](https://github.com/youwen-wang)

## 🔗 Links

- [Documentation](https://github.com/youwen-wang/ai-design-system)
- [Storybook](https://youwen-ai-design-system.netlify.app)
- [Issue Tracker](https://github.com/youwen-wang/ai-design-system/issues)

---

Built with ❤️ for modern enterprise applications