docs(design-system): add design system documentation and AI agent instructions

- Add docs/design-system.md with color tokens, typography, spacing, icons, responsive/PWA rules and component reuse guidelines - Add CLAUDE.md with permanent instructions for Claude Code - Add .github/instructions/design-system.instruction.md for GitHub Copilot - Update .github/copilot-instructions.md to reference the design system - Update Front-End/tailwind.config.js with color tokens (primary, secondary, tertiary, neutral) and font families (Manrope/Inter) - Update Front-End/src/app/layout.js to load Manrope and Inter via next/font/google
2026-04-05 20:51:26 +00:00 · 2026-04-04 11:56:19 +02:00
parent 2579af9b8b
commit cb76a23d02
6 changed files with 553 additions and 2 deletions
--- a/docs/design-system.md
+++ b/docs/design-system.md
@ -0,0 +1,293 @@
+# Design System — N3WT-SCHOOL
+
+## Vue d'ensemble
+
+Le design system N3WT-SCHOOL définit les tokens visuels et les conventions d'usage pour garantir une interface cohérente sur l'ensemble du produit.
+
+---
+
+## Couleurs
+
+Les couleurs sont définies comme tokens Tailwind dans `Front-End/tailwind.config.js`.
+
+| Token Tailwind | Valeur hex | Usage                                              |
+| -------------- | ---------- | -------------------------------------------------- |
+| `primary`      | `#059669`  | Boutons principaux, CTA, éléments interactifs clés |
+| `secondary`    | `#064E3B`  | Hover des éléments primaires, accents sombres      |
+| `tertiary`     | `#10B981`  | Badges, icônes d'accent, highlights                |
+| `neutral`      | `#F8FAFC`  | Fonds de page, surfaces, arrière-plans neutres     |
+
+### Règles d'usage
+
+- **Ne jamais** utiliser les classes Tailwind brutes `emerald-*`, `green-*` pour les éléments interactifs. Utiliser les tokens (`primary`, `secondary`, `tertiary`).
+- Les fonds décoratifs (gradients, illustrations) peuvent conserver les classes Tailwind standards.
+- Les états de statut (success, error, warning, info) peuvent conserver leurs couleurs sémantiques (`green`, `red`, `yellow`, `blue`).
+
+### Exemples
+
+```jsx
+// Bouton principal
+<button className="bg-primary hover:bg-secondary text-white">Valider</button>
+
+// Texte accent
+<span className="text-primary font-medium">Voir plus</span>
+
+// Badge
+<span className="bg-tertiary/10 text-tertiary">Actif</span>
+
+// Fond de page
+<div className="bg-neutral min-h-screen">...</div>
+```
+
+---
+
+## Typographie
+
+Les polices sont chargées via `next/font/google` dans `Front-End/src/app/layout.js` et exposées comme variables CSS.
+
+| Rôle      | Police    | Token Tailwind  | Usage                               |
+| --------- | --------- | --------------- | ----------------------------------- |
+| Headlines | `Manrope` | `font-headline` | `h1`, `h2`, `h3`, titres de section |
+| Body      | `Inter`   | `font-body`     | Paragraphes, contenu (défaut)       |
+| Labels    | `Inter`   | `font-label`    | Boutons, labels de formulaires      |
+
+> `font-body` est appliqué par défaut sur `<body>`. Il n'est donc pas nécessaire de l'ajouter manuellement sur chaque élément de texte courant.
+
+### Exemples
+
+```jsx
+// Titre de page
+<h1 className="font-headline text-2xl font-bold text-gray-900">Tableau de bord</h1>
+
+// Sous-titre
+<h2 className="font-headline text-xl font-semibold text-secondary">Élèves</h2>
+
+// Label de formulaire
+<label className="font-label text-sm font-medium text-gray-700">Prénom</label>
+```
+
+---
+
+## Rayon de bordure (Border Radius)
+
+Arrondi subtil, niveau 1.
+
+| Token Tailwind | Valeur | Usage                              |
+| -------------- | ------ | ---------------------------------- |
+| `rounded-sm`   | `2px`  | Éléments très petits (badges fins) |
+| `rounded`      | `4px`  | Par défaut — boutons, inputs       |
+| `rounded-md`   | `6px`  | Cards, modales                     |
+| `rounded-lg`   | `8px`  | Grandes surfaces                   |
+
+> Éviter `rounded-xl` (12px) et `rounded-full` sauf pour les avatars ou indicateurs circulaires.
+
+---
+
+## Espacement
+
+Espacement normal, base 8px (niveau 2). Utiliser les multiples de 4px/8px du système Tailwind standard.
+
+| Classe | Valeur |
+| ------ | ------ |
+| `p-1`  | 4px    |
+| `p-2`  | 8px    |
+| `p-3`  | 12px   |
+| `p-4`  | 16px   |
+| `p-6`  | 24px   |
+| `p-8`  | 32px   |
+
+---
+
+## Composants récurrents
+
+### Bouton principal
+
+```jsx
+<button className="bg-primary hover:bg-secondary text-white font-label font-medium px-4 py-2 rounded transition-colors">
+  Action
+</button>
+```
+
+### Bouton secondaire
+
+```jsx
+<button className="border border-primary text-primary hover:bg-primary hover:text-white font-label font-medium px-4 py-2 rounded transition-colors">
+  Action secondaire
+</button>
+```
+
+### Card
+
+```jsx
+<div className="bg-white rounded-md border border-gray-200 shadow-sm p-4">
+  <h2 className="font-headline text-lg font-semibold text-gray-900">Titre</h2>
+  <p className="text-gray-600 mt-2">Contenu</p>
+</div>
+```
+
+### Badge de statut
+
+```jsx
+<span className="inline-flex items-center bg-tertiary/10 text-tertiary text-xs font-label font-medium px-2 py-0.5 rounded">
+  Actif
+</span>
+```
+
+### Lien d'action
+
+```jsx
+<a className="text-primary hover:text-secondary underline-offset-2 hover:underline transition-colors">
+  Voir le détail
+</a>
+```
+
+---
+
+## Configuration Tailwind
+
+Fichier : `Front-End/tailwind.config.js`
+
+```js
+theme: {
+  extend: {
+    colors: {
+      primary:   '#059669',
+      secondary: '#064E3B',
+      tertiary:  '#10B981',
+      neutral:   '#F8FAFC',
+    },
+    fontFamily: {
+      headline: ['var(--font-manrope)', 'Manrope', 'sans-serif'],
+      body:     ['var(--font-inter)',   'Inter',   'sans-serif'],
+      label:    ['var(--font-inter)',   'Inter',   'sans-serif'],
+    },
+    borderRadius: {
+      DEFAULT: '4px',
+      sm:      '2px',
+      md:      '6px',
+      lg:      '8px',
+    },
+  },
+},
+```
+
+---
+
+## Icônes
+
+Toutes les icônes utilisent la bibliothèque **`lucide-react`** exclusivement.
+
+```jsx
+import { Home, User, ChevronRight } from 'lucide-react';
+
+// Taille standard
+<Home size={20} className="text-primary" />
+
+// Avec label accessible
+<button className="flex items-center gap-2">
+  <Plus size={16} />
+  Ajouter
+</button>
+```
+
+### Règles icônes
+
+- **Toujours** importer depuis `lucide-react` — jamais d'autres bibliothèques d'icônes.
+- Taille par défaut : `size={20}` (inline), `size={24}` (boutons standalone).
+- Couleur : via `className="text-*"` — ne jamais utiliser le prop `color`.
+- Icônes seules sans texte : ajouter `aria-label` ou wrapper `title` pour l'accessibilité.
+
+---
+
+## Responsive & PWA
+
+L'interface est conçue **mobile-first** pour un usage PWA (Progressive Web App).
+
+### Breakpoints Tailwind
+
+| Préfixe  | Largeur min | Contexte                 |
+| -------- | ----------- | ------------------------ |
+| _(base)_ | 0px         | Mobile (priorité)        |
+| `sm:`    | 640px       | Grands mobiles/tablettes |
+| `md:`    | 768px       | Tablettes                |
+| `lg:`    | 1024px      | Desktop                  |
+
+### Principes responsive
+
+- **Toujours** penser desktop en premier — les styles de base ciblent le desktop.
+- Les sidebars passent en overlay sur mobile (`md:hidden` / `hidden md:block`).
+- Les tableaux utilisent le mode `responsive-table` (classe utilitaire définie dans `tailwind.css`) sur mobile.
+- Les grilles : commencer par `grid-cols-1`, étendre avec `sm:grid-cols-2 lg:grid-cols-3`.
+- Les textes : tailles mobiles d'abord (`text-sm sm:text-base`), ne jamais forcer une grande taille sur mobile.
+- Touch targets : minimum `44px × 44px` pour tous les éléments interactifs (`min-h-[44px]`).
+
+### PWA
+
+- Tous les écrans doivent fonctionner hors-ligne ou en mode dégradé (données en cache).
+- Les interactions clés (navigation, actions principales) doivent être accessibles sans rechargement de page.
+- Pas de contenu critique uniquement visible au survol (`hover:`) — prévoir une alternative tactile.
+
+### Exemples responsive
+
+```jsx
+// Layout page
+<div className="px-4 sm:px-6 lg:px-8 py-4 sm:py-6">
+
+// Grille de cards
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+
+// Titre responsive
+<h1 className="font-headline text-xl sm:text-2xl lg:text-3xl font-bold">
+
+// Bouton full-width sur mobile
+<button className="w-full sm:w-auto bg-primary text-white px-4 py-2 rounded">
+
+// Navigation mobile/desktop
+<nav className="hidden md:flex gap-4">
+<nav className="flex md:hidden">  {/* version mobile */}
+```
+
+---
+
+## Bibliothèque de composants existants
+
+**Avant de créer un nouveau composant, toujours vérifier s'il en existe un dans `Front-End/src/components/`.**
+
+### Composants disponibles (inventaire)
+
+| Composant       | Chemin                        | Usage                                     |
+| --------------- | ----------------------------- | ----------------------------------------- |
+| `AlertMessage`  | `components/AlertMessage.js`  | Messages success / error / warning / info |
+| `Modal`         | `components/Modal.js`         | Fenêtre modale générique                  |
+| `Pagination`    | `components/Pagination.js`    | Pagination de listes                      |
+| `SectionHeader` | `components/SectionHeader.js` | En-tête de section avec icône             |
+| `ProgressStep`  | `components/ProgressStep.js`  | Étapes d'un formulaire multi-step         |
+| `EventCard`     | `components/EventCard.js`     | Card d'événement de planning              |
+| `Calendar/*`    | `components/Calendar/`        | Vues calendrier (semaine, mois…)          |
+| `Chat/*`        | `components/Chat/`            | Interface de messagerie                   |
+| `Evaluation/*`  | `components/Evaluation/`      | Formulaires d'évaluation                  |
+| `Grades/*`      | `components/Grades/`          | Affichage et saisie des notes             |
+| `Form/*`        | `components/Form/`            | Inputs, selects, composants de formulaire |
+| `Admin/*`       | `components/Admin/`           | Composants spécifiques à l'admin          |
+| `Charts/*`      | `components/Charts/`          | Graphiques et visualisations              |
+
+### Règles de réutilisation
+
+1. **Chercher avant de créer** : effectuer une recherche dans `components/` avant d'implémenter un nouveau composant.
+2. **Étendre, ne pas dupliquer** : si un composant existant est proche mais manque d'une variante, l'étendre via des props — ne pas créer une copie.
+3. **Props plutôt que fork** : passer des variantes via `variant`, `size`, `className` plutôt que de dupliquer le JSX.
+4. **Appliquer le design system dans les composants** : tout composant existant ou nouveau doit utiliser les tokens (`primary`, `secondary`, `tertiary`, `neutral`, `font-headline`, etc.) — jamais de couleurs codées en dur.
+
+---
+
+## Règles pour les agents IA (Copilot / Claude)
+
+1. **Couleurs interactives** : toujours utiliser `primary`, `secondary`, `tertiary`, `neutral` — jamais `emerald-*` pour les boutons, liens, icônes actives.
+2. **Typographie** : utiliser `font-headline` sur les `h1`/`h2`/`h3`. Le `font-body` est le défaut.
+3. **Arrondi** : préférer `rounded` (4px) pour les éléments courants. Éviter `rounded-xl` sauf exception justifiée.
+4. **Espacement** : respecter la grille 4px/8px. Pas de valeurs arbitraires `p-[13px]`.
+5. **Mode** : interface en mode **light** uniquement — ne pas ajouter de support dark mode.
+6. **Icônes** : utiliser uniquement `lucide-react` — jamais d'autres bibliothèques d'icônes.
+7. **Responsive** : mobile-first — les styles de base ciblent le mobile, les breakpoints `sm:`/`md:`/`lg:` étendent vers le haut.
+8. **PWA** : pas d'interactions uniquement au survol, touch targets ≥ 44px, navigation sans rechargement.
+9. **Réutilisation** : chercher un composant existant dans `components/` avant d'en créer un nouveau.