2026-02-05 13:15:55 +00:00
# Règles de Développement UI - Projet SaaS
2026-03-03 08:25:34 +00:00
## 0. Scope v0.901 (priorité absolue)
2026-02-19 22:39:40 +00:00
2026-03-03 08:25:34 +00:00
- **Référence** : `docs/V0_901_RELEASE_SCOPE.md` et `docs/SCOPE_CONTROL.md`
- Avant toute modification : vérifier si le changement est **dans le scope v0.901**
- **v0.803 livré** : Voir `docs/archive/V0_803_RELEASE_SCOPE.md`
2026-02-19 22:39:40 +00:00
- **Interdit** : nouvelles routes/pages hors scope, nouvelles dépendances (sauf correctif sécurité)
- En cas de doute : ne pas ajouter. Créer une issue pour une version ultérieure.
2026-02-05 13:15:55 +00:00
## 1. Standards Tailwind & Layout
feat(web): UI premium Discord/Spotify-like — tokens, shadows, focus, layout
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>
2026-02-08 16:15:58 +00:00
- **Interdiction formelle** d'utiliser des valeurs arbitraires (ex: `w-[300px]`, `gap-[7px]`, `rounded-[12px]`, `shadow-[...]`) pour les espacements, tailles, rayons ou ombres sans justification (voir exceptions dans `apps/web/docs/DESIGN_TOKENS.md`).
2026-02-05 13:15:55 +00:00
- Utilise exclusivement l'échelle de spacing native de Tailwind ou les **Layout Primitives** définies dans `apps/web/src/index.css` :
- `max-w-layout-content` (1600px)
- `min-h-layout-main` (calc(100vh - 4rem))
- `min-h-layout-page` (600px)
- `min-h-layout-page-sm` (400px)
- `min-h-layout-story` (192px, pour les stories)
feat(web): UI premium Discord/Spotify-like — tokens, shadows, focus, layout
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>
2026-02-08 16:15:58 +00:00
- Référence unique : **DESIGN_TOKENS.md** et **APP_SHELL.md** dans `apps/web/docs/` pour layout, espacements, ombres, typo, transitions.
2026-02-05 13:15:55 +00:00
## 2. Cycle de Vie des Composants (Storybook-First)
- Toute modification d'UI doit d'abord être validée dans sa **Story**.
- Chaque composant "Feature" doit obligatoirement posséder les états suivants dans sa Story :
- `Loading` (utilisant des Skeletons)
- `Error` (état de repli)
- `Empty` (si liste ou data)
- Référence toujours le `docs/STORYBOOK_CONTRACT.md` avant de créer une story.
- N'importer jamais les providers applicatifs dans les stories ; utiliser le décorateur global (StorybookDecorator).
## 3. Modularité & IA-Friendliness
- Si un composant dépasse **300 lignes**, il DOIT être découpé en sous-composants atomiques.
- Les composants doivent être "purs" : la logique de fetch doit être mockée via MSW dans `apps/web/src/mocks/handlers.ts`.
- Lors de l'ajout d'une nouvelle fonctionnalité qui appelle l'API, ajouter le handler correspondant dans `handlers.ts` sans qu'on te le demande.
## 4. Audit & Qualité
- Avant de finaliser une tâche, lance `npm run test:storybook` (depuis `apps/web`) après build + serve sur 6007 pour garantir 0 erreur réseau/console.
feat(web): UI premium Discord/Spotify-like — tokens, shadows, focus, layout
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>
2026-02-08 16:15:58 +00:00
## 5. Tests visuels et valeurs arbitraires
- **Commandes visuelles** (depuis `apps/web`) : `npm run visual:capture` (capture écrans → `visual-tests/current/`), `npm run visual:compare` (diff vs baselines), `npm run visual:update` (mise à jour des baselines). Procédure détaillée dans `apps/web/visual-tests/README.md`.
- **Rapport des valeurs arbitraires** : `node scripts/report-arbitrary-values.mjs` (optionnel `--json` ou `--dir src/features`) pour lister les patterns à migrer ; pas de remplacement automatique sans revue.
- **Nouvelle page full layout** : suivre `apps/web/docs/FULL_LAYOUT_PAGE.md` (route, story, MSW, viewport).
