veza/SUMI_DESIGN_SYSTEM.md

# VEZA SUMI Design System — Source de Vérité

> **Version:** 1.0
> **Philosophie:** Encre sur papier. Chaque surface est une feuille, chaque accent un coup de pinceau délibéré. L'espace (間 ma) est sacré.

---

## 1. PRINCIPES FONDAMENTAUX

### Les 6 règles inviolables

1. **Encre, pas néon** — Les couleurs sont des pigments, pas des lumières. Quand tout brille, rien ne se distingue. Le glow est UNIQUEMENT pour les focus rings.
2. **Espace sacré (Ma 間)** — Spacing généreux, densité maîtrisée. Ce qui n'est pas là est aussi important que ce qui y est.
3. **Universalité** — Lisible pour tous (8 ans–80 ans, auditeur casual–label pro). Pas de dark pattern, pas de complexité gratuite.
4. **Wabi-sabi numérique** — Authenticité > perfection stérile. Personnalité dans les détails, pas dans les effets.
5. **Révélation progressive** — Simple pour l'auditeur, profond pour le label. Les fonctions avancées se révèlent au fur et à mesure.
6. **Thèmes comme épices** — Gaming (XP, achievements), cyber (monospace, terminal), graffiti (chips, tags) = 5% de l'UI, 100% de la personnalité.

### Thèmes absorbés

| Thème | Comment il se manifeste | Où dans l'UI |
|-------|------------------------|--------------|
| Fusain / Lavis japonais | Couleurs chaudes, tons d'encre, espace | **Partout** — c'est le langage visuel de base |
| Nature / Botanical | Sauge comme couleur success, tons terreux | Badges, états online/success |
| Cybersec / Linux | JetBrains Mono, terminal blocks, stats mono | Stats, analytics, terminal, durées |
| Jeux vidéo 2D | XP bar, achievements, animation pop | Gamification, récompenses |
| Graffiti / Tag | Chips genre, tags, énergie gestuelle | Tags musicaux, filtres, catégories |
| Musique indé | Authenticité, imperfection, warmth | Ton général, pas de clinquant |

---

## 2. PALETTE COULEURS

### Principe: 4 pigments, c'est TOUT

