@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/documentation/templates.md

@@ -11,7 +11,7 @@ Chaque documentation de module DOIT inclure ces sections dans cet ordre:
 
 | # | Section | Objectif | Public cible |
 |---|---------|----------|--------------|
-| 1 | **Valeur Metier** | Pourquoi cette fonctionnalite existe (probleme + solution) | Decideurs, Managers |
+| 1 | **Objectif** | Ce que fait le module et a quoi il sert (description simple, redigee comme un objectif) | Decideurs, Managers |
 | 2 | **Acces** | Navigation breadcrumb + URL | Utilisateurs |
 | 3 | **Apercu de l'interface** | **Mock UI annote** reproduisant la page reelle | Utilisateurs |
 | 4 | **Formulaire de creation** | **Mock UI annote** du formulaire de creation | Utilisateurs |
@@ -21,9 +21,40 @@ Chaque documentation de module DOIT inclure ces sections dans cet ordre:
 | 8 | **FAQ** | Questions non-techniques | Tous |
 | 9 | **Reference technique** | Permissions, API, regles metier (collapsible) | Admins |
 
+> **OBLIGATOIRE — Section 1 = Objectif :** toujours presente, en premier, comme
+> **section numerotee a part entiere** (`t('sections.objective')` + corps `t('objective')`).
+> Le `subtitle` du header ne la remplace PAS, meme s'il resume deja le module.
+> L'omettre echoue le gate step-03 (`existingDoc.missingRequired` = `['objective']`).
+>
+> **ADAPTATION autorisee :** les sections "interface" du milieu (Apercu / Formulaire /
+> Vue detail) s'adaptent a la forme reelle de la page — une page de reglages a onglets
+> devient une section par onglet ; un Kanban devient un board. **Fixes** : Section 1
+> Objectif, puis Acces, et la queue (Cas d'usage, Fonctionnalites, FAQ, Reference
+> technique). On adapte le corps, on ne supprime jamais l'Objectif.
+>
 > **SUPPRIME:** Les sections "Benefices" et "Avant/Apres" ne sont plus incluses.
 > Ce n'est pas un document de vente, mais une documentation utilisateur.
 
