veza/docs/archive/root-md/DESIGN_SYSTEM_REFERENCE.md

🎨 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
2. Typographie
3. Espacements & Grilles
4. Composants UI
5. Animations & Transitions
6. Thèmes & Variantes
7. Icônes & Assets
8. États & Interactions
9. Responsive Design
10. Accessibilité

---

🎨 Palette de Couleurs

Spectre Astral (Palette Principale)

Neutrals (Backgrounds & Surfaces)

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

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

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

Text Colors

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

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

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

.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

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

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

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

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

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

variant="ghost"
// Styles: bg-transparent
// Text: text-gray-400
// Hover: text-white bg-white/5

Gaming - Style gaming/tech

variant="gaming"
// Styles: bg-kodo-slate border border-kodo-gold/40
// Text: text-kodo-gold uppercase tracking-wider

Terminal - Style code/terminal

variant="terminal"
// Styles: bg-kodo-ink border border-kodo-steel
// Text: text-gray-300 font-mono text-xs

Nature - Style organique

variant="nature"
// Styles: bg-kodo-slate border border-kodo-lime/30
// Text: text-kodo-lime

Icon - Bouton icône uniquement

variant="icon"
// Styles: bg-transparent rounded-full p-2
// Hover: bg-white/10

Tailles

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

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

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

Styles de base:

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

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

Styles:

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

FileUpload

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

Styles:

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

bg-kodo-graphite
border border-kodo-steel/60
p-6
hover:border-kodo-steel

Manga - Style créatif/artistique

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

bg-kodo-ink
border border-kodo-cyan/20
hover:border-kodo-cyan/40
hover:shadow-neon-cyan/10

Glass - Glassmorphism

bg-kodo-slate/40
backdrop-blur-xl
border border-white/5
hover:bg-kodo-slate/50

Props Interface

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

---

4. Badge

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

Variantes:

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

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

Tailles:

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:

online: bg-kodo-lime
offline: bg-gray-500
away: bg-kodo-gold
busy: bg-kodo-red

---

6. Progress Bar

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

Variantes:

default: bg-kodo-cyan
success: bg-kodo-lime
warning: bg-kodo-gold
error: bg-kodo-red

---

7. Modal / Dialog

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

Overlay:

bg-kodo-void/80
backdrop-blur-sm

Content:

bg-kodo-graphite
border border-kodo-steel
rounded-2xl
shadow-2xl

---

8. Dropdown / Select

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

Styles:

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

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

Styles:

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

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

Styles:

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

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

Variantes:

Default:

border-b border-kodo-steel
active:border-b-2 border-kodo-cyan

Pills:

bg-kodo-graphite
active:bg-kodo-cyan active:text-kodo-void
rounded-lg

Underline:

border-b-2 border-transparent
active:border-kodo-cyan

---

12. Toast / Notification

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

Variantes:

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

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

Styles:

bg-kodo-ink
border border-kodo-steel
text-sm
rounded-lg
px-3 py-2
shadow-xl

---

14. Table

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

Styles:

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

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

Styles:

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

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

Styles:

text-kodo-secondary
hover:text-kodo-cyan
active:text-white font-semibold

---

17. Pagination

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

Styles:

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

---

18. Skeleton Loader

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

Styles:

bg-kodo-graphite
animate-pulse
rounded

---

19. Spinner / Loading

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

Variantes:

default: border-kodo-cyan border-t-transparent animate-spin
dots: bg-kodo-cyan animate-bounce
bars: bg-kodo-cyan animate-pulse

---

20. Divider

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

Styles:

bg-kodo-steel
h-px (horizontal)
w-px (vertical)

---

🎭 Animations & Transitions

Animations Personnalisées

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

.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

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

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

.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

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

.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

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

---

📱 Responsive Breakpoints

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

Usage

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

---

♿ Accessibilité

Focus States

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

.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

.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

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

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

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

Disabled States

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

Loading States

.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)

[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

[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

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

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

Truncate Text

.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

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

Import Styles

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

Import Components

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

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

StatCard

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

NotificationBadge

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

---

🔍 Exemples d'Usage

Formulaire de Connexion

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

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:

mkdir src/components/MonComposant
touch src/components/MonComposant/MonComposant.tsx
touch src/components/MonComposant/index.ts

2. Définir l'interface:

export interface MonComposantProps {
  variant?: 'default' | 'autre';
  size?: 'sm' | 'md' | 'lg';
  // ... autres props
}

3. Implémenter le composant:

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:

// src/components/MonComposant/index.ts
export { MonComposant } from './MonComposant';
export type { MonComposantProps } from './MonComposant';

5. Ajouter à l'index principal:

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

{
  "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

{
  "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