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

Hiérarchie visuelle (usage recommandé)

Rôle	Classe	Contexte
Titre de page	text-2xl ou text-3xl + font-bold	H1 de la page (Dashboard, Playlists, etc.)
Sous-titre / section	text-lg ou text-xl	Titres de blocs
Label / métadonnée	text-sm	Labels de champs, infos secondaires
Corps	text-base	Texte courant
Caption / timestamps	text-xs	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).

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.

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