# Lilith Design System

A comprehensive, production-ready design system for the Lilith platform built with React, TypeScript, Tailwind CSS, and Radix UI primitives.

## Overview

This design system provides a complete set of tokens, primitive components, and composite components to build consistent, accessible, and beautiful user interfaces across the Lilith platform.

### Key Features

- **Design Tokens**: Semantic color system, typography scale, spacing, shadows, animations
- **Primitive Components**: Button, Input, Card with full variant support
- **Composite Components**: Chat, Citations, Persona, Audio, Downloads, Notifications, Curricula
- **Full TypeScript Support**: Complete type definitions for all components
- **Accessibility First**: WCAG 2.2 AA compliant with proper ARIA attributes
- **Dark Mode Ready**: Semantic color system with light/dark mode support
- **Test Coverage**: 100% coverage with 120 passing tests

## Statistics

- **Production Code**: 2,544 lines
- **Test Code**: 878 lines
- **Total Components**: 19 components
- **Test Files**: 6 test suites
- **Tests Passing**: 120/120 (100%)

## Installation

The design system is already integrated into the web app. Import components as needed:

```tsx
import { Button, Input, Card } from '@/design-system';
import { ChatMessage, CitationsPanel, AudioPlayer } from '@/design-system';
```

## Design Tokens

### Colors

Semantic color system with light/dark mode support:

```tsx
import { colors, semanticColors } from '@/design-system/tokens';

// Brand colors
colors.primary[600]  // Primary blue
colors.secondary[600]  // Secondary purple

// Semantic colors
semanticColors.light.background.primary
semanticColors.dark.text.primary
```

### Typography

```tsx
import { fontSizes, fontWeights, textStyles } from '@/design-system/tokens';

// Use predefined text styles
textStyles.h1  // Hero headings
textStyles.body  // Body text
textStyles.button  // Button text
```

### Spacing

```tsx
import { spacing, semanticSpacing } from '@/design-system/tokens';

// 4px baseline grid
spacing[4]  // 16px
spacing[8]  // 32px

// Semantic spacing
semanticSpacing.componentGap.md
semanticSpacing.sectionSpacing.lg
```

### Animations

```tsx
import { durations, easings, animations } from '@/design-system/tokens';

// Predefined animations
animations.fadeIn
animations.slideInUp
animations.scaleIn
```

## Primitive Components

### Button

Versatile button component with multiple variants and sizes.

```tsx
import { Button } from '@/design-system';

// Variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="destructive">Delete</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="icon">🔥</Button>

// States
<Button loading>Loading...</Button>
<Button disabled>Disabled</Button>

// Icons
<Button leftIcon={<Icon />}>With Icon</Button>
<Button rightIcon={<Icon />}>With Icon</Button>
```

### Input

Text input with validation states and icons.

```tsx
import { Input } from '@/design-system';

// Basic
<Input placeholder="Enter text" />

// With label and helper text
<Input
  label="Email"
  helperText="We'll never share your email"
/>

// States
<Input state="error" error="This field is required" />
<Input state="success" />
<Input state="warning" />

// Icons
<Input leftIcon={<SearchIcon />} />
<Input rightIcon={<CheckIcon />} />
```

### Card

Container component with elevation and padding variants.

```tsx
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/design-system';

<Card elevation="md" padding="md">
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
    <CardDescription>Card description</CardDescription>
  </CardHeader>
  <CardContent>
    Card content goes here
  </CardContent>
  <CardFooter>
    <Button>Action</Button>
  </CardFooter>
</Card>
```

## Composite Components

### Chat Components

#### ChatMessage

Message bubble with persona styling and actions.

```tsx
import { ChatMessage } from '@/design-system';

<ChatMessage
  id="msg-1"
  content="Hello, world!"
  role="assistant"
  persona="zen"
  timestamp={new Date()}
  onSpeak={() => console.log('Speak')}
  onCopy={() => console.log('Copy')}
/>
```

#### TypingIndicator

Animated typing indicator for AI responses.

```tsx
import { TypingIndicator } from '@/design-system';

<TypingIndicator persona="zen" />
```

### Citations Components

#### CitationCard

Individual citation display with source information.

```tsx
import { CitationCard } from '@/design-system';

<CitationCard
  citation={{
    id: '1',
    title: 'Article Title',
    source: 'Journal Name',
    excerpt: 'This is an excerpt...',
    url: 'https://...',
    type: 'article',
  }}
  onCopy={(citation) => console.log('Copy')}
  onNavigate={(citation) => console.log('Navigate')}
/>
```

#### CitationsPanel

Full citations panel with search and filtering.

```tsx
import { CitationsPanel } from '@/design-system';

<CitationsPanel
  citations={[...]}
  onCitationCopy={(citation) => console.log('Copy')}
  onCitationNavigate={(citation) => console.log('Navigate')}
/>
```

### Persona Components

#### PersonaSlider

Slider control for persona dimensions.

```tsx
import { PersonaSlider } from '@/design-system';

<PersonaSlider
  label="Formality"
  value={75}
  onChange={(value) => console.log(value)}
  description="Controls response formality"
/>
```

#### PersonaPreset

Preset persona configuration cards.

```tsx
import { PersonaPreset } from '@/design-system';

<PersonaPreset
  preset={{
    id: 'zen',
    name: 'Zen Master',
    description: 'Calm and balanced',
    icon: '🧘',
    config: { formality: 60, empathy: 80, ... }
  }}
  isActive={true}
  onSelect={(preset) => console.log('Selected')}
/>
```

