# 🎨 Kōdō Design System - Référence Complète UI

> **Document de référence exhaustif pour la génération du design system Kōdō**
> 
> Ce document contient toutes les spécifications nécessaires pour générer un design system complet et autonome qui peut être importé dans n'importe quel projet.

---

## 📋 Table des Matières

1. [Palette de Couleurs](#palette-de-couleurs)
2. [Typographie](#typographie)
3. [Espacements & Grilles](#espacements--grilles)
4. [Composants UI](#composants-ui)
5. [Animations & Transitions](#animations--transitions)
6. [Thèmes & Variantes](#thèmes--variantes)
7. [Icônes & Assets](#icônes--assets)
8. [États & Interactions](#états--interactions)
9. [Responsive Design](#responsive-design)
10. [Accessibilité](#accessibilité)

---

## 🎨 Palette de Couleurs

### Spectre Astral (Palette Principale)

#### Neutrals (Backgrounds & Surfaces)
```css
--kodo-void: 11 12 16          /* #0B0C10 - Background principal */
--kodo-ink: 23 25 35           /* #171923 - Surface secondaire */
--kodo-graphite: 31 40 51      /* #1F2833 - Cards, inputs */
--kodo-slate: 44 54 67         /* #2C3643 - Hover states */
--kodo-steel: 59 69 84         /* #3B4554 - Borders, dividers */
```

#### Accent Colors (Highlights & CTAs)
```css
--kodo-cyan: 102 252 241       /* #66FCF1 - Primary accent, CTAs */
--kodo-cyan-dim: 69 162 158    /* #45A29E - Cyan variant */
--kodo-magenta: 138 126 164    /* #8A7EA4 - Creative accent */
--kodo-orange: 230 184 156     /* #E6B89C - Warm accent */
```

#### Semantic Colors
```css
--kodo-lime: 54 229 209        /* #36E5D1 - Success */
--kodo-gold: 234 179 8         /* #EAB308 - Warning */
--kodo-red: 230 57 70          /* #E63946 - Error, danger */
```

#### Text Colors
```css
--kodo-text-main: 243 243 224       /* #F3F3E0 - Body text */
--kodo-content-highlight: 255 255 255  /* #FFFFFF - Headings */
--kodo-content-dim: 156 163 175     /* #9CA3AF - Secondary text */
```

### Utilisation Tailwind
```javascript
colors: {
  kodo: {
    void: 'rgb(var(--kodo-void) / <alpha-value>)',
    ink: 'rgb(var(--kodo-ink) / <alpha-value>)',
    graphite: 'rgb(var(--kodo-graphite) / <alpha-value>)',
    slate: 'rgb(var(--kodo-slate) / <alpha-value>)',
    steel: 'rgb(var(--kodo-steel) / <alpha-value>)',
    cyan: 'rgb(var(--kodo-cyan) / <alpha-value>)',
    'cyan-dim': 'rgb(var(--kodo-cyan-dim) / <alpha-value>)',
    magenta: 'rgb(var(--kodo-magenta) / <alpha-value>)',
    lime: 'rgb(var(--kodo-lime) / <alpha-value>)',
    orange: 'rgb(var(--kodo-orange) / <alpha-value>)',
    gold: 'rgb(var(--kodo-gold) / <alpha-value>)',
    red: 'rgb(var(--kodo-red) / <alpha-value>)',
    primary: 'rgb(var(--kodo-content-highlight) / <alpha-value>)',
    secondary: 'rgb(var(--kodo-content-dim) / <alpha-value>)',
  }
}
```

---

## 📝 Typographie

### Familles de Polices

```css
font-family: {
  display: ['Space Grotesk', 'sans-serif'],  /* Titres principaux */
  heading: ['Space Grotesk', 'sans-serif'],  /* Sous-titres */
  body: ['Inter', 'sans-serif'],             /* Corps de texte */
  mono: ['JetBrains Mono', 'monospace'],     /* Code, terminal */
}
```

### Échelle Typographique

| Niveau | Taille | Line Height | Font Weight | Usage |
|--------|--------|-------------|-------------|-------|
| **Display** | 4.5rem (72px) | 1.1 | 700 | Hero sections |
| **H1** | 3rem (48px) | 1.2 | 700 | Page titles |
| **H2** | 2.25rem (36px) | 1.3 | 600 | Section headers |
| **H3** | 1.875rem (30px) | 1.3 | 600 | Subsections |
| **H4** | 1.5rem (24px) | 1.4 | 600 | Card titles |
| **H5** | 1.25rem (20px) | 1.4 | 500 | Small headings |
| **H6** | 1.125rem (18px) | 1.4 | 500 | Labels |
| **Body Large** | 1.125rem (18px) | 1.6 | 400 | Lead paragraphs |
| **Body** | 1rem (16px) | 1.6 | 400 | Default text |
| **Body Small** | 0.875rem (14px) | 1.5 | 400 | Secondary text |
| **Caption** | 0.75rem (12px) | 1.4 | 400 | Captions, labels |
| **Overline** | 0.75rem (12px) | 1.4 | 600 | Uppercase labels |

### Classes Utilitaires

```css
.text-display { @apply text-7xl font-display font-bold; }
.text-h1 { @apply text-5xl font-heading font-bold; }
.text-h2 { @apply text-4xl font-heading font-semibold; }
.text-h3 { @apply text-3xl font-heading font-semibold; }
.text-h4 { @apply text-2xl font-heading font-semibold; }
.text-body-lg { @apply text-lg font-body; }
.text-body { @apply text-base font-body; }
.text-body-sm { @apply text-sm font-body; }
.text-caption { @apply text-xs font-body; }
```

---

## 📏 Espacements & Grilles

### Système d'Espacement

```javascript
spacing: {
  0: '0px',
  1: '0.25rem',    // 4px
  2: '0.5rem',     // 8px
  3: '0.75rem',    // 12px
  4: '1rem',       // 16px
  5: '1.25rem',    // 20px
  6: '1.5rem',     // 24px
  8: '2rem',       // 32px
  10: '2.5rem',    // 40px
  12: '3rem',      // 48px
  16: '4rem',      // 64px
  20: '5rem',      // 80px
  24: '6rem',      // 96px
  32: '8rem',      // 128px
}
```

### Border Radius

```javascript
borderRadius: {
  none: '0',
  sm: '0.25rem',    // 4px
  DEFAULT: '0.5rem', // 8px
  md: '0.5rem',     // 8px
  lg: '0.75rem',    // 12px
  xl: '12px',
  '2xl': '16px',
  '3xl': '24px',
  full: '9999px',
}
```

### Grille & Layout

```css
/* Container */
.container {
  max-width: 1280px;
  margin: 0 auto;
  padding: 0 1rem;
}

/* Grid System */
.grid-cols-auto-fill {
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
}

.grid-cols-auto-fit {
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
}
```

---

## 🧩 Composants UI

### 1. Button

#### Variantes

**Primary** - CTA principal
```tsx
variant="primary"
// Styles: bg-gradient-to-r from-kodo-cyan-dim to-kodo-cyan
// Text: text-kodo-void
// Hover: shadow-lg shadow-kodo-cyan/20
```

**Secondary** - Actions secondaires
```tsx
variant="secondary"
// Styles: border border-kodo-magenta/50 bg-transparent
// Text: text-kodo-magenta
// Hover: bg-kodo-magenta/5 border-kodo-magenta
```

**Ghost** - Actions tertiaires
```tsx
variant="ghost"
// Styles: bg-transparent
// Text: text-gray-400
// Hover: text-white bg-white/5
```

**Gaming** - Style gaming/tech
```tsx
variant="gaming"
// Styles: bg-kodo-slate border border-kodo-gold/40
// Text: text-kodo-gold uppercase tracking-wider
```

**Terminal** - Style code/terminal
```tsx
variant="terminal"
// Styles: bg-kodo-ink border border-kodo-steel
// Text: text-gray-300 font-mono text-xs
```

**Nature** - Style organique
```tsx
variant="nature"
// Styles: bg-kodo-slate border border-kodo-lime/30
// Text: text-kodo-lime
```

**Icon** - Bouton icône uniquement
```tsx
variant="icon"
// Styles: bg-transparent rounded-full p-2
// Hover: bg-white/10
```

#### Tailles

```tsx
size="sm"   // text-xs px-3 py-1.5
size="md"   // text-sm px-5 py-2.5 (default)
size="lg"   // text-base px-8 py-3.5
size="icon" // p-2.5
```

#### Props Interface

```typescript
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost' | 'gaming' | 'terminal' | 'nature' | 'icon';
  size?: 'sm' | 'md' | 'lg' | 'icon';
  icon?: React.ReactNode;
  disabled?: boolean;
  onClick?: () => void;
  type?: 'button' | 'submit' | 'reset';
  className?: string;
  children?: React.ReactNode;
}
```

---

### 2. Input

#### Input Standard

```typescript
interface InputProps {
  label?: string;
  type?: string;
  placeholder?: string;
  icon?: React.ReactNode;
  error?: string;
  disabled?: boolean;
  className?: string;
}
```

**Styles de base:**
```css
bg-kodo-graphite
border border-kodo-steel
text-white
placeholder-gray-500
rounded-lg
focus:border-kodo-cyan focus:ring-1 focus:ring-kodo-cyan
```

#### SearchInput

```typescript
interface SearchInputProps {
  placeholder?: string;
  onSearch?: (value: string) => void;
}
```

**Styles:**
```css
rounded-full
pl-12 pr-4 py-3
bg-kodo-graphite
border border-kodo-steel
focus:shadow-neon-cyan
```

#### FileUpload

```typescript
interface FileUploadProps {
  onUpload?: (files: FileList) => void;
  accept?: string;
  maxSize?: number;
  className?: string;
}
```

**Styles:**
```css
border-2 border-dashed border-kodo-steel
rounded-xl p-8
bg-kodo-graphite/50
hover:bg-kodo-slate/30 hover:border-kodo-cyan/50
```

---

### 3. Card

#### Variantes

**Default** - Card standard
```css
bg-kodo-graphite
border border-kodo-steel/60
p-6
hover:border-kodo-steel
```

**Manga** - Style créatif/artistique
```css
bg-gradient-to-br from-kodo-graphite to-kodo-slate
border border-kodo-magenta/20
hover:border-kodo-magenta/40
hover:shadow-neon-magenta/10
```

**Gaming** - Style tech/gaming
```css
bg-kodo-ink
border border-kodo-cyan/20
hover:border-kodo-cyan/40
hover:shadow-neon-cyan/10
```

**Glass** - Glassmorphism
```css
bg-kodo-slate/40
backdrop-blur-xl
border border-white/5
hover:bg-kodo-slate/50
```

#### Props Interface

```typescript
interface CardProps {
  variant?: 'default' | 'manga' | 'gaming' | 'glass';
  children: React.ReactNode;
  className?: string;
  onClick?: () => void;
}
```

---

### 4. Badge

```typescript
interface BadgeProps {
  variant?: 'default' | 'success' | 'warning' | 'error' | 'info';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
}
```

**Variantes:**
```css
default: bg-kodo-steel/50 text-gray-300
success: bg-kodo-lime/10 text-kodo-lime border-kodo-lime/30
warning: bg-kodo-gold/10 text-kodo-gold border-kodo-gold/30
error: bg-kodo-red/10 text-kodo-red border-kodo-red/30
info: bg-kodo-cyan/10 text-kodo-cyan border-kodo-cyan/30
```

---

### 5. Avatar

```typescript
interface AvatarProps {
  src?: string;
  alt?: string;
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
  status?: 'online' | 'offline' | 'away' | 'busy';
  fallback?: string;
}
```

**Tailles:**
```css
xs: w-6 h-6
sm: w-8 h-8
md: w-10 h-10
lg: w-12 h-12
xl: w-16 h-16
```

**Status Indicator:**
```css
online: bg-kodo-lime
offline: bg-gray-500
away: bg-kodo-gold
busy: bg-kodo-red
```

---

### 6. Progress Bar

```typescript
interface ProgressProps {
  value: number;
  max?: number;
  variant?: 'default' | 'success' | 'warning' | 'error';
  size?: 'sm' | 'md' | 'lg';
  showLabel?: boolean;
}
```

**Variantes:**
```css
default: bg-kodo-cyan
success: bg-kodo-lime
warning: bg-kodo-gold
error: bg-kodo-red
```

---

### 7. Modal / Dialog

```typescript
interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title?: string;
  children: React.ReactNode;
  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
  variant?: 'default' | 'gaming' | 'glass';
}
```

**Overlay:**
```css
bg-kodo-void/80
backdrop-blur-sm
```

**Content:**
```css
bg-kodo-graphite
border border-kodo-steel
rounded-2xl
shadow-2xl
```

---

### 8. Dropdown / Select

```typescript
interface SelectProps {
  options: Array<{ value: string; label: string }>;
  value?: string;
  onChange?: (value: string) => void;
  placeholder?: string;
  disabled?: boolean;
}
```

**Styles:**
```css
/* Trigger */
bg-kodo-graphite
border border-kodo-steel
rounded-lg
hover:border-kodo-cyan

/* Menu */
bg-kodo-ink
border border-kodo-steel
rounded-lg
shadow-xl

/* Item */
hover:bg-kodo-slate
focus:bg-kodo-cyan/10
```

---

### 9. Checkbox & Radio

```typescript
interface CheckboxProps {
  checked?: boolean;
  onChange?: (checked: boolean) => void;
  label?: string;
  disabled?: boolean;
}
```

**Styles:**
```css
/* Checkbox */
border-kodo-steel
bg-kodo-graphite
checked:bg-kodo-cyan
checked:border-kodo-cyan
rounded

/* Radio */
border-kodo-steel
bg-kodo-graphite
checked:bg-kodo-cyan
checked:border-kodo-cyan
rounded-full
```

---

### 10. Switch / Toggle

```typescript
interface SwitchProps {
  checked?: boolean;
  onChange?: (checked: boolean) => void;
  label?: string;
  disabled?: boolean;
}
```

**Styles:**
```css
/* Track */
bg-kodo-steel
checked:bg-kodo-cyan
rounded-full
w-11 h-6

/* Thumb */
bg-white
rounded-full
w-5 h-5
```

---

### 11. Tabs

```typescript
interface TabsProps {
  tabs: Array<{ id: string; label: string; content: React.ReactNode }>;
  defaultTab?: string;
  variant?: 'default' | 'pills' | 'underline';
}
```

**Variantes:**

**Default:**
```css
border-b border-kodo-steel
active:border-b-2 border-kodo-cyan
```

**Pills:**
```css
bg-kodo-graphite
active:bg-kodo-cyan active:text-kodo-void
rounded-lg
```

**Underline:**
```css
border-b-2 border-transparent
active:border-kodo-cyan
```

---

### 12. Toast / Notification

```typescript
interface ToastProps {
  type?: 'success' | 'error' | 'warning' | 'info';
  title: string;
  message?: string;
  duration?: number;
  onClose?: () => void;
}
```

**Variantes:**
```css
success: bg-kodo-lime/10 border-kodo-lime/50 text-kodo-lime
error: bg-kodo-red/10 border-kodo-red/50 text-kodo-red
warning: bg-kodo-gold/10 border-kodo-gold/50 text-kodo-gold
info: bg-kodo-cyan/10 border-kodo-cyan/50 text-kodo-cyan
```

---

### 13. Tooltip

```typescript
interface TooltipProps {
  content: string;
  position?: 'top' | 'bottom' | 'left' | 'right';
  children: React.ReactNode;
}
```

**Styles:**
```css
bg-kodo-ink
border border-kodo-steel
text-sm
rounded-lg
px-3 py-2
shadow-xl
```

---

### 14. Table

```typescript
interface TableProps {
  columns: Array<{ key: string; label: string; sortable?: boolean }>;
  data: Array<Record<string, any>>;
  onSort?: (key: string) => void;
  variant?: 'default' | 'striped' | 'bordered';
}
```

**Styles:**
```css
/* Header */
bg-kodo-ink
border-b border-kodo-steel
text-kodo-secondary
font-semibold

/* Row */
border-b border-kodo-steel/30
hover:bg-kodo-slate/30

/* Cell */
px-6 py-4
text-white
```

---

### 15. Accordion

```typescript
interface AccordionProps {
  items: Array<{ title: string; content: React.ReactNode }>;
  allowMultiple?: boolean;
  defaultOpen?: number[];
}
```

**Styles:**
```css
/* Header */
bg-kodo-graphite
border border-kodo-steel
hover:bg-kodo-slate
rounded-lg

/* Content */
bg-kodo-ink
border-x border-b border-kodo-steel
rounded-b-lg
```

---

### 16. Breadcrumb

```typescript
interface BreadcrumbProps {
  items: Array<{ label: string; href?: string }>;
  separator?: React.ReactNode;
}
```

**Styles:**
```css
text-kodo-secondary
hover:text-kodo-cyan
active:text-white font-semibold
```

---

### 17. Pagination

```typescript
interface PaginationProps {
  currentPage: number;
  totalPages: number;
  onPageChange: (page: number) => void;
  variant?: 'default' | 'simple';
}
```

**Styles:**
```css
/* Button */
bg-kodo-graphite
border border-kodo-steel
hover:bg-kodo-slate
active:bg-kodo-cyan active:text-kodo-void
```

---

### 18. Skeleton Loader

```typescript
interface SkeletonProps {
  variant?: 'text' | 'circular' | 'rectangular';
  width?: string | number;
  height?: string | number;
  animation?: 'pulse' | 'wave';
}
```

**Styles:**
```css
bg-kodo-graphite
animate-pulse
rounded
```

---

### 19. Spinner / Loading

```typescript
interface SpinnerProps {
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
  variant?: 'default' | 'dots' | 'bars';
  color?: string;
}
```

**Variantes:**
```css
default: border-kodo-cyan border-t-transparent animate-spin
dots: bg-kodo-cyan animate-bounce
bars: bg-kodo-cyan animate-pulse
```

---

### 20. Divider

```typescript
interface DividerProps {
  orientation?: 'horizontal' | 'vertical';
  variant?: 'solid' | 'dashed' | 'dotted';
  label?: string;
}
```

**Styles:**
```css
bg-kodo-steel
h-px (horizontal)
w-px (vertical)
```

---

## 🎭 Animations & Transitions

### Animations Personnalisées

```css
/* Float Animation */
@keyframes float {
  0%, 100% { transform: translateY(0px); }
  50% { transform: translateY(-5px); }
}
.animate-float { animation: float 6s ease-in-out infinite; }

/* Fade In */
@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}
.animate-fadeIn { animation: fadeIn 0.3s ease-in; }

/* Pulse Glow */
@keyframes pulse-glow {
  0%, 100% { box-shadow: 0 0 10px rgba(var(--kodo-cyan), 0.2); }
  50% { box-shadow: 0 0 20px rgba(var(--kodo-cyan), 0.4); }
}
.animate-pulse-glow { animation: pulse-glow 2s ease-in-out infinite; }

/* Slide In */
@keyframes slideInRight {
  from { transform: translateX(100%); opacity: 0; }
  to { transform: translateX(0); opacity: 1; }
}
.animate-slideInRight { animation: slideInRight 0.3s ease-out; }

/* Scale In */
@keyframes scaleIn {
  from { transform: scale(0.9); opacity: 0; }
  to { transform: scale(1); opacity: 1; }
}
.animate-scaleIn { animation: scaleIn 0.2s ease-out; }

/* Shimmer */
@keyframes shimmer {
  0% { background-position: -1000px 0; }
  100% { background-position: 1000px 0; }
}
.animate-shimmer {
  background: linear-gradient(
    90deg,
    transparent,
    rgba(var(--kodo-cyan), 0.1),
    transparent
  );
  background-size: 1000px 100%;
  animation: shimmer 2s infinite;
}
```

### Transitions Standards

```css
.transition-base { transition: all 200ms ease; }
.transition-colors { transition: color, background-color, border-color 200ms ease; }
.transition-transform { transition: transform 200ms ease; }
.transition-opacity { transition: opacity 200ms ease; }
.transition-shadow { transition: box-shadow 200ms ease; }
```

---

## 🎨 Gradients & Effects

### Gradients Prédéfinis

```javascript
backgroundImage: {
  'gradient-neon': 'linear-gradient(135deg, rgb(var(--kodo-cyan-dim)) 0%, rgb(var(--kodo-cyan)) 100%)',
  'gradient-gaming': 'linear-gradient(135deg, rgb(var(--kodo-graphite)) 0%, rgb(var(--kodo-ink)) 100%)',
  'gradient-cyber': 'linear-gradient(135deg, rgba(var(--kodo-cyan), 0.1) 0%, rgba(var(--kodo-magenta), 0.1) 100%)',
  'gradient-sunset': 'linear-gradient(135deg, rgb(var(--kodo-orange)) 0%, rgb(var(--kodo-magenta)) 100%)',
  'gradient-aurora': 'linear-gradient(135deg, rgb(var(--kodo-cyan)) 0%, rgb(var(--kodo-lime)) 100%)',
}
```

### Box Shadows

```javascript
boxShadow: {
  'neon-cyan': '0 0 20px rgba(var(--kodo-cyan), 0.15)',
  'neon-magenta': '0 0 20px rgba(var(--kodo-magenta), 0.15)',
  'neon-lime': '0 0 20px rgba(var(--kodo-lime), 0.15)',
  'gaming': '0 10px 30px -10px rgba(0,0,0,0.5)',
  'glass': '0 8px 32px 0 rgba(0, 0, 0, 0.36)',
  'elevated': '0 20px 60px -10px rgba(0,0,0,0.6)',
}
```

### Backdrop Effects

```css
.backdrop-gaming {
  backdrop-filter: blur(12px) saturate(180%);
  background: rgba(var(--kodo-graphite), 0.7);
}

.backdrop-glass {
  backdrop-filter: blur(16px) saturate(200%);
  background: rgba(var(--kodo-slate), 0.4);
}
```

---

## 🌐 Background Patterns

### Body Background

```css
body {
  background-color: rgb(var(--kodo-void));
  background-image:
    radial-gradient(circle at 15% 0%, rgba(var(--kodo-cyan), 0.05) 0%, transparent 40%),
    radial-gradient(circle at 85% 100%, rgba(var(--kodo-magenta), 0.05) 0%, transparent 40%);
  background-attachment: fixed;
}
```

### Grid Pattern

```css
.bg-grid {
  background-image: 
    linear-gradient(rgba(var(--kodo-steel), 0.1) 1px, transparent 1px),
    linear-gradient(90deg, rgba(var(--kodo-steel), 0.1) 1px, transparent 1px);
  background-size: 20px 20px;
}
```

### Dot Pattern

```css
.bg-dots {
  background-image: radial-gradient(rgba(var(--kodo-steel), 0.3) 1px, transparent 1px);
  background-size: 16px 16px;
}
```

---

## 📱 Responsive Breakpoints

```javascript
screens: {
  'xs': '475px',
  'sm': '640px',
  'md': '768px',
  'lg': '1024px',
  'xl': '1280px',
  '2xl': '1536px',
}
```

### Usage

```css
/* Mobile First */
.component {
  @apply text-sm;
  
  @screen md {
    @apply text-base;
  }
  
  @screen lg {
    @apply text-lg;
  }
}
```

---

## ♿ Accessibilité

### Focus States

```css
/* Focus Ring */
.focus-ring {
  @apply focus:outline-none focus:ring-2 focus:ring-kodo-cyan focus:ring-offset-2 focus:ring-offset-kodo-void;
}

/* Focus Visible (keyboard only) */
.focus-visible-ring {
  @apply focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-kodo-cyan;
}
```

### Screen Reader Only

```css
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}
```

### Skip Links

```css
.skip-link {
  @apply sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50;
  @apply bg-kodo-cyan text-kodo-void px-4 py-2 rounded-lg font-bold;
}
```

---

## 🎯 États Interactifs

### Hover States

```css
/* Buttons */
.btn-hover {
  @apply transition-all duration-200;
  @apply hover:scale-105 hover:shadow-lg;
}

/* Cards */
.card-hover {
  @apply transition-all duration-300;
  @apply hover:border-kodo-cyan/40 hover:shadow-neon-cyan;
}

/* Links */
.link-hover {
  @apply text-kodo-secondary hover:text-kodo-cyan;
  @apply transition-colors duration-200;
}
```

### Active States

```css
.btn-active {
  @apply active:scale-95;
}

.link-active {
  @apply text-kodo-cyan font-semibold;
}
```

### Disabled States

```css
.disabled {
  @apply opacity-50 cursor-not-allowed;
  @apply pointer-events-none;
}
```

### Loading States

```css
.loading {
  @apply relative overflow-hidden;
}

.loading::after {
  content: '';
  @apply absolute inset-0;
  @apply bg-gradient-to-r from-transparent via-white/10 to-transparent;
  @apply animate-shimmer;
}
```

---

## 🎨 Thèmes & Modes

### Dark Mode (Default)

Déjà défini dans les variables CSS principales.

### Light Mode (Optionnel)

```css
[data-theme="light"] {
  --kodo-void: 255 255 255;
  --kodo-ink: 249 250 251;
  --kodo-graphite: 243 244 246;
  --kodo-slate: 229 231 235;
  --kodo-steel: 209 213 219;
  
  --kodo-text-main: 17 24 39;
  --kodo-content-highlight: 0 0 0;
  --kodo-content-dim: 107 114 128;
}
```

### High Contrast Mode

```css
[data-theme="high-contrast"] {
  --kodo-cyan: 0 255 255;
  --kodo-magenta: 255 0 255;
  --kodo-lime: 0 255 0;
  --kodo-red: 255 0 0;
  --kodo-gold: 255 255 0;
}
```

---

## 🔧 Utilitaires Personnalisés

### Scrollbar Styling

```css
::-webkit-scrollbar {
  width: 6px;
  height: 6px;
}

::-webkit-scrollbar-track {
  background: transparent;
}

::-webkit-scrollbar-thumb {
  background: rgb(var(--kodo-steel));
  border-radius: 99px;
}

::-webkit-scrollbar-thumb:hover {
  background: rgb(var(--kodo-cyan-dim));
}
```

### Text Selection

```css
::selection {
  background: rgb(var(--kodo-cyan) / 0.3);
  color: rgb(var(--kodo-content-highlight));
}
```

### Truncate Text

```css
.truncate-1 {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.truncate-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

.truncate-3 {
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  overflow: hidden;
}
```

---

## 📦 Structure de Fichiers Recommandée

```
design-system/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   └── index.ts
│   │   ├── Input/
│   │   │   ├── Input.tsx
│   │   │   ├── SearchInput.tsx
│   │   │   ├── FileUpload.tsx
│   │   │   └── index.ts
│   │   ├── Card/
│   │   ├── Badge/
│   │   ├── Avatar/
│   │   ├── Progress/
│   │   ├── Modal/
│   │   ├── Select/
│   │   ├── Checkbox/
│   │   ├── Switch/
│   │   ├── Tabs/
│   │   ├── Toast/
│   │   ├── Tooltip/
│   │   ├── Table/
│   │   ├── Accordion/
│   │   ├── Breadcrumb/
│   │   ├── Pagination/
│   │   ├── Skeleton/
│   │   ├── Spinner/
│   │   └── Divider/
│   ├── styles/
│   │   ├── index.css          # Global styles + CSS variables
│   │   ├── animations.css     # Animations
│   │   └── utilities.css      # Custom utilities
│   ├── tokens/
│   │   └── colors.ts          # Color tokens
│   ├── utils/
│   │   └── cn.ts              # Class name utility
│   └── index.ts               # Main export
├── tailwind.config.js
├── tsconfig.json
└── package.json
```

---

## 🚀 Installation & Usage

### Installation

```bash
npm install @veza/design-system
# or
yarn add @veza/design-system
```

### Import Styles

```tsx
// Dans votre fichier principal (App.tsx, main.tsx, etc.)
import '@veza/design-system/styles';
```

### Import Components

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

function MyComponent() {
  return (
    <Card variant="gaming">
      <Input label="Email" type="email" />
      <Button variant="primary">Submit</Button>
    </Card>
  );
}
```

---

## 📚 Composants Manquants à Implémenter

### Priorité Haute
- [ ] **Dropdown Menu** - Menu déroulant avec sous-menus
- [ ] **Popover** - Conteneur flottant pour contenu contextuel
- [ ] **Alert** - Messages d'alerte système
- [ ] **Banner** - Bannières d'information
- [ ] **Stepper** - Indicateur d'étapes
- [ ] **Rating** - Système de notation (étoiles)

### Priorité Moyenne
- [ ] **Slider** - Curseur de valeur
- [ ] **DatePicker** - Sélecteur de date
- [ ] **TimePicker** - Sélecteur d'heure
- [ ] **ColorPicker** - Sélecteur de couleur
- [ ] **Combobox** - Input avec autocomplétion
- [ ] **Command Palette** - Palette de commandes (Cmd+K)

### Priorité Basse
- [ ] **Calendar** - Calendrier complet
- [ ] **TreeView** - Vue arborescente
- [ ] **Carousel** - Carrousel d'images
- [ ] **Drawer** - Panneau latéral
- [ ] **ContextMenu** - Menu contextuel (clic droit)
- [ ] **Menubar** - Barre de menu

---

## 🎯 Composants Spécifiques Veza

### TrackList
```typescript
interface TrackListProps {
  tracks: Array<{
    id: string;
    title: string;
    artist: string;
    duration: number;
    coverUrl?: string;
  }>;
  onPlay?: (trackId: string) => void;
  variant?: 'compact' | 'detailed';
}
```

### StatCard
```typescript
interface StatCardProps {
  label: string;
  value: string | number;
  icon?: React.ReactNode;
  trend?: {
    value: number;
    direction: 'up' | 'down';
  };
  variant?: 'default' | 'gaming';
}
```

### NotificationBadge
```typescript
interface NotificationBadgeProps {
  count: number;
  max?: number;
  variant?: 'default' | 'dot';
  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
}
```

---

## 🔍 Exemples d'Usage

### Formulaire de Connexion

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

function LoginForm() {
  return (
    <Card variant="gaming" className="max-w-md mx-auto">
      <h2 className="text-h2 text-center mb-6">Connexion</h2>
      
      <form className="space-y-6">
        <Input
          label="Email"
          type="email"
          placeholder="votre@email.com"
        />
        
        <Input
          label="Mot de passe"
          type="password"
          placeholder="••••••••"
        />
        
        <Button variant="primary" className="w-full">
          Se connecter
        </Button>
      </form>
    </Card>
  );
}
```

### Dashboard Stats

```tsx
import { StatCard } from '@veza/design-system';
import { Users, Music, TrendingUp } from 'lucide-react';

function DashboardStats() {
  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
      <StatCard
        label="Total Users"
        value="12,345"
        icon={<Users />}
        trend={{ value: 12, direction: 'up' }}
        variant="gaming"
      />
      
      <StatCard
        label="Tracks Uploaded"
        value="8,901"
        icon={<Music />}
        trend={{ value: 8, direction: 'up' }}
        variant="gaming"
      />
      
      <StatCard
        label="Active Sessions"
        value="1,234"
        icon={<TrendingUp />}
        trend={{ value: 5, direction: 'down' }}
        variant="gaming"
      />
    </div>
  );
}
```

---

## 🎨 Guide de Contribution

### Ajouter un Nouveau Composant

1. **Créer la structure:**
```bash
mkdir src/components/MonComposant
touch src/components/MonComposant/MonComposant.tsx
touch src/components/MonComposant/index.ts
```

2. **Définir l'interface:**
```tsx
export interface MonComposantProps {
  variant?: 'default' | 'autre';
  size?: 'sm' | 'md' | 'lg';
  // ... autres props
}
```

3. **Implémenter le composant:**
```tsx
import React from 'react';
import { cn } from '../../utils/cn';

export const MonComposant = React.forwardRef<HTMLDivElement, MonComposantProps>(
  ({ variant = 'default', className, ...props }, ref) => {
    return (
      <div ref={ref} className={cn('base-styles', className)} {...props}>
        {/* Contenu */}
      </div>
    );
  }
);

MonComposant.displayName = 'MonComposant';
```

4. **Exporter:**
```tsx
// src/components/MonComposant/index.ts
export { MonComposant } from './MonComposant';
export type { MonComposantProps } from './MonComposant';
```

5. **Ajouter à l'index principal:**
```tsx
// src/index.ts
export { MonComposant } from './components/MonComposant';
export type { MonComposantProps } from './components/MonComposant';
```

---

## 📝 Checklist de Génération

Lors de la génération du design system, s'assurer que:

- [ ] Toutes les variables CSS sont définies dans `styles/index.css`
- [ ] La configuration Tailwind est complète avec toutes les extensions
- [ ] Tous les composants de base sont implémentés
- [ ] Les composants utilisent `React.forwardRef` pour les refs
- [ ] Les interfaces TypeScript sont exportées
- [ ] L'utilitaire `cn()` est disponible pour fusionner les classes
- [ ] Les animations sont définies dans le CSS global
- [ ] Les gradients et shadows sont configurés dans Tailwind
- [ ] Les polices sont importées (Google Fonts ou local)
- [ ] Le package.json contient toutes les dépendances
- [ ] Les peer dependencies sont correctement spécifiées
- [ ] Un fichier README.md est présent avec la documentation
- [ ] Les exemples d'usage sont fournis
- [ ] Le système est responsive (mobile-first)
- [ ] L'accessibilité est prise en compte (ARIA, focus states)
- [ ] Les tests unitaires sont en place (optionnel mais recommandé)

---

## 🔗 Dépendances Requises

### Dependencies

```json
{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "lucide-react": "^0.294.0",
    "clsx": "^2.0.0",
    "tailwind-merge": "^2.0.0"
  }
}
```

### DevDependencies

```json
{
  "devDependencies": {
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "typescript": "^5.0.0",
    "tailwindcss": "^3.3.0",
    "autoprefixer": "^10.4.0",
    "postcss": "^8.4.0"
  }
}
```

---

## 🎯 Conclusion

Ce document de référence contient **TOUTES** les spécifications nécessaires pour générer un design system Kōdō complet et autonome. Il peut être utilisé pour:

1. ✅ Générer le design system dans un package séparé
2. ✅ Importer le design system dans n'importe quel projet
3. ✅ Maintenir la cohérence visuelle à travers tous les projets
4. ✅ Faciliter la collaboration entre designers et développeurs
5. ✅ Accélérer le développement de nouvelles features

**Prochaines étapes:**
1. Utiliser ce document pour générer le package `@veza/design-system`
2. Publier le package sur npm (ou registry privé)
3. Importer dans les projets Veza, Talas, etc.
4. Itérer et améliorer en fonction des besoins

---

**Version:** 1.0.0  
**Dernière mise à jour:** 2026-01-04  
**Auteur:** Kōdō Design Team