veza/docs/archive/root-md/DESIGN_SYSTEM_REFERENCE.md
senke 43af35fd93 chore(audit 2.2, 2.3): nettoyer .md et .json à la racine
- Archiver 131 .md dans docs/archive/root-md/
- Archiver 22 .json dans docs/archive/root-json/
- Conserver 7 .md utiles (README, CONTRIBUTING, CHANGELOG, etc.)
- Conserver package.json, package-lock.json, turbo.json
- Ajouter README d'index dans chaque archive
2026-02-15 14:35:08 +01:00

1549 lines
30 KiB
Markdown

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