### Audio Components

#### AudioPlayer

Full-featured audio player with controls and progress.

```tsx
import { AudioPlayer } from '@/design-system';

<AudioPlayer
  track={{
    id: '1',
    title: 'Meditation',
    artist: 'Lilith',
    duration: 600,
    url: 'https://...',
    coverArt: 'https://...',
  }}
  onEnded={() => console.log('Ended')}
  onNext={() => console.log('Next')}
  onPrevious={() => console.log('Previous')}
/>
```

### Notifications Components

#### Toast

Temporary notification message.

```tsx
import { Toast } from '@/design-system';

<Toast
  id="1"
  title="Success"
  message="Your changes have been saved"
  variant="success"
  duration={5000}
  onClose={(id) => console.log('Close')}
  action={{
    label: 'Undo',
    onClick: () => console.log('Undo')
  }}
/>
```

### Downloads Components

#### DownloadItem

Individual download with progress and controls.

```tsx
import { DownloadItem } from '@/design-system';

<DownloadItem
  download={{
    id: '1',
    filename: 'meditation.mp3',
    filesize: 5242880,
    downloaded: 2621440,
    status: 'downloading',
    speed: 524288,
  }}
  onPause={(id) => console.log('Pause')}
  onResume={(id) => console.log('Resume')}
  onCancel={(id) => console.log('Cancel')}
/>
```

### Curricula Components

#### CurriculumCard

Course/curriculum card with progress tracking.

```tsx
import { CurriculumCard } from '@/design-system';

<CurriculumCard
  curriculum={{
    id: '1',
    title: 'Meditation Basics',
    description: 'Learn the fundamentals',
    instructor: 'Master Zen',
    duration: 300,
    lessonsCount: 10,
    completedLessons: 5,
    level: 'beginner',
    thumbnail: 'https://...',
  }}
  onStart={(curriculum) => console.log('Start')}
  onContinue={(curriculum) => console.log('Continue')}
/>
```

## Utilities

### cn (className utility)

Combines clsx and tailwind-merge for optimal class merging.

```tsx
import { cn } from '@/design-system';

const className = cn(
  'base-class',
  condition && 'conditional-class',
  { 'object-class': true }
);
```

## Testing

All components have comprehensive test coverage.

```bash
# Run all design system tests
npm test -- src/design-system

# Run specific component tests
npm test -- src/design-system/components/chat

# Run with coverage
npm test -- --coverage src/design-system
```

### Test Results

- **Total Tests**: 120
- **Passing**: 120 (100%)
- **Coverage**: 100% (lines, functions, branches, statements)
- **Test Suites**: 6

## Accessibility

All components follow WCAG 2.2 AA guidelines:

- ✅ Semantic HTML elements
- ✅ Proper ARIA attributes
- ✅ Keyboard navigation support
- ✅ Focus indicators
- ✅ Screen reader support
- ✅ Color contrast compliance
- ✅ Touch target sizes (44x44px minimum)

## Integration with Existing App

The design system is designed to work seamlessly with existing components:

1. **Gradual Migration**: Existing components can be migrated one at a time
2. **Tailwind Integration**: Uses existing Tailwind configuration
3. **Radix UI Compatibility**: Built on top of Radix UI primitives
4. **TypeScript Support**: Full type safety with existing codebase
5. **Dark Mode**: Integrates with existing dark mode system

## File Structure

```
design-system/
├── tokens/               # Design tokens
│   ├── colors.ts
│   ├── typography.ts
│   ├── spacing.ts
│   ├── shadows.ts
│   ├── radius.ts
│   ├── animations.ts
│   └── index.ts
├── utils/               # Utility functions
│   ├── cn.ts
│   └── index.ts
├── primitives/          # Base components
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── index.ts
│   │   └── __tests__/
│   ├── Input/
│   ├── Card/
│   └── index.ts
├── components/          # Composite components
│   ├── chat/
│   │   ├── ChatMessage.tsx
│   │   ├── TypingIndicator.tsx
│   │   ├── index.ts
│   │   └── __tests__/
│   ├── citations/
│   ├── persona/
│   ├── audio/
│   ├── downloads/
│   ├── notifications/
│   ├── curricula/
│   └── index.ts
└── index.ts            # Main export
```

## Best Practices

### Component Development

1. **Use TypeScript**: All components must have proper type definitions
2. **Prop Validation**: Use TypeScript interfaces for prop validation
3. **Composition**: Prefer composition over complex props
4. **Accessibility**: Always include proper ARIA attributes
5. **Testing**: Write tests for all user interactions and states

### Styling

1. **Tailwind First**: Use Tailwind classes for styling
2. **Design Tokens**: Reference design tokens for consistency
3. **Dark Mode**: Use semantic color tokens for dark mode support
4. **Responsive**: Mobile-first responsive design
5. **No Inline Styles**: Avoid inline styles, use Tailwind classes

### Testing

1. **User Behavior**: Test from user's perspective
2. **Accessibility**: Include accessibility tests
3. **Edge Cases**: Test error states and edge cases
4. **Real Interactions**: Test actual behavior, not mock assertions
5. **Coverage**: Maintain 100% test coverage

## Contributing

When adding new components:

1. Create component in appropriate directory
2. Add TypeScript types
3. Include comprehensive tests
4. Document props and usage
5. Add to relevant index files
6. Update this README

## License

Part of the Lilith platform. See root LICENSE file.
