veza/docs/archive/root-md/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

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

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

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

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

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

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

.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