La palette repose sur des neutres chauds (90% de l'UI) et 4 couleurs d'accent intentionnelles. Pas 50 variables. Pas de neon.

### Dark Theme (défaut)

#### Backgrounds — Couches d'encre
```css
--sumi-bg-void:      #0c0c0f;    /* Deepest — behind everything */
--sumi-bg-base:      #121215;    /* Primary — main content */
--sumi-bg-raised:    #1a1a1f;    /* Cards, sidebar */
--sumi-bg-overlay:   #222228;    /* Dropdowns, modals */
--sumi-bg-hover:     #2a2a31;    /* Hover states */
--sumi-bg-active:    #32323a;    /* Active/pressed */
--sumi-bg-wash:      #18181d;    /* Subtle tinted bg */
```

#### Surfaces
```css
--sumi-surface-inset:    #101013;    /* Search bars, inputs */
--sumi-surface-subtle:   #1e1e24;    /* Table row alternate */
--sumi-surface-card:     #1a1a1f;    /* Standard card */
--sumi-surface-elevated: #242430;    /* FAB, sticky headers */
```

#### Borders
```css
--sumi-border-faint:     rgba(255, 255, 255, 0.06);    /* Subtle separation */
--sumi-border-default:   rgba(255, 255, 255, 0.10);    /* Standard */
--sumi-border-strong:    rgba(255, 255, 255, 0.16);    /* Emphasized */
--sumi-border-focus:     rgba(139, 170, 220, 0.50);    /* Focus rings */
--sumi-border-accent:    rgba(139, 170, 220, 0.30);    /* Accent borders */
```

#### Text — Densités d'encre
```css
--sumi-text-primary:     #f0ede8;    /* Warm white — titres, contenu principal */
--sumi-text-secondary:   #a8a4a0;    /* Descriptions, métadonnées */
--sumi-text-tertiary:    #706c68;    /* Timestamps, captions */
--sumi-text-disabled:    #4a4844;    /* Disabled */
--sumi-text-inverse:     #121215;    /* Sur fonds accent */
--sumi-text-link:        #8baade;    /* Liens */
```

#### Les 4 Pigments d'accent

| Pigment | Nom | Variable | Usage |
|---------|-----|----------|-------|
| 藍墨 Indigo Ink | `--sumi-accent` | `#7c9dd6` | Primaire — boutons, active, focus, navigation |
| 朱印 Vermillion Seal | `--sumi-vermillion` | `#d4634a` | Danger — erreurs, destructif, notifications, live |
| 草墨 Sage | `--sumi-sage` | `#7a9e6c` | Success — online, validé, nature |
| 金墨 Gold Leaf | `--sumi-gold` | `#c9a84c` | Reward — XP, achievements, premium, warnings |

Chaque pigment a 3 variantes : `base`, `hover`, `subtle` (ex: `--sumi-accent-subtle`).

#### Semantic mapping
```css
--sumi-success   → --sumi-sage
--sumi-warning   → --sumi-gold
--sumi-error     → --sumi-vermillion
--sumi-info      → --sumi-accent
--sumi-live      → #e05a5a
--sumi-online    → --sumi-sage
```

### Light Theme ("Washi Paper" 和紙)

Même structure, pigments ajustés pour le fond clair. Backgrounds deviennent des tons papier chaud (cream, off-white, PAS blanc pur froid).

```css
--sumi-bg-void:      #f0ece4;    /* Washi aged */
--sumi-bg-base:      #f6f3ed;    /* Rice paper */
--sumi-bg-raised:    #ffffff;    /* Cards pop sur cream */
--sumi-text-primary: #1a1816;    /* Charcoal chaud */
--sumi-accent:       #4a6fa5;    /* Indigo profond */
--sumi-vermillion:   #b84a35;    /* Plus foncé sur clair */
--sumi-sage:         #5a7e4e;
--sumi-gold:         #9a7d2e;
```

---

## 3. TYPOGRAPHIE

### 3 polices, pas plus

| Police | Rôle | Variable | Usage |
|--------|------|----------|-------|
| **Inter** | Corps | `--sumi-font-body` | Tout le texte courant, labels, descriptions |
| **Space Grotesk** | Titres | `--sumi-font-heading` | H1–H4, display, noms de section |
| **JetBrains Mono** | Données | `--sumi-font-mono` | Stats, durées, code, terminal, compteurs |
| *Noto Serif JP* | *Décoratif* | `--sumi-font-serif` | *Easter eggs, citations japonaises (rare)* |

### Échelle typographique

| Classe | Taille | Font | Weight | Usage |
|--------|--------|------|--------|-------|
| `.sumi-display` | 2.25rem (36px) | Heading | 700 | Hero, landing |
| `.sumi-h1` | 1.875rem (30px) | Heading | 600 | Titre de page |
| `.sumi-h2` | 1.5rem (24px) | Heading | 600 | Section |
| `.sumi-h3` | 1.25rem (20px) | Heading | 500 | Sous-section |
| `.sumi-h4` | 1.125rem (18px) | Heading | 500 | Sous-titre |
| `.sumi-body-lg` | 1rem (16px) | Body | 400 | Texte important |
| `.sumi-body` | 0.875rem (14px) | Body | 400 | Texte standard |
| `.sumi-body-sm` | 0.8125rem (13px) | Body | 400 | Texte compact |
| `.sumi-caption` | 0.75rem (12px) | Body | 400 | Timestamps, captions |
| `.sumi-label` | 0.75rem (12px) | Body | 500 | Labels uppercase |
| `.sumi-mono` | 0.8125rem (13px) | Mono | 400 | Stats, durées |

### Règle de contraste texte

- **Info principale** → `text-primary` (titres, noms, contenu)
- **Info secondaire** → `text-secondary` (artiste sous le titre, descriptions)
- **Info tertiaire** → `text-tertiary` (timestamps, durées, captions)
- **Données chiffrées** → `font-mono` toujours (12,847 streams, 3:42, +23.4%)

---

## 4. SPACING

Base 4px. Utiliser les classes Tailwind mappées aux tokens.

| Token | Valeur | Usage typique |
|-------|--------|---------------|
| `space-1` | 4px | Micro gaps entre icône et texte |
| `space-2` | 8px | Padding tight, gap d'icônes |
| `space-3` | 12px | Padding d'inputs, petits gaps |
| `space-4` | 16px | **Padding de carte standard**, gap grille |
| `space-5` | 20px | |
| `space-6` | 24px | Padding de section |
| `space-8` | 32px | Margins entre sections |
| `space-12` | 48px | Gap entre grandes sections de page |
| `space-16` | 64px | Margins majeurs de page |

---

## 5. BORDER RADIUS

| Token | Valeur | Usage |
|-------|--------|-------|
| `radius-xs` | 4px | Tags, petits éléments |
| `radius-sm` | 6px | Badges, chips |
| `radius-md` | 8px | **Défaut** — buttons, inputs, covers |
| `radius-lg` | 12px | **Cards**, terminaux, menus |
| `radius-xl` | 16px | Modales, grandes cartes |
| `radius-2xl` | 20px | Hero sections |
| `radius-full` | 9999px | Avatars, pills, toggles |

---

## 6. SHADOWS

| Token | Usage |
|-------|-------|
| `shadow-xs` | Inputs, badges |
| `shadow-sm` | Cards au repos |
| `shadow-md` | Cards hover, tooltips |
| `shadow-lg` | Dropdowns, popovers |
| `shadow-xl` | Modales, drawers |
| `shadow-2xl` | Full-screen overlays |
| `shadow-glow` | **Focus rings uniquement** — JAMAIS décoratif |

---

## 7. TRANSITIONS

| Token | Durée | Usage |
|-------|-------|-------|
| `duration-instant` | 75ms | Feedback clavier |
| `duration-fast` | 150ms | Hover, focus |
| `duration-normal` | 200ms | Transitions standard |
| `duration-slow` | 300ms | Modales, sidebar |
| `duration-slower` | 500ms | Achievements uniquement |

### Easings
- `ease-default` — Standard pour tout
- `ease-out` — Entrée d'éléments (slide-up, scale-in)
- `ease-in` — Sortie (fermeture)
- `ease-bounce` — **Achievements seulement** — jamais ailleurs
- `ease-spring` — Toast notifications

### Animations disponibles
```
sumi-fade-in, sumi-fade-out
sumi-slide-up, sumi-slide-down
sumi-scale-in, sumi-scale-out
sumi-pop          ← Achievements uniquement
sumi-pulse        ← Live indicator uniquement
sumi-brush-reveal ← Page transitions (optionnel)
```

---

## 8. COMPOSANTS

### Primitives (utilisés partout)

| Composant | Classe | Description |
|-----------|--------|-------------|
| Card | `.sumi-card` | Surface élevée avec border subtile. Variantes: `--interactive`, `--elevated` |
| Button | `.sumi-btn` | 4 variantes: `--primary`, `--secondary`, `--ghost`, `--danger`. Tailles: `--xs`, `--sm`, default, `--lg`, `--icon` |
| Input | `.sumi-input` | Fond inset, border default, focus glow |
| Badge | `.sumi-badge` | Pill. Variantes: `--default`, `--accent`, `--success`, `--warning`, `--error`, `--live` |
| Chip | `.sumi-chip` | Tag/genre. Variante: `--selected`. (Touche graffiti) |
| Avatar | `.sumi-avatar` | Cercle. Tailles: `--xs` à `--2xl`. Status: `--online`, `--live` |
| Menu | `.sumi-menu` | Dropdown. Items: `__item`, `__item--active`, `__item--danger` |
| Modal | `.sumi-modal` | Centré, backdrop blur, scale-in animation |
| Toast | `.sumi-toast` | Notification slide-up |
| Tooltip | `.sumi-tooltip` | Petit, md shadow |
| Tabs | `.sumi-tabs` / `.sumi-tab` | Border-bottom active indicator |
| Toggle | `.sumi-toggle` | Switch on/off |
| Divider | `.sumi-divider` | Ligne border-faint |

### Spécialités thématiques

| Composant | Classe | Thème | Usage |
|-----------|--------|-------|-------|
| XP Bar | `.sumi-xp-bar` | 🎮 Gaming | Progression utilisateur |
| Achievement | `.sumi-achievement` | 🎮 Gaming | Toast de récompense (animation pop) |
| Terminal | `.sumi-terminal` | 💻 Cyber | Stats avancées, analytics developer |
| Track List | `.sumi-track` | 🎵 Music | Liste de morceaux avec état playing |
| Stat Card | `.sumi-stat` | 📊 Data | Dashboard analytics (mono numbers) |
| Cover Art | `.sumi-cover` | 🎵 Music | Album art avec tailles |
| Live Dot | `.sumi-live-dot` | 📡 Stream | Indicateur live pulsant |
| Slider | `.sumi-slider` | 🎧 Player | Progress bar avec thumb au hover |

### Glass Panel
```css
.sumi-glass {
  background: var(--sumi-glass-bg);
  backdrop-filter: blur(12px);
  border: 1px solid var(--sumi-glass-border);
}
```
Usage: **Player bar, header sticky, floating panels**. PAS pour les cartes normales.

---

## 9. LAYOUT SHELL

| Zone | Dimension | Background |
|------|-----------|------------|
| Sidebar | 240px expanded / 64px collapsed | `bg-raised` |
| Header | 56px height | Glass (blur) |
| Main | Padding top: header+24px, bottom: player+24px | `bg-base` |
| Player | 80px height, full-width | Glass (blur) |

### Responsive
- **≥ 1024px (lg)** — Sidebar fixe, main avec margins tokenisées
- **< 1024px** — Sidebar overlay, main pleine largeur

### Z-Index Scale
```
base:     0
raised:   10
dropdown: 100
sticky:   200    ← Sidebar, header, player
overlay:  300
modal:    400
popover:  500
toast:    600
tooltip:  700
max:      999
```

---

## 10. ANTI-PATTERNS — INTERDIT

| ❌ Ne JAMAIS faire | ✅ Faire à la place |
|---|---|
| Couleurs Tailwind (slate, zinc, gray) | Tokens `--sumi-*` |
| Glow/neon décoratif | Glow uniquement pour focus rings |
| Orbitron ou font gaming | Space Grotesk pour headings |
| Clip-path manga/hex | Border-radius standard |
| Plus de 4 accents | Indigo, Vermillon, Sauge, Or |
| Gradient sur composants | Gradient uniquement hero/cover |
| Box-shadow décoratif | Shadow = élévation fonctionnelle |
| Animations > 300ms | Max 300ms sauf achievements |
| Valeurs CSS arbitraires | Tokens et échelle Tailwind |
| `!important` sauf utilitaires | Spécificité CSS normale |
| Neon flicker, matrix, terminal green text | Subtilité, discrétion |

---

## 11. CHECKLIST COMPOSANT

Avant de merger un composant, vérifier :

- [ ] Utilise uniquement des tokens `--sumi-*`
- [ ] Fonctionne en dark ET light theme
- [ ] Responsive (testé à 320px, 768px, 1024px, 1280px)
- [ ] Focus visible avec `shadow-glow`
- [ ] Pas plus de 2 fonts utilisées
- [ ] Pas d'animation > 300ms (sauf achievement)
- [ ] Contrast ratio ≥ 4.5:1 pour le texte
- [ ] Pas de valeur CSS arbitraire
- [ ] States couverts : default, hover, active, focus, disabled
- [ ] Données chiffrées en `font-mono`

---

## 12. MIGRATION DEPUIS L'EXISTANT

### Mapping ancien → nouveau

| Ancien (Kōdō/Fusion) | Nouveau (Sumi) |
|---|---|
| `--kodo-void` / `--veza-void` | `--sumi-bg-void` |
| `--kodo-ink` / `--veza-ink` | `--sumi-bg-base` |
| `--kodo-graphite` | `--sumi-bg-raised` |
| `--kodo-cyan` / `--veza-cyan` | `--sumi-accent` |
| `--kodo-magenta` / `--veza-magenta` | **Supprimé** — utiliser `--sumi-vermillion` si danger |
| `--kodo-lime` / `--veza-lime` | **Supprimé** — utiliser `--sumi-sage` si success |
| `--kodo-gold` / `--veza-xp-gold` | `--sumi-gold` |
| `--kodo-red` / `--veza-error` | `--sumi-vermillion` |
| `--glass-hud-bg` | `--sumi-glass-bg` |
| `--glow-cyan`, `--glow-magenta` etc. | **Supprimé** — un seul `--sumi-shadow-glow` pour focus |
| `.clip-manga`, `.clip-hex` | **Supprimé** |
| `.animate-neon-flicker` | **Supprimé** |
| `.backdrop-blur-cyber` | `.sumi-glass` |
| `font-display` (Orbitron) | `font-heading` (Space Grotesk) |

### Ordre de migration recommandé

1. Remplacer les tokens CSS (search & replace global)
2. Supprimer les fichiers `design-system.css` et `design-tokens.css` anciens
3. Intégrer le nouveau fichier de tokens
4. Migrer les composants un par un en commençant par le shell (sidebar, header, player)
5. Puis les primitives (buttons, inputs, cards)
6. Puis les pages

---

*墨は心の鏡 — L'encre est le miroir du cœur*