senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/apps/web/docs/APP_SHELL.md
senke 34e1f41091 refactor: Phase 8 — Update docs, ESLint, Storybook config for SUMI 
- DESIGN_TOKENS.md: Complete rewrite to document --sumi-* token system
- APP_SHELL.md: Update layout shell docs (glass bg, backdrop-blur, z-index)
- DESIGN_DIRECTION.md: Update aesthetic direction to SUMI philosophy
- .storybook/preview.tsx: Remove deleted CSS imports, update bg colors
- eslint.config.js: Update color rule message from Kodo to SUMI tokens
- tailwind.config.ts: Fix comment referencing deleted design-tokens.css

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-12 02:15:11 +01:00

143 lines
8.1 KiB
Markdown
Raw Blame History

# App Shell — Référence (SUMI)
Vue d'ensemble du shell applicatif (layout principal) et des tokens CSS SUMI associés. Toute évolution du shell (sidebar, header, main, player) doit s'appuyer sur ces variables et classes pour rester cohérente.
Source de vérité : [index.css](../src/index.css) — sections "LAYOUT", "GLASS", "Z-INDEX" et les classes utilitaires `@utility`.
## Rôle du shell
- **Header** : barre fixe en haut (hauteur `--header-height`). Fond **glass** (`--sumi-glass-bg`), `backdrop-blur-[12px]` (`--sumi-glass-blur`), bordure basse `--sumi-border-faint`, z-index **200** (`--sumi-z-sticky`). Le bord gauche suit la sidebar (expanded/collapsed).
- **Sidebar** : navigation fixe à gauche (largeur `--sidebar-width-expanded` / `--sidebar-width-collapsed`). Fond `--sumi-bg-raised`, bordure droite `--sumi-border-faint`. Voir [index.css](../src/index.css) section "Sidebar layout" et le mapping Shadcn `--sidebar-*`.
- **Main** : zone scrollable (contenu des pages). Marges gauche pilotées par l'état de la sidebar ; padding top/bottom pour ne pas passer sous le header ni le player. Espacement interne via tokens SUMI (`--sumi-space-*`).
- **Player** : barre de lecture fixe en bas (rendue par `GlobalPlayer` dans `DashboardLayout`). Fond **glass** (`--sumi-glass-bg`), `backdrop-blur-[16px]`, bordure `--sumi-glass-border`, z-index **200** (`--sumi-z-sticky`). Conteneur : `PlayerBarGlass`.
Fichiers principaux :
- [DashboardLayout.tsx](../src/components/layout/DashboardLayout.tsx) — assemblage Sidebar, zone main, Header, GlobalPlayer.
- [Header.tsx](../src/components/layout/Header.tsx) — barre supérieure (glass bg, recherche, actions, user menu).
- [PlayerBarGlass.tsx](../src/features/player/components/player-bar/PlayerBarGlass.tsx) — conteneur glassmorphism du player.
## Thème et switching
Le thème est piloté par l'attribut **`[data-theme]`** sur `<html>`, et non par un toggle de classe (`dark`/`light`).
- `ThemeProvider` (`src/components/theme/ThemeProvider.tsx`) pose `data-theme="dark"` ou `data-theme="light"` sur `document.documentElement`.
- Les tokens CSS sont définis dans `:root, [data-theme="dark"]` (dark par défaut) et `[data-theme="light"]` (light theme — Washi Paper).
- Le mode `system` écoute `prefers-color-scheme` et pose le `data-theme` correspondant.
## Variables CSS (shell — SUMI)
### Tokens SUMI globaux (utilisés par le shell)
Définis dans `:root` dans [index.css](../src/index.css) :
| Variable | Valeur (dark) | Rôle |
|----------|---------------|------|
| `--sumi-glass-bg` | `rgba(18,18,21, 0.80)` | Fond glass (header, player) |
| `--sumi-glass-border` | `rgba(255,255,255, 0.08)` | Bordure glass |
| `--sumi-glass-blur` | `12px` | Flou glass (header) |
| `--sumi-bg-raised` | `#1a1a1f` | Fond sidebar |
| `--sumi-border-faint` | `rgba(255,255,255, 0.06)` | Bordure fine (sidebar, header) |
| `--sumi-z-sticky` | `200` | Z-index header et player |
| `--sumi-z-raised` | `10` | Z-index contenu principal |
| `--sumi-header-height` | `56px` | Hauteur header (token SUMI) |
| `--sumi-sidebar-width` | `240px` | Largeur sidebar ouverte (token SUMI) |
| `--sumi-sidebar-collapsed` | `64px` | Largeur sidebar fermée (token SUMI) |
| `--sumi-player-height` | `80px` | Hauteur player bar (token SUMI) |
### Tokens layout du shell (classes utilitaires)
Définis dans la section "App shell" de [index.css](../src/index.css) :
| Variable | Valeur | Rôle |
|----------|--------|------|
| `--header-height` | 4rem | Hauteur de la barre header fixe |
| `--main-offset-top` | 5rem | Padding-top du `<main>` (dégager le header) |
| `--main-offset-bottom` | 9rem | Padding-bottom du `<main>` (réserve pour le player) |
| `--main-margin-left-expanded` | 18rem | Marge gauche du conteneur main quand sidebar ouverte (15rem sidebar + 3rem gap) |
| `--main-margin-left-collapsed` | 7rem | Marge gauche du main quand sidebar fermée (5rem + 2rem gap) |
| `--header-left-expanded` | 18rem | Position `left` de la barre header quand sidebar ouverte |
| `--header-left-collapsed` | 5rem | Position `left` de la barre header quand sidebar fermée |
Les largeurs sidebar sont définies à part : `--sidebar-width-expanded` (15rem), `--sidebar-width-collapsed` (5rem). Pour garder la cohérence, ne pas modifier les marges main/header sans ajuster ces tokens de façon cohérente.
## Classes utilitaires (shell)
Définies dans [index.css](../src/index.css) via `@utility` :
| Classe | Propriété | Usage |
|--------|-----------|--------|
| `.h-header` | height | Barre header et div interne du header |
| `.pt-main` | padding-top | Élément `<main>` |
| `.pb-main` | padding-bottom | Élément `<main>` |
| `.ml-main-expanded` | margin-left | Conteneur principal (avec préfixe `lg:`) quand sidebar ouverte |
| `.ml-main-collapsed` | margin-left | Conteneur principal (avec `lg:`) quand sidebar fermée |
| `.left-header-expanded` | left | Barre header quand sidebar ouverte |
| `.left-header-collapsed` | left | Barre header quand sidebar fermée |
| `.max-w-layout-content` | max-width | Wrapper contenu principal (limite à `--layout-content-max-width`) |
À utiliser avec le préfixe responsive `lg:` pour les marges/positions desktop (ex. `lg:ml-main-expanded`). En dessous de `lg`, la sidebar est en overlay et le main utilise `ml-0`, le header `left-0` (`max-lg:left-0`).
## Apparence des zones du shell
### Header
```
bg: var(--sumi-glass-bg) → rgba(18,18,21, 0.80)
blur: backdrop-blur-[12px] → var(--sumi-glass-blur)
border: border-b border-[var(--sumi-border-faint)]
z-index: z-[200] → var(--sumi-z-sticky)
height: h-header → var(--header-height) = 4rem
```
### Sidebar
```
bg: var(--sumi-bg-raised) → #1a1a1f (dark) / #ffffff (light)
border: border-r border-[var(--sumi-border-faint)]
z-index: var(--sidebar-z-index) → 95
width: w-sidebar-expanded (15rem) / w-sidebar-collapsed (5rem)
```
### Player bar
```
bg: var(--sumi-glass-bg) → rgba(18,18,21, 0.80)
blur: backdrop-blur-[16px] → plus prononcé que le header
border: border border-[var(--sumi-glass-border)]
z-index: z-[200] → var(--sumi-z-sticky)
shadow: var(--sumi-shadow-lg) / var(--sumi-shadow-xl) au hover
```
### Main content
```
padding: pt-main (5rem top), pb-main (9rem bottom), px-4 md:px-8
margin: lg:ml-main-expanded / lg:ml-main-collapsed
wrapper: max-w-layout-content mx-auto → limité à var(--layout-content-max-width) = 100rem
scroll: overflow-y-auto custom-scrollbar
```
## Comportement responsive
- **lg (1024px et plus)** : sidebar fixe à gauche, main et header utilisent les classes tokenisées (expanded/collapsed selon `sidebarOpen`).
- **En dessous de lg** : sidebar en overlay (ouverte/fermée par toggle), conteneur main en pleine largeur (`ml-0`), header en pleine largeur (`max-lg:left-0`).
## Breakpoints et viewports de test
| Breakpoint | Largeur | Comportement attendu |
|------------|---------|----------------------|
| Mobile | 320px | Sidebar overlay, main pleine largeur, header pleine largeur. |
| Tablet | 768px | Idem (sidebar overlay jusqu'à lg). |
| Desktop | 1024px (lg) | Sidebar fixe, main et header avec marges/positions tokenisées. |
| Large desktop | 1280px | Même comportement que lg, contenu limité par `max-w-layout-content` si applicable. |
Vérifier visuellement (ou via tests Playwright) que Sidebar, Header et Main se comportent correctement sur ces largeurs.
## Référence croisée
- Tokens SUMI complets (backgrounds, borders, text, glass, shadows, z-index, spacing, radius, motion) : [index.css](../src/index.css) — `:root` et `[data-theme="light"]`.
- Tokens sidebar (largeurs, offsets, z-index) : [index.css](../src/index.css) — "Sidebar layout" et classes `.w-sidebar-expanded`, `.left-sidebar`, `.top-sidebar`, `.bottom-sidebar`, `.z-sidebar`, `.z-sidebar-overlay`.
- Layout primitives (max-width contenu, min-height pages) : variables `--layout-content-max-width`, `--layout-page-min-height`, etc. Le `<main>` contient un wrapper `max-w-layout-content` pour le contenu.
- Design tokens SUMI (nomenclature, philosophie) : [DESIGN_TOKENS.md](./DESIGN_TOKENS.md).
- Direction design (esthétique SUMI) : [DESIGN_DIRECTION.md](./DESIGN_DIRECTION.md).
Reference in a new issue View git blame Copy permalink