+### Header OBLIGATOIRE (au-dessus de la Section 1) — structure fixe
+
+Tout doc `user` ouvre par un header **identique** d'une page a l'autre (c'est l'ecart
+le plus visible quand il manque). Dans cet ordre exact :
+
+| Element | Rendu | Clé i18n |
+|---------|-------|----------|
+| Titre + icone | `<h1 class="text-3xl font-bold …">` | `title` |
+| **Tagline accent** | `<p class="text-xl text-[var(--color-accent-600)] font-medium">` — **REQUISE** | `summary` |
+| Sous-titre | `<p class="text-lg text-[var(--text-secondary)]">` | `subtitle` |
+| Ligne de stats | `<div class="flex gap-4 mt-3 text-sm …">` — **inline, PAS de pills** | `header.{businessRules,apiEndpoints,…}` |
+
+- **Tagline (`summary`) obligatoire** : une phrase accent qui resume l'usage. Son
+  absence echoue le gate step-03 (`existingDoc.missingRequired` = `['summary']`).
+  *(`valueProposition` est l'ancien nom de cette clé — migrer vers `summary`.)*
+- **Stats = texte inline** : `<span>{N} {t('header.xxx')}</span>` — le compteur est
+  un noeud texte frere. **NE PAS** utiliser `t('header.xxx', { count })` : si la
+  valeur i18n n'a pas `{{count}}`, le nombre disparait (bug observe). **PAS de badges
+  pills**, et pas de badge parasite (ex. le nom de l'app) dans la ligne de stats.
+
 ---
 
 ## REGLE FONDAMENTALE: Lire la vraie page AVANT de generer
@@ -38,6 +69,258 @@ Chaque documentation de module DOIT inclure ces sections dans cet ordre:
 
 ---
 
+## REGLE STYLE : Discret, pas flashy, contexte DocPanel-aware
+
+La documentation est consultee dans **deux contextes** :
+
+| Contexte | Largeur | Contraintes |
+|----------|---------|-------------|
+| Page pleine | ~`max-w-5xl` (~1024px) | Marges horizontales `px-4` ou `px-6` |
+| **DocPanel** (panneau lateral droit) | ~480px | Pas de debordement, padding compact, texte plus petit OK |
+
+### Couleurs : utiliser UNIQUEMENT les variables CSS du theme
+
+> **INTERDIT** : `bg-blue-50`, `bg-green-100`, `border-blue-200`, `text-blue-800`, ou toute couleur Tailwind hardcodee.
+> **INTERDIT** : `bg-[var(--info-bg)]`, `bg-[var(--success-bg)]`, `bg-[var(--warning-bg)]`, `bg-[var(--error-bg)]` pour les blocs d'information / annotation / solution. Ces couleurs sont reservees aux **vraies alertes** (toasts, validation form, banderoles d'erreur), pas a la mise en valeur visuelle de paragraphes.
+>
+> **EXCEPTIONS legitimes** : les **badges semantiques courts** (HTTP method GET/POST/PUT/PATCH/DELETE, status pills "active/inactive", severity tags) PEUVENT utiliser les couleurs `--info/success/warning/error/accent-*`. Convention universelle. Critere : badge `<= 4em` de large, font `text-xs`, pas un container d'information narrative.
+
+### Pattern d'accent recommande (Annotation, Solution, Tip, etc.)
+
+```tsx
+<div className="rounded-md border-l-2 border-[var(--color-accent-500)] bg-[var(--bg-secondary)] p-3">
+  ...
+</div>
+```
+
+- `bg-[var(--bg-secondary)]` : fond neutre (gris clair en light / gris fonce en dark)
+- `border-l-2 border-[var(--color-accent-500)]` : **bordure gauche fine** comme indicateur visuel (PAS de bordure tout-autour)
+- Padding `p-3` ou `px-3 py-2` selon densite voulue
+
+### Card pattern OFFICIEL SmartStack
+
+Le pattern **OBLIGATOIRE** pour toute card (sections principales, items de listes, blocs d'info) est celui utilisé par les vraies pages SmartStack (`UserDashboardPage.tsx`, `ProfilePage.tsx`, `MyTenantsPage.tsx`) :
+
+```tsx
+className="p-6 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]"
+```
+
+| Token | Role | NE PAS remplacer par |
+|-------|------|----------------------|
+| `bg-[var(--bg-card)]` | Fond de card | `bg-white`, `bg-gray-50`, `bg-[var(--bg-secondary)]` |
+| `border border-[var(--border-color)]` | Bordure subtile | `border-gray-200`, pas de border |
+| `rounded-[var(--radius-card)]` | Radius (12px) | `rounded-lg` (= 8px ≠ card), `rounded-md` |
+| `p-6` / `p-5` / `p-4` | Padding interne (densite) | px aleatoires |
+
+> **NE PAS UTILISER** `className="p-6 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]"` seul : la classe `.card` du theme n'inclut PAS de border (juste fond + shadow-sm). Les vraies pages SmartStack utilisent le pattern explicite avec **border** pour une separation plus nette dans les listes / grilles. **Adopter le pattern explicite pour rester aligne**.
+
+**Variantes** :
+- **Card highlighted** (selectionnee, focus) : ajouter `border-[var(--color-accent-500)] ring-2 ring-[var(--color-accent-500)]/20`
+- **Card secondaire** (item interne, list row) : `bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-[var(--radius-card)] p-4`
+- **Card cliquable** (button-like) : ajouter `hover:bg-[var(--bg-hover)] hover:border-[var(--color-accent-500)] transition-all`
+
+### Couleurs SmartStack : mapping Tailwind → tokens
+
+> **Délégué au CLI ui-polish.** N'applique PAS ce mapping à la main : après génération, `/ui-components` (CLI ui-polish, étape 03) convertit les couleurs Tailwind hardcodées en tokens de façon **déterministe**. La table ci-dessous est une **référence** (ce que le CLI applique) — ne la recopie pas dans le code généré.
+
+Mapping de référence (appliqué par ui-polish) quand une source contient du Tailwind hardcode :
+
+| Tailwind hardcode | Token SmartStack a utiliser | Contexte |
+|-------------------|-----------------------------|----------|
+| `bg-blue-50` / `bg-blue-100` | `bg-[var(--info-bg)]` | **Alerte info uniquement** (sinon `bg-[var(--bg-secondary)]`) |
+| `text-blue-700` / `text-blue-800` | `text-[var(--info-text)]` ou `text-[var(--color-accent-700)]` | Info vs accent (marque) |
+| `border-blue-200` / `border-blue-500/20` | `border-[var(--info-border)]` ou `border-[var(--color-accent-500)]/20` | — |
+| `bg-green-50` / `bg-green-100` | `bg-[var(--success-bg)]` | **Vrai succes uniquement** |
+| `text-green-600` / `text-green-700` / `text-green-800` | `text-[var(--success-text)]` | — |
+| `border-green-200` | `border-[var(--success-border)]` | — |
+| `bg-red-50` / `bg-red-100` | `bg-[var(--error-bg)]` | **Vraie erreur uniquement** |
+| `text-red-600` / `text-red-700` | `text-[var(--error-text)]` | — |
+| `bg-amber-*` / `bg-yellow-*` | `bg-[var(--warning-bg)]` | **Vrai warning** |
+| `text-amber-700` / `text-yellow-700` | `text-[var(--warning-text)]` | — |
+| `bg-purple-*` / `bg-violet-*` | `bg-[var(--accent-bg)]` ou `bg-[var(--color-accent-500)]/10` | Accent visuel |
+| `text-purple-700` | `text-[var(--color-accent-700)]` | — |
+| `bg-gray-*` / `bg-slate-*` / `bg-zinc-*` | `bg-[var(--bg-secondary)]` ou `bg-[var(--bg-tertiary)]` | — |
+| `text-gray-500` / `text-gray-600` | `text-[var(--text-secondary)]` / `text-[var(--text-tertiary)]` | — |
+
+> **Rappel** : `--info-bg`/`--success-bg`/`--warning-bg`/`--error-bg` ne s'utilisent **QUE** pour des **alertes reelles** (toast, form validation, banniere d'erreur, badge HTTP method). Pour mettre en valeur un paragraphe descriptif (Annotation, Tip, Solution), utiliser le pattern d'accent discret `bg-[var(--bg-secondary)] border-l-2 border-[var(--color-accent-500)]`.
+
+---
+
+### Marges et largeur — REGLE CRITIQUE
+
+> **PROBLEME OBSERVE** : si la Mock UI utilise du padding interne (`px-4 pb-4`) mais que les `<Annotation>` sont placees **hors** du conteneur padded, les annotations dépassent à gauche. Et si les barres internes ont une largeur fixe (px), elles débordent à droite en mode DocPanel (~480px).
+
+**Regle inviolable** : **toutes les Annotation d'une meme section sont placees DANS le meme conteneur que le Mock UI**, avec le **MEME** padding horizontal. JAMAIS d'Annotation orpheline en dehors du conteneur padded.
+
+```tsx
+{/* BON — Annotation DANS la card, même padding que le Mock UI */}
+<section>
+  <h2>...</h2>
+  <div className="bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)] overflow-hidden">
+    <div className="p-4 space-y-4">
+      {/* Mock UI ici */}
+      <div className="border rounded-lg p-3">...graphique...</div>
+
+      {/* Annotations DANS la même card, même padding */}
+      <div className="space-y-1.5">
+        <Annotation>{t('section.annotations.element1')}</Annotation>
+        <Annotation>{t('section.annotations.element2')}</Annotation>
+      </div>
+    </div>
+  </div>
+</section>
+
+{/* MAUVAIS — Annotation HORS du conteneur padded → déborde à gauche */}
+<section>
+  <div className="bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]">
+    <div className="px-4 pb-4">{/* Mock UI avec padding */}</div>
+  </div>
+  <Annotation>...</Annotation> {/* ← Décalée à gauche par rapport au Mock UI ! */}
+</section>
+```
+
+**Largeur des éléments internes** :
+- Le conteneur racine est **TOUJOURS** `<div className="space-y-8 max-w-5xl mx-auto pb-12">` — **PAS** de `px-` au niveau racine. Le padding horizontal vient du parent (`DocsLayout` en page pleine, `DocPanel` en panneau).
+- **Toute card contenant un Mock UI** doit avoir `overflow-hidden` pour empêcher les barres ou éléments larges de déborder.
+- **JAMAIS de width fixe en px** sur les barres de graphes : utiliser `flex-1`, `min-w-0`, `w-full` ou `%`. Les flex children doivent avoir `min-w-0` pour autoriser le rétrécissement.
+- Les `<section>` n'ajoutent **JAMAIS** de `mx-` ou `w-` qui forceraient une largeur. Elles s'etalent sur le conteneur.
+- Les Annotations utilisent `space-y-1.5` (espacement reduit). La marge supérieure (`mt-3`) **ne s'applique que si l'Annotation suit directement un Mock UI dans le même padding**.
+- Les `card p-6` ou `card p-4` selon la densite ; en DocPanel, preferer `p-4` quand possible.
+
+### Mapping recharts → Mock UI (FIDELITE OBLIGATOIRE)
+
+Le Mock UI doit reproduire le **TYPE** de graphique de la vraie page (pas seulement les données). Avant de coder la mock, identifier le composant recharts utilisé dans la vraie page :
+
+| Vrai composant | Type recharts | Mock UI fidele |
+|----------------|---------------|----------------|
+| `BarChart` (vertical) | `<BarChart>` + `<Bar>` | Histogramme avec `<div>` empilés en colonnes (`flex items-end h-N`, barres avec `height: %`) |
+| `BarChart` (horizontal, `layout="vertical"`) | `<BarChart layout="vertical">` | Liste de barres horizontales (`<div>` avec `width: %`) |
+| `PieChart` / `Doughnut` | `<PieChart>` + `<Pie>` | SVG `<circle>` avec `stroke-dasharray` OU `conic-gradient` en CSS |
+| `LineChart` | `<LineChart>` + `<Line>` | SVG `<polyline>` ou path |
+| `AreaChart` | `<AreaChart>` + `<Area>` | SVG path avec fill |
+| `RadialBarChart` | `<RadialBarChart>` | SVG circle avec stroke-dasharray |
+
+> **REGLE** : si la vraie page utilise `BarChart` (vertical, sans `layout="vertical"`), la mock DOIT être un histogramme vertical — **JAMAIS** une liste de barres horizontales. Inversement, `BarChart layout="vertical"` (Recharts → barres horizontales) → mock en barres horizontales. Vérifier le `layout` du composant `BarChart` source.
+
+**Detection** : grep `BarChart\|PieChart\|LineChart\|AreaChart\|RadialBarChart\|layout=` sur le composant chart source (souvent `/components/dashboard/*.tsx` ou `/components/charts/*.tsx`).
+
+### Fidélité des DONNÉES : vraie métrique + unité (PAS de % abstrait)
+
+> **REGLE CRITIQUE** : les valeurs d'un graphe mock reflètent la **vraie métrique** de la page documentée. Avant de coder, lire le composant chart source et relever :
+> - le **DTO + `dataKey`** (ex. `WeeklyStatsDto.dayStats[].totalDuration`) → **quelle grandeur** est tracée ;
+> - le **formatteur de valeur** (ex. `formatDuration` → `45 min`, `1h 10m`) → **l'unité** affichée ;
+> - les **labels d'axe** (`yAxisLabel`, `XAxis dataKey`) et toute **`ReferenceLine`** (ex. moyenne) ;
+> - la couleur de série réelle (ex. `getCategoricalColor(0)` = `--dataviz-cat-1`).
+>
+> La mock montre cette grandeur **dans sa vraie unité** (minutes/heures, nombre de sessions, €, %…) avec le bon label — **JAMAIS** des barres en `%` 0-100 abstrait quand la vraie métrique est une durée/un compte, et **JAMAIS** les valeurs d'exemple de ce fichier recopiées telles quelles.
+>
+> *Exemple vécu* : `WeeklyUsageChart` trace une **durée moyenne de session/jour** + une ligne de moyenne. Une doc qui affiche « Lun 42 %, Mar 78 %… » a recopié l'exemple : il faut des durées (« 42 min, 1h18… ») et la ligne de moyenne.
+
+### Couleurs des graphiques & KPI dashboard : palette `--dataviz-*`
+
+> **REGLE** : tout Mock UI reproduisant une **page dashboard** (KPI cards, graphiques, légendes) colore ses **séries de données** avec la palette **`--dataviz-*`** — **jamais** `--color-primary-*` ni `--color-accent-*`. C'est la palette dédiée aux dashboards (colorblind-safe, surchargée à l'exécution par `ThemeContext.applyDataViz()`), exactement comme la vraie `DashboardPage.tsx`.
+
+| Élément du dashboard | Token |
+|----------------------|-------|
+| Série unique (histogramme 1 métrique, ligne) | `var(--dataviz-cat-1)` (= `getCategoricalColor(0)` du vrai chart) |
+| Catégories multiples (barres groupées, donut, légende) | `var(--dataviz-cat-1)` … `var(--dataviz-cat-12)` (cycler) |
+| Tendance ↑ / ↓ / = | `var(--dataviz-trend-up)` / `var(--dataviz-trend-down)` / `var(--dataviz-trend-neutral)` |
+| Dégradé séquentiel (heatmap, intensité) | `var(--dataviz-seq-low)` → `var(--dataviz-seq-mid)` → `var(--dataviz-seq-high)` |
+
+> La card KPI reste une card standard (`bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]`) ; seuls le **chiffre**, la **barre**, le **segment** ou le **badge de tendance** portent une couleur `--dataviz-*` (via `style={{ backgroundColor: 'var(--dataviz-cat-N)' }}` ou `bg-[var(--dataviz-accent)]`).
+
+**Histogramme vertical type** :
+```tsx
+{/* Hauteur MINIMALE h-24 (96px) en page pleine, h-20 (80px) en DocPanel.
+    JAMAIS h-16 ou moins — les variations deviennent invisibles. */}
+<div className="flex items-end gap-1 h-24 w-full">
+  {data.map((d) => (
+    <div key={d.label} className="flex-1 min-w-0 flex flex-col items-center gap-1">
+      <div
+        className="w-full rounded-t bg-[var(--dataviz-cat-1)]"
+        style={{ height: `${(d.value / max) * 100}%`, minHeight: d.value > 0 ? '6px' : '0' }}
+        title={formatValue(d.value)}  /* vraie unité de la page : "45 min", "1h 10m", "12 sessions"… */
+      />
+      <span className="text-[10px] text-[var(--text-tertiary)] truncate w-full text-center">{d.label}</span>
+    </div>
+  ))}
+</div>
+{/* `--dataviz-cat-1` = getCategoricalColor(0) du vrai chart. `d.value` = la VRAIE métrique
+    (durée, nombre…), PAS un % abstrait. Si le vrai chart a une ReferenceLine (ex. moyenne),
+    la reproduire : trait pointillé --dataviz-trend-neutral + label "Moyenne: 1h 02". */}
+```
+
+**Donut chart type (SVG)** :
+```tsx
+<svg viewBox="0 0 36 36" className="w-32 h-32 mx-auto">
+  {segments.map((s, i) => (
+    <circle
+      key={i}
+      cx="18" cy="18" r="15.9"
+      fill="transparent"
+      stroke={s.color}
+      strokeWidth="3.5"
+      strokeDasharray={`${s.pct} ${100 - s.pct}`}
+      strokeDashoffset={s.offset}
+      transform="rotate(-90 18 18)"
+    />
+  ))}
+</svg>
+```
+
+### Donnees Mock EXPRESSIVES (anti-graphes-plats)
+
+> **PROBLEME** : si les valeurs mock sont uniformes (ex: `[10, 12, 11, 13, 10]`), toutes les barres apparaissent de la meme taille → graphe **plat** illisible. La doc doit montrer **une histoire visuelle** claire.
+
+**Regles de generation des mock data pour les graphes** :
+
+| Critere | Regle |
+|---------|-------|
+| Ratio max/min (valeurs > 0) | **≥ 5x** entre la valeur la plus haute et la plus basse non-nulle |
+| Pic clairement identifie | Au moins **1 valeur ≥ 90%** du max (pour qu'on voie un sommet) |
+| Vallee identifiee | Au moins **1 valeur ≤ 15%** du max (pour qu'on voie un creux) |
+| Zero plausible | Mettre `0` uniquement si realiste (ex: week-end pour une app pro, heure de nuit pour une app de jour) |
+| Hauteur container | `h-24` (96px) page pleine, `h-20` (80px) DocPanel — **JAMAIS** `h-16` ou moins |
+| `minHeight` barre non-nulle | `'6px'` minimum pour que les petites valeurs restent visibles |
+
+**Exemples concrets — ILLUSTRATIFS, à RÉGÉNÉRER par module (NE PAS recopier ces valeurs)** :
+
+> Ces blocs montrent la **forme** attendue (métrique réelle + unité + courbe expressive). Les chiffres sont des exemples : chaque doc produit les siens, tirés de la vraie page. Recopier `mockWeeklyData` / `mockHourlyData` tel quel = doc générique non conforme.
+
+```tsx
+// ✓ Hebdomadaire — VRAIE métrique de la page (ici: durée moyenne/jour, en minutes), PAS un % abstrait.
+//   Rendue via le formatteur de la vraie page (ex. formatDuration → "1h 40", "42 min").
+const mockWeeklyData = [
+  { day: 'Lun', value: 42 },  // 42 min   → barre moyenne
+  { day: 'Mar', value: 78 },  // 1h18     → barre haute
+  { day: 'Mer', value: 61 },  // 1h01     → barre moyenne-haute
+  { day: 'Jeu', value: 100 }, // 1h40     → PIC (le sommet)
+  { day: 'Ven', value: 52 },  // 52 min   → barre moyenne
+  { day: 'Sam', value: 12 },  // 12 min   → CREUX (week-end)
+  { day: 'Dim', value: 0  },  // inactif  → vide assumé
+];
+// ratio max/min(>0) = 100/12 = 8.3x ✓  (le ratio porte sur la forme, l'affichage garde l'unité)
+
+// ✓ Horaire — nombre de sessions par tranche : pic matin, creux midi, second pic apres-midi
+const mockHourlyData = [4, 8, 18, 28, 45, 38, 22, 15, 32, 40, 28, 18, 10, 5];
+// max=45, min(>0)=4 → ratio 11x ✓ ; double-bosse expressive
+
+// ✓ Donut applications — répartition en % (le donut EST une métrique en %) : 1 dominant, 1 moyen, 1 minoritaire (somme = 100)
+const mockAppSegments = [
+  { label: 'Administration', pct: 65, color: 'var(--dataviz-cat-1)' },
+  { label: 'Support',        pct: 25, color: 'var(--dataviz-cat-2)' },
+  { label: 'Mon Espace',     pct: 10, color: 'var(--dataviz-cat-3)' },
+];
+
+// ✗ MAUVAIS — toutes les valeurs proches → graphe plat
+const badWeekly = [{ day: 'Lun', value: 22 }, { day: 'Mar', value: 25 }, ...];
+// ratio 25/22 = 1.13x → on voit pas la difference
+```
+
+> **Pattern recommande** : courbe en cloche, double-bosse (matin+apres-midi), ou pic-isole-week-end. Eviter une distribution lineaire ou uniforme.
+
+---
+
 ## Mock UI TSX Approach (TYPE: user — PRIMARY)
 
 > **Principe:** Pour les docs de type `user`, generer un **composant TSX autonome** (~400-600 lignes)
@@ -74,7 +357,9 @@ Chaque documentation de module DOIT inclure ces sections dans cet ordre:
   }
 }
 
-// CORRECT pour DocRenderer (type developer/database/testing) - AVEC cle racine :
+// CORRECT pour DocRenderer (developer/database/testing) — NESTED sous la cle du namespace :
+// DocRenderer resout t('<namespace>.overview.objective'), donc le fichier imbrique sous le namespace.
+// (scaffold-doc fait cette imbrication automatiquement — tu fournis du contenu PLAT.)
 {
   "docsAdministrationUsers": {
     "overview": { "objective": "..." }
@@ -110,36 +395,52 @@ export default function {ModuleName}DocPage() {
 ## Composant Helper: Annotation
 
 > **OBLIGATOIRE** pour chaque section Mock UI. Un Mock sans explication ne sert a rien.
+>
+> **Design discret (NON flashy)** : fond neutre du theme + bordure gauche fine d'accent.
+> N'utilise PAS `--info-bg`, `--success-bg`, `--warning-bg`, ni `bg-blue-*`/`bg-green-*` (Tailwind hardcode).
+> Le composant doit rester lisible aussi bien en pleine page que dans le panneau `DocPanel`
+> (largeur reduite ~480px). Pas de fond colore vif.
 
 ```tsx
 import { Info } from 'lucide-react';
+import type { ReactNode } from 'react';
 
-function Annotation({ text }: { text: string }) {
+function Annotation({ children }: { children: ReactNode }) {
   return (
-    <div className="flex items-start gap-2 p-2.5 rounded-lg bg-[var(--info-bg)] border border-[var(--info-border)] text-sm text-[var(--info-text)]">
-      <Info className="w-4 h-4 mt-0.5 flex-shrink-0" />
-      <span>{text}</span>
+    <div className="flex items-start gap-2 px-3 py-2 rounded-md border-l-2 border-[var(--color-accent-500)] bg-[var(--bg-secondary)] text-xs text-[var(--text-secondary)]">
+      <Info className="w-3.5 h-3.5 mt-0.5 flex-shrink-0 text-[var(--text-tertiary)]" />
+      <span className="leading-relaxed">{children}</span>
     </div>
   );
 }
 ```
 
-**Utilisation:** Apres chaque bloc Mock UI, ajouter un `<div className="space-y-2 mt-4">` contenant
+> **API** : le composant accepte `children` (pas `text`) pour pouvoir injecter du JSX riche (badges, `<code>`, etc.) au besoin. En usage standard, `children` est juste un appel `t('...')`.
+
+**Pourquoi ce design :**
+- `bg-[var(--bg-secondary)]` : fond neutre cohérent avec le reste de l'app (gris clair / gris foncé selon le mode)
+- `border-l-2 border-[var(--color-accent-500)]` : bordure fine **uniquement à gauche** comme accent visuel (pas une boîte encadrée flashy)
+- `text-[var(--text-secondary)]` + `text-xs` : texte discret, hierarchie claire avec le contenu principal
+- `px-3 py-2` : padding compact qui respecte les marges du conteneur parent (essentiel pour DocPanel)
+
+**Utilisation:** Apres chaque bloc Mock UI, ajouter un `<div className="space-y-1.5 mt-3">` contenant
 les `<Annotation text={t('section.annotations.key')} />` pour chaque element visuel.
 
+> **NE PAS** ajouter `mx-` ou `w-` sur les Annotations : elles doivent suivre la largeur du parent (section) pour eviter les debordements en mode DocPanel.
+
 ### Exemple d'annotation apres un Mock UI
 
 ```tsx
 {/* Mock UI card ici */}
-<div className="card p-6">...</div>
-
-{/* Annotations explicatives */}
-<div className="space-y-2 mt-4">
-  <Annotation text={t('interface.annotations.icon')} />
-  <Annotation text={t('interface.annotations.title')} />
-  <Annotation text={t('interface.annotations.code')} />
-  <Annotation text={t('interface.annotations.defaultBadge')} />
-  <Annotation text={t('interface.annotations.cta')} />
+<div className="p-6 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]">...</div>
+
+{/* Annotations explicatives — espacement reduit + marge superieure modeste */}
+<div className="space-y-1.5 mt-3">
+  <Annotation>{t('interface.annotations.icon')}</Annotation>
+  <Annotation>{t('interface.annotations.title')}</Annotation>
+  <Annotation>{t('interface.annotations.code')}</Annotation>
+  <Annotation>{t('interface.annotations.defaultBadge')}</Annotation>
+  <Annotation>{t('interface.annotations.cta')}</Annotation>
 </div>
 ```
 
@@ -155,8 +456,6 @@ import { useTranslation } from 'react-i18next';
 import {
   ArrowLeft,
   Info,
-  Target,
-  Lightbulb,
   Users,
   Zap,
   ChevronDown,
@@ -165,12 +464,13 @@ import {
 
 // ═══════════════════════════════════════════════════
 // Helper: Annotation (obligatoire pour chaque Mock UI)
+// Design discret : fond neutre + bordure gauche d'accent (PAS de fond colore vif).
 // ═══════════════════════════════════════════════════
-function Annotation({ text }: { text: string }) {
+function Annotation({ children }: { children: React.ReactNode }) {
   return (
-    <div className="flex items-start gap-2 p-2.5 rounded-lg bg-[var(--info-bg)] border border-[var(--info-border)] text-sm text-[var(--info-text)]">
-      <Info className="w-4 h-4 mt-0.5 flex-shrink-0" />
-      <span>{text}</span>
+    <div className="flex items-start gap-2 px-3 py-2 rounded-md border-l-2 border-[var(--color-accent-500)] bg-[var(--bg-secondary)] text-xs text-[var(--text-secondary)]">
+      <Info className="w-3.5 h-3.5 mt-0.5 flex-shrink-0 text-[var(--text-tertiary)]" />
+      <span className="leading-relaxed">{children}</span>
     </div>
   );
 }
@@ -199,51 +499,52 @@ export default function {Module}DocPage() {
       {/* BREADCRUMB + BACK */}
       <div>
         <Link to="/docs/business/administration/tenants"
-          className="inline-flex items-center gap-1.5 text-sm text-[var(--text-secondary)] hover:text-[var(--color-primary-600)] mb-4">
+          className="inline-flex items-center gap-1.5 text-sm text-[var(--text-secondary)] hover:text-[var(--color-accent-600)] mb-4">
           <ArrowLeft className="w-4 h-4" />
           {t('nav.backToParent')}
         </Link>
       </div>
 
-      {/* HEADER */}
+      {/* HEADER — OBLIGATOIRE, structure fixe (voir "Header obligatoire" plus haut) */}
       <div>
         <h1 className="text-3xl font-bold mb-4 flex items-center gap-3">
-          <ModuleIcon className="w-8 h-8 text-[var(--color-primary-600)]" />
+          <ModuleIcon className="w-8 h-8 text-[var(--color-accent-600)]" />
           {t('title')}
         </h1>
-        <p className="text-xl text-[var(--color-primary-600)] font-medium mb-2">
-          {t('valueProposition')}
+        {/* Tagline accent — REQUISE (clé `summary`). Le gate step-03 bloque si absente. */}
+        <p className="text-xl text-[var(--color-accent-600)] font-medium mb-2">
+          {t('summary')}
         </p>
         <p className="text-lg text-[var(--text-secondary)]">
           {t('subtitle')}
         </p>
+        {/* Ligne de stats — texte inline, PAS de pills. Le compteur est un noeud
+            texte frere (`{N} {t('header.xxx')}`), JAMAIS via la pluralisation i18n
+            `t('header.xxx', { count })` (si la valeur n'a pas `{{count}}`, le nombre
+            disparait silencieusement). 2-3 stats : regles, endpoints + 1 metier. */}
+        <div className="flex flex-wrap gap-4 mt-3 text-sm text-[var(--text-secondary)]">
+          <span>{businessRules.length} {t('header.businessRules')}</span>
+          <span>{apiEndpoints.length} {t('header.apiEndpoints')}</span>
+          {/* + 1 stat specifique au module si pertinent (statuts, onglets, types…) */}
+        </div>
       </div>
 
       {/* ══════════════════════════════════════════════════════════════════ */}
-      {/* SECTION 1: VALEUR METIER - Pourquoi ca existe ?                   */}
+      {/* SECTION 1: OBJECTIF — Ce que fait le module / a quoi il sert       */}
+      {/* ══════════════════════════════════════════════════════════════════ */}
+      {/* Rediger {t('objective')} COMME UN OBJECTIF : une description       */}
+      {/* simple et factuelle de ce que permet le module (ce qu'il fait, a   */}
+      {/* quoi il sert), du point de vue utilisateur. PAS de probleme +      */}
+      {/* solution, PAS d'argumentaire de vente.                             */}
       {/* ══════════════════════════════════════════════════════════════════ */}
-      <section id="valeur" className="scroll-mt-4">
+      <section id="objectif" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
-          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">1</span>
-          {t('sections.businessValue')}
+          <span className="w-8 h-8 rounded-full bg-[var(--color-accent-600)] text-white flex items-center justify-center text-sm">1</span>
+          {t('sections.objective')}
         </h2>
 
-        <div className="card p-6">
-          <div className="mb-6">
-            <h3 className="font-semibold mb-3 flex items-center gap-2">
-              <Target className="w-5 h-5 text-[var(--error-text)]" />
-              {t('sections.problem')}
-            </h3>
-            <p className="text-[var(--text-secondary)]">{t('problem')}</p>
-          </div>
-
-          <div className="p-4 rounded-lg bg-[var(--success-bg)] border border-[var(--success-border)]">
-            <h3 className="font-semibold mb-2 flex items-center gap-2 text-[var(--success-text)]">
-              <Lightbulb className="w-5 h-5" />
-              {t('sections.solution')}
-            </h3>
-            <p className="text-[var(--text-secondary)]">{t('solution')}</p>
-          </div>
+        <div className="p-6 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]">
+          <p className="text-[var(--text-secondary)] leading-relaxed">{t('objective')}</p>
         </div>
       </section>
 
@@ -252,10 +553,10 @@ export default function {Module}DocPage() {
       {/* ══════════════════════════════════════════════════════════════════ */}
       <section id="acces" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
-          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">2</span>
+          <span className="w-8 h-8 rounded-full bg-[var(--color-accent-600)] text-white flex items-center justify-center text-sm">2</span>
           {t('sections.access')}
         </h2>
-        <div className="card p-6">
+        <div className="p-6 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]">
           {/* Breadcrumb de navigation et URL */}
           <div className="flex items-center gap-2 text-sm">
             <span>Administration</span> <span>›</span>
@@ -281,19 +582,19 @@ export default function {Module}DocPage() {
       {/* ══════════════════════════════════════════════════════════════════ */}
       <section id="interface" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
-          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">3</span>
+          <span className="w-8 h-8 rounded-full bg-[var(--color-accent-600)] text-white flex items-center justify-center text-sm">3</span>
           {t('sections.interface')}
         </h2>
 
         {/* Mock UI reproduisant la vraie page */}
-        <div className="card p-6">
+        <div className="p-6 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]">
           {/* ... MOCK UI FIDELE A LA VRAIE PAGE ... */}
         </div>
 
         {/* ANNOTATIONS OBLIGATOIRES apres le Mock UI */}
-        <div className="space-y-2 mt-4">
-          <Annotation text={t('interface.annotations.element1')} />
-          <Annotation text={t('interface.annotations.element2')} />
+        <div className="space-y-1.5 mt-3">
+          <Annotation>{t('interface.annotations.element1')}</Annotation>
+          <Annotation>{t('interface.annotations.element2')}</Annotation>
           {/* ... une annotation par element visuel important ... */}
         </div>
       </section>
@@ -303,7 +604,7 @@ export default function {Module}DocPage() {
       {/* ══════════════════════════════════════════════════════════════════ */}
       <section id="form" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
-          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">4</span>
+          <span className="w-8 h-8 rounded-full bg-[var(--color-accent-600)] text-white flex items-center justify-center text-sm">4</span>
           {t('sections.createForm')}
         </h2>
 
@@ -316,7 +617,7 @@ export default function {Module}DocPage() {
             {/* Champs de formulaire adaptes au module */}
           </div>
           <div className="flex items-center gap-3 mt-6 pt-6 border-t border-[var(--border-color)]">
-            <button className="px-4 py-2 bg-[var(--color-primary-600)] text-white rounded-lg">
+            <button className="px-4 py-2 bg-[var(--color-accent-600)] text-white rounded-lg">
               {t('form.create')}
             </button>
             <button className="px-4 py-2 border border-[var(--border-color)] rounded-lg">
@@ -326,10 +627,10 @@ export default function {Module}DocPage() {
         </div>
 
         {/* ANNOTATIONS OBLIGATOIRES apres le formulaire */}
-        <div className="space-y-2 mt-4">
-          <Annotation text={t('form.annotations.field1')} />
-          <Annotation text={t('form.annotations.field2')} />
-          <Annotation text={t('form.annotations.actions')} />
+        <div className="space-y-1.5 mt-3">
+          <Annotation>{t('form.annotations.field1')}</Annotation>
+          <Annotation>{t('form.annotations.field2')}</Annotation>
+          <Annotation>{t('form.annotations.actions')}</Annotation>
         </div>
       </section>
 
@@ -338,7 +639,7 @@ export default function {Module}DocPage() {
       {/* ══════════════════════════════════════════════════════════════════ */}
       <section id="detail" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
-          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">5</span>
+          <span className="w-8 h-8 rounded-full bg-[var(--color-accent-600)] text-white flex items-center justify-center text-sm">5</span>
           {t('sections.detailView')}
         </h2>
 
@@ -346,15 +647,15 @@ export default function {Module}DocPage() {
         <p className="text-[var(--text-secondary)] mb-4">{t('detail.desc')}</p>
 
         {/* Mock UI de la vue detail */}
-        <div className="card p-6">
+        <div className="p-6 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]">
           {/* ... MOCK UI FIDELE A LA VRAIE VUE DETAIL ... */}
         </div>
 
         {/* ANNOTATIONS OBLIGATOIRES */}
-        <div className="space-y-2 mt-4">
-          <Annotation text={t('detail.annotations.header')} />
-          <Annotation text={t('detail.annotations.tabs')} />
-          <Annotation text={t('detail.annotations.stats')} />
+        <div className="space-y-1.5 mt-3">
+          <Annotation>{t('detail.annotations.header')}</Annotation>
+          <Annotation>{t('detail.annotations.tabs')}</Annotation>
+          <Annotation>{t('detail.annotations.stats')}</Annotation>
         </div>
       </section>
 
@@ -363,13 +664,13 @@ export default function {Module}DocPage() {
       {/* ══════════════════════════════════════════════════════════════════ */}
       <section id="cas-usage" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
-          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">6</span>
+          <span className="w-8 h-8 rounded-full bg-[var(--color-accent-600)] text-white flex items-center justify-center text-sm">6</span>
           {t('sections.useCases')}
         </h2>
 
         <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
           {[1, 2, 3].map((i) => (
-            <div key={i} className="card p-6">
+            <div key={i} className="p-6 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]">
               <div className="flex items-center gap-3 mb-4">
                 <div className="w-10 h-10 rounded-full bg-[var(--accent-bg)] flex items-center justify-center">
                   <Users className="w-5 h-5 text-[var(--accent-text)]" />
@@ -384,9 +685,10 @@ export default function {Module}DocPage() {
                   <span className="font-medium text-[var(--text-secondary)]">Situation:</span>
                   <p>{t(`useCases.${i}.situation`)}</p>
                 </div>
-                <div className="text-sm p-3 rounded-lg bg-[var(--success-bg)] border border-[var(--success-border)]">
-                  <span className="font-medium text-[var(--success-text)]">Avec la fonctionnalite:</span>
-                  <p>{t(`useCases.${i}.withFeature`)}</p>
+                {/* Bloc "Avec la fonctionnalite" discret — accent gauche, pas de fond vif */}
+                <div className="text-sm p-3 rounded-md border-l-2 border-[var(--color-accent-500)] bg-[var(--bg-secondary)]">
+                  <span className="font-medium text-[var(--text-primary)]">Avec la fonctionnalite:</span>
+                  <p className="text-[var(--text-secondary)]">{t(`useCases.${i}.withFeature`)}</p>
                 </div>
               </div>
             </div>
@@ -399,22 +701,22 @@ export default function {Module}DocPage() {
       {/* ══════════════════════════════════════════════════════════════════ */}
       <section id="fonctionnalites" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
-          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">7</span>
+          <span className="w-8 h-8 rounded-full bg-[var(--color-accent-600)] text-white flex items-center justify-center text-sm">7</span>
           {t('sections.features')}
         </h2>
 
         <div className="space-y-4">
           {[1, 2, 3, 4, 5].map((i) => (
-            <div key={i} className="card p-6">
+            <div key={i} className="p-6 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]">
               <div className="flex items-start gap-4">
-                <div className="w-10 h-10 rounded-lg bg-[var(--color-primary-600)]/10 flex items-center justify-center flex-shrink-0">
-                  <Zap className="w-5 h-5 text-[var(--color-primary-600)]" />
+                <div className="w-10 h-10 rounded-lg bg-[var(--accent-bg)] flex items-center justify-center flex-shrink-0">
+                  <Zap className="w-5 h-5 text-[var(--accent-text)]" />
                 </div>
                 <div className="flex-1">
                   <h3 className="font-semibold mb-2">{t(`features.${i}.title`)}</h3>
                   <p className="text-[var(--text-secondary)] mb-3">{t(`features.${i}.description`)}</p>
                   <div className="p-3 rounded-lg bg-[var(--bg-secondary)] text-sm">
-                    <span className="font-medium text-[var(--color-primary-600)]">Exemple: </span>
+                    <span className="font-medium text-[var(--color-accent-600)]">Exemple: </span>
                     {t(`features.${i}.example`)}
                   </div>
                 </div>
@@ -429,14 +731,14 @@ export default function {Module}DocPage() {
       {/* ══════════════════════════════════════════════════════════════════ */}
       <section id="faq" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
-          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">8</span>
+          <span className="w-8 h-8 rounded-full bg-[var(--color-accent-600)] text-white flex items-center justify-center text-sm">8</span>
           {t('sections.faq')}
         </h2>
 
         <div className="space-y-3">
           {[1, 2, 3, 4, 5].map((i) => (
-            <details key={i} className="card group">
-              <summary className="p-4 cursor-pointer hover:bg-[var(--bg-secondary)] rounded-lg font-medium flex items-center justify-between">
+            <details key={i} className="bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)] group">
+              <summary className="p-4 cursor-pointer hover:bg-[var(--bg-secondary)] rounded-[var(--radius-card)] font-medium flex items-center justify-between">
                 {t(`faq.${i}.question`)}
                 <ChevronDown className="w-4 h-4 text-[var(--text-secondary)] group-open:rotate-180 transition-transform" />
               </summary>
@@ -452,8 +754,8 @@ export default function {Module}DocPage() {
       {/* SECTION 9: REFERENCE TECHNIQUE (collapsible)                      */}
       {/* ══════════════════════════════════════════════════════════════════ */}
       <section id="reference" className="scroll-mt-4">
-        <details className="card">
-          <summary className="p-4 cursor-pointer hover:bg-[var(--bg-secondary)] rounded-lg font-semibold flex items-center gap-2">
+        <details className="bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]">
+          <summary className="p-4 cursor-pointer hover:bg-[var(--bg-secondary)] rounded-[var(--radius-card)] font-semibold flex items-center gap-2">
             <span className="w-8 h-8 rounded-full bg-[var(--bg-tertiary)] text-[var(--text-secondary)] flex items-center justify-center text-sm">9</span>
             {t('sections.technicalRef')}
           </summary>
@@ -540,27 +842,27 @@ export default function {Module}DocPage() {
     "backToParent": "Retour a {Parent}"
   },
   "title": "Nom du module",
-  "valueProposition": "Une phrase percutante resumant la valeur",
+  "summary": "Une phrase accent resumant l'usage du module (tagline header — REQUISE)",
   "subtitle": "Description en 1-2 phrases",
 
+  "header": {
+    "businessRules": "regles metier",
+    "apiEndpoints": "endpoints API"
+  },
+
   "sections": {
-    "businessValue": "Pourquoi ce module ?",
-    "problem": "Le probleme",
-    "solution": "La solution",
+    "objective": "Objectif",
     "access": "Acces",
     "interface": "Apercu de l'interface",
     "createForm": "Formulaire de creation",
     "detailView": "Vue detail",
     "useCases": "Exemples d'utilisation",
-    "benefits": "Benefices concrets",
-    "beforeAfter": "Avant / Apres",
     "features": "Ce que vous pouvez faire",
     "faq": "Questions frequentes",
     "technicalRef": "Reference technique (administrateurs)"
   },
 
-  "problem": "Description du probleme AVANT cette fonctionnalite",
-  "solution": "Comment ce module resout le probleme",
+  "objective": "Description simple, redigee comme un objectif, de ce que permet le module (ce qu'il fait, a quoi il sert) — sans probleme/solution ni argumentaire",
 
   "access": {
     "navigation": "Navigation"
@@ -642,13 +944,22 @@ Avant de valider une documentation de module `user`, verifier:
 - [ ] **Mock UI Section 4: Formulaire** avec champs du vrai formulaire
 - [ ] **Mock UI Section 5: Vue detail** avec onglets/stats de la vraie page
 - [ ] **Annotations** sur chaque section Mock UI (composant `Annotation`)
-- [ ] **Proposition de valeur** claire en 1 phrase
-- [ ] **Probleme/Solution** du point de vue utilisateur (pas technique)
+- [ ] **Header complet** : titre + **tagline accent `t('summary')`** (REQUISE — gate `missingRequired`) + sous-titre + **ligne de stats inline** (`{N} {t('header.xxx')}`, compteur en texte frere, PAS de pills, PAS de `{count}` i18n)
+- [ ] **Resume descriptif** clair en 1 phrase (neutre, pas une accroche marketing)
+- [ ] **Objectif** = Section 1 a part entiere (`t('sections.objective')` + `t('objective')`), decrit simplement ce qu'il fait / a quoi il sert — PAS de probleme/solution, PAS fondu dans le subtitle. (Gate step-03 : `missingRequired` doit etre vide.)
 - [ ] **2-3 cas d'usage** avec personas nommes
 - [ ] **5 fonctionnalites** avec exemples concrets
 - [ ] **5 FAQ** non-techniques
 - [ ] **Reference technique** collapsible: regles metier + API endpoints reels
-- [ ] **Semantic colors** (`var(--success-*)`, `var(--error-*)`, etc.)
+- [ ] **Theme tokens uniquement** (`var(--bg-secondary)`, `var(--color-accent-*)`, `var(--text-secondary)`, etc.) — JAMAIS de `bg-blue-50`, `border-green-200`, ni `--info-bg`/`--success-bg` pour les blocs d'emphase
+- [ ] **Couleur de marque = `--color-accent-*`** (rampe thématisable qui suit l'éditeur de thème) — **JAMAIS `--color-primary-*`** (indigo figé, "flashy"). Badges/halos subtils = `bg-[var(--accent-bg)] text-[var(--accent-text)]`. Vérifier : `grep "color-primary" <fichier>` → 0 match
+- [ ] **Graphiques & KPI dashboard = palette `--dataviz-*`** : séries via `--dataviz-accent`/`--dataviz-cat-N`, tendances via `--dataviz-trend-*` — jamais `--color-primary-*`/`--color-accent-*` pour les données
+- [ ] **ZERO couleur Tailwind palette** : verifier `grep -E "(bg|text|border)-(blue|red|green|yellow|amber|purple|violet|gray|slate|zinc|indigo|teal|cyan|sky|orange|pink|rose|emerald|lime)-[0-9]"` → 0 match
+- [ ] **Cards = pattern officiel** : `p-N bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]` — PAS `className="card"`, PAS `rounded-lg`, PAS `bg-white`/`bg-gray-*`
+- [ ] **Annotation discrete** : `bg-[var(--bg-secondary)] border-l-2 border-[var(--color-accent-500)]` — pas de boite encadree flashy
+- [ ] **Charts fideles + expressifs** : type recharts respecte (histogramme vertical ≠ barres horizontales), ratio max/min ≥ 5x, hauteur ≥ h-24/h-20
+- [ ] **Pas d'overflow DocPanel** : `overflow-hidden` sur cards de chart, `min-w-0` sur flex children, pas de width px
+- [ ] **Racine sans `px-`** : `<div className="space-y-8 max-w-5xl mx-auto pb-12">` pour compatibilite DocPanel (~480px)
 - [ ] **i18n** via `useTranslation()` — pas de texte hardcode
 - [ ] **i18n 4 langues** : FR, EN, DE, IT (JSON plat, pas de cle racine)
 - [ ] **PAS de section "Benefices"** ni "Avant/Apres"