4305d66aa2
- .storybook/main.ts: add viteFinal with allowedHosts for veza.fr/com domains - DESIGN_TOKENS.md: document modal max-height tokens and typography exceptions (avatar xs text-[10px]) - capture-visual-baseline.mjs: fix locator selectors for sidebar and player captures Co-authored-by: Cursor <cursoragent@cursor.com>
116 lines
7.2 KiB
Markdown
116 lines
7.2 KiB
Markdown
# 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](../src/index.css) (`:root`) et [design-tokens.css](../src/styles/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](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](../src/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](../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).
|
||
|
||
### Exceptions (tailles arbitraires typo)
|
||
|
||
- **Avatar size `xs`** : le composant [avatar.tsx](../src/components/ui/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](../src/styles/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](../src/index.css). Référence complète : [APP_SHELL.md](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`.
|
||
|
||
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](../src/styles/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](../.cursorrules) (layout primitives, pas de valeurs arbitraires pour espacements/tailles).
|