66a56409ad
Plan UI premium 6–8 semaines (design system, shell, Storybook, a11y): - Design system: DESIGN_TOKENS.md, APP_SHELL.md, FULL_LAYOUT_PAGE.md. Single source for layout/shell (index.css), shadows (design-system.css), durations/easing. - Tokens: shadow-cover-depth, shadow-gold-glow, shadow-fab-glow; layout max-height (max-h-layout-drawer, max-h-layout-panel, max-h-layout-list). All duration-200/300/500 replaced by --duration-fast/normal/slow. Arbitrary shadows replaced by token classes. - Shell & player: Sidebar, Header, GlobalPlayer, MiniPlayer, PlayerQueue, PlayerControls, AudioPlayer use tokens; focus-visible on Sidebar, PlayerQueue, DropdownMenuTrigger/Item, TabsTrigger. Typography: text-[10px]/[9px] → text-xs where applicable. - ESLint: no-restricted-syntax (warn) for w-/h-/rounded-/shadow-/text-/spacing arbitrary. - Scripts: report-arbitrary-values.mjs, capture/compare/generate visual; visual-complete.spec.ts. - Stories full layout: Dashboard, Playlists, Library, Settings, Profile in DashboardLayout.stories. - .cursorrules + README: DESIGN_TOKENS, APP_SHELL, visual commands, no arbitrary without justification. - apps/web/.gitignore: e2e test artifacts (test-results-visual, playwright-report-visual). Co-authored-by: Cursor <cursoragent@cursor.com>
109 lines
6.3 KiB
Markdown
109 lines
6.3 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).
|
||
|
||
## 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`.
|
||
|
||
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).
|