veza/apps/web/docs/DESIGN_TOKENS.md

Design Tokens — Référence

Source de vérité pour les tokens du design system Veza/Kodo. Toute valeur d’espacement, couleur, ombre, typographie ou transition doit s’appuyer sur ces tokens ou sur l’échelle Tailwind documentée ici.

1. Espacements (layout et sections)

Définis dans index.css (:root) et design-tokens.css (scale Tailwind).

Variable	Valeur	Rôle
--layout-gap	1rem (16px)	Gap par défaut entre sections (align Tailwind gap-4)
--layout-gap-sm	0.75rem (12px)	Gap serré (gap-3)
--layout-gap-lg	1.5rem (24px)	Gap large (gap-6)

Scale complète (4px base) : voir SPACING_GUIDE.md et design-tokens.css (--spacing-0 à --spacing-96). Utiliser les classes Tailwind gap-*, p-*, m-*, space-* de préférence aux valeurs arbitraires.

2. Couleurs

• Kodo (primaire) : index.css — --background, --foreground, --primary, --muted, --border, etc.
• Sidebar : --sidebar, --sidebar-foreground, --sidebar-primary, etc. (index.css).
• Mapping et usage : src/styles/COLOR_USAGE.md.

Ne pas utiliser les couleurs par défaut Tailwind (slate, gray, zinc, etc.) ; privilégier les tokens Kodo (kodo-void, kodo-cyan, etc.).

3. Typographie

Échelle Tailwind utilisée (tailles de texte) :

Classe	Taille (rem)	Usage
text-xs	0.75rem	Caption, labels secondaires
text-sm	0.875rem	Labels, métadonnées
text-base	1rem	Corps de texte
text-lg	1.125rem	Sous-titres
text-xl	1.25rem	Titres de section
text-2xl	1.5rem	Titres de page
text-3xl	1.875rem	Titres principaux
text-4xl	2.25rem	Hero / titres très visibles

Line-height et font-weight : suivre les utilitaires Tailwind (leading-*, font-normal, font-medium, font-semibold, font-bold). Ne pas utiliser de tailles arbitraires (text-[14px], etc.) sauf exception documentée (ex. SVG charts).

Classes utilitaires typographiques (index.css @layer utilities)

Classe	Définition	Usage
.text-display	text-4xl font-bold tracking-tight	Hero / titres très visibles
.text-heading-1	text-3xl font-semibold tracking-tight	Titre principal de page (H1)
.text-heading-2	text-2xl font-semibold	Titre de section (H2)
.text-heading-3	text-xl font-medium	Sous-section (H3)
.text-heading-4	text-lg font-medium	Sous-titre (H4)
.text-body-lg	text-base leading-relaxed	Corps de texte élargi
.text-body	text-sm leading-relaxed	Corps de texte standard
.text-caption	text-xs text-muted-foreground	Légendes, durées, timestamps
.text-label	text-xs font-medium uppercase tracking-wider text-muted-foreground	Labels de champs

Utiliser ces classes en priorité pour les headings et body text. Ajouter font-display séparément si la police Orbitron est souhaitée.

Hiérarchie visuelle (usage recommandé)

Rôle	Classe	Contexte
Titre de page	.text-heading-1 (ou .text-display pour hero)	H1 de la page (Dashboard, Playlists, etc.)
Sous-titre / section	.text-heading-2 ou .text-heading-3	Titres de blocs
Label / métadonnée	.text-label ou text-sm	Labels de champs, infos secondaires
Corps	.text-body-lg ou .text-body	Texte courant
Caption / timestamps	.text-caption	Légendes, durées, timestamps

Contraste : privilégier text-foreground pour l’info principale et text-muted-foreground pour l’info secondaire (style Spotify : titre + artiste, description en gris).

Exceptions (tailles arbitraires typo)

• Avatar size xs : le composant avatar.tsx utilise text-[10px] pour les initiales en taille xs (w-6 h-6) pour garder une proportion lisible. Exception documentée — ne pas remplacer par text-xs dans ce cas.
• Badge : la doc du composant badge mentionne text-[10px] comme référence de style ; les usages réels du composant utilisent l’échelle (ex. text-xs).

4. Ombres

Définies dans design-system.css.

Variable	Rôle
--shadow-sm	Ombres légères
--shadow-md	Ombres moyennes, tooltips
--shadow-lg	Cartes surélevées
--shadow-xl	Modales
--shadow-soft	Ombres douces
--shadow-card	Cartes (alias --shadow-soft)
--shadow-modal	Modales (alias --shadow-xl)
--shadow-tooltip	Tooltips (alias --shadow-md)

Classes utilitaires dans index.css : .shadow-card, .shadow-modal, .shadow-tooltip, .shadow-card-hover, .shadow-card-glow-cyan, .shadow-card-glow-magenta. Tokens additionnels : --sidebar-active-indicator, --button-primary-glow, --button-primary-glow-hover, --player-thumb-glow, --player-hover-glow, --queue-item-current-glow, --slider-thumb-glow, --status-dot-glow-cyan, --status-dot-glow-lime, --status-dot-glow-magenta (design-system.css) avec classes .sidebar-active-indicator, .shadow-button-primary-glow, .shadow-button-primary-glow-hover, .shadow-player-thumb, .shadow-player-hover, .shadow-queue-item-current, .shadow-slider-thumb, .shadow-status-dot-cyan, .shadow-status-dot-lime, .shadow-status-dot-magenta. Couverture / hero : --shadow-cover-depth (.shadow-cover-depth). Gaming / XP : --shadow-gold-glow (.shadow-gold-glow). FAB : --shadow-fab-glow, --shadow-fab-glow-hover (.shadow-fab-glow, .shadow-fab-glow-hover).

5. Layout shell (sidebar, header, main)

Définis dans index.css. Référence complète : APP_SHELL.md.

• Sidebar : --sidebar-width-expanded, --sidebar-width-collapsed, --sidebar-offset-*, --sidebar-z-index.
• Header : --header-height, --header-left-expanded, --header-left-collapsed.
• Main : --main-offset-top, --main-offset-bottom, --main-margin-left-expanded, --main-margin-left-collapsed.
• Max heights (drawers, panels, lists) : --layout-drawer-max-height (60vh), --layout-panel-max-height (70vh), --layout-list-max-height (25rem) — classes .max-h-layout-drawer, .max-h-layout-panel, .max-h-layout-list.
• Modales : --layout-modal-max-height (85vh), --layout-modal-max-height-sm (80vh), --layout-modal-max-height-xs (70vh), --layout-modal-max-height-lg (90vh) — classes .max-h-layout-modal, .max-h-layout-modal-sm, .max-h-layout-modal-xs, .max-h-layout-modal-lg.
• Lyrics / hero : --layout-lyrics-height (60vh), --layout-lyrics-height-sm (50vh) — classes .h-layout-lyrics, .h-layout-lyrics-sm.
• Chat / full-page : --layout-chat-height (calc(100vh - 6.25rem)), --layout-chat-main-height (calc(100vh - 6rem)), --layout-stream-height (calc(100vh - 6rem)), --layout-modal-full-height (calc(100vh - 2rem)) — classes .h-layout-chat, .h-layout-chat-main, .h-layout-stream, .h-layout-modal-full.

Ne pas définir de variables concurrentes (ex. --sidebar-width, --header-height) ailleurs ; index.css est la source unique pour le shell.

6. Transitions et animations

Définies dans design-system.css.

Variable	Valeur	Usage
--duration-instant	100ms	Feedback immédiat
--duration-fast	150ms	Hover, focus
--duration-normal	250ms	Sidebar, modales
--duration-immersive	200ms	Micro-interactions (hover, focus)
--duration-slow	400ms	Animations visibles
--duration-slower	600ms	Transitions longues
--ease-out	cubic-bezier(0.33, 1, 0.68, 1)	Sortie
--ease-in-out	cubic-bezier(0.65, 0, 0.35, 1)	Entrée/sortie
--ease-bounce	cubic-bezier(0.34, 1.56, 0.64, 1)	Rebond
--ease-spring	cubic-bezier(0.175, 0.885, 0.32, 1.275)	Spring

Utiliser ces variables dans les transitions (ex. transition-all var(--duration-normal) var(--ease-out)).

7. Exceptions (valeurs arbitraires)

Les règles ESLint interdisent les classes arbitraires pour w-[...], h-[...], rounded-[...], shadow-[...], etc. Exceptions autorisées avec commentaire eslint-disable :

• SVG ou canvas (ex. text-[2px] pour axes de graphiques).
• Composants tiers dont on ne contrôle pas le markup.
• Cas documentés dans ce fichier ou en PR avec justification.

Voir aussi : .cursorrules (layout primitives, pas de valeurs arbitraires pour espacements/tailles).