# 📚 Documentation Frontend - Notytex

> **Design System & Composants UI**  
> **Version**: 2.0  
> **Dernière mise à jour**: 7 août 2025

## 🎯 **Vue d'Ensemble**

Cette documentation couvre l'ensemble du **design system Notytex**, ses composants UI, et les bonnes pratiques pour maintenir une interface cohérente et moderne.

---

## 📁 **Organisation de la Documentation**

### 🎨 **Design System & Guidelines**

| Document                                                         | Description                                                               | Statut |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------- | ------ |
| **[COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)** | Guide complet des bonnes pratiques pour créer et maintenir des composants | ✅     |
| Design Tokens                                                    | Couleurs, typography, spacing centralisés                                 | 🔄     |
| Accessibility Guidelines                                         | Standards WCAG & implémentation                                           | 🔄     |

### 📄 **Pages & Interfaces**

| Document                                           | Description                                                      | Statut |
| -------------------------------------------------- | ---------------------------------------------------------------- | ------ |
| **[CLASSES_PAGE.md](./CLASSES_PAGE.md)**           | Page des classes modernisée - Architecture & guide d'utilisation | ✅     |
| **[CLASS_FORM.md](./CLASS_FORM.md)**               | Formulaire création/modification classes - Interface & UX        | ✅     |
| [ASSESSMENTS_FILTRES.md](./ASSESSMENTS_FILTRES.md) | Système de filtres des évaluations                               | ✅     |
| Dashboard Modernization                            | Page d'accueil & statistiques                                    | 📋     |
| Student Management Page                            | Interface de gestion des élèves                                  | 📋     |

### 🧩 **Composants**

| Document                                                 | Description                                     | Statut |
| -------------------------------------------------------- | ----------------------------------------------- | ------ |
| **[CLASS_CARD_COMPONENT.md](./CLASS_CARD_COMPONENT.md)** | Composant carte de classe - API & usage         | ✅     |
| [ASSESSMENT_CARDS.md](./ASSESSMENT_CARDS.md)             | Composants cartes d'évaluation                  | ✅     |
| Common Macros                                            | Macros réutilisables (hero_section, buttons...) | 📋     |
| **Form Components**                                      | **Champs de formulaire standardisés (voir CLASS_FORM.md)** | ✅     |

### ⚡ **Performance & Outils**

| Document               | Description                                 | Statut |
| ---------------------- | ------------------------------------------- | ------ |
| Performance Guidelines | Optimisation frontend & best practices      | 📋     |
| Testing Strategy       | Tests visuels, accessibilité, cross-browser | 📋     |
| Build & Deploy         | Process de build frontend                   | 📋     |

---

## 🚀 **Getting Started**

### **Pour les Nouveaux Développeurs**

1. **Lire d'abord** : [COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)
2. **Explorer** : [CLASSES_PAGE.md](./CLASSES_PAGE.md) comme exemple complet  
3. **Formulaires** : [CLASS_FORM.md](./CLASS_FORM.md) pour interfaces de saisie
4. **Composants** : [CLASS_CARD_COMPONENT.md](./CLASS_CARD_COMPONENT.md) pour l'API des composants
5. **Appliquer** : Créer son premier composant avec les guidelines

### **Pour les Designers**

1. **Design System** : Couleurs, typography, spacing dans [COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)
2. **Exemples concrets** : [CLASSES_PAGE.md](./CLASSES_PAGE.md) pour voir l'application pratique
3. **Composants disponibles** : Inventaire dans chaque doc de composant

### **Pour la Maintenance**

1. **Standards** : Tous les composants suivent [COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)
2. **Tests** : Procédures de validation dans chaque documentation
3. **Evolution** : Guidelines de versioning et migration

---

## 🎨 **Design System en Bref**

### **Couleurs Principales**

```scss
// Couleurs par niveau scolaire
6ème: from-blue-500 to-blue-600      // Actions primaires
5ème: from-green-500 to-green-600    // Succès, validation
4ème: from-purple-500 to-purple-600  // Évaluations, analytics
3ème: from-orange-500 to-orange-600  // Avertissement, en cours
2nde: from-red-500 to-red-600        // Erreur, critique
1ère: from-pink-500 to-pink-600      // Spécial, highlight
Term: from-indigo-500 to-indigo-600  // Excellence, Terminales
???: from-gray-500 to-gray-600       // Non reconnu, neutres
```

### **Components Architecture**

```
templates/components/
├── common/          # Macros & composants de base
├── assessment/      # Composants liés aux évaluations
├── class/          # Composants liés aux classes
├── forms/          # Composants de formulaire
└── ui/            # Composants UI génériques
```

### **Responsive Breakpoints**

```scss
sm:  640px    // Téléphone large / Tablette portrait
md:  768px    // Tablette
lg:  1024px   // Desktop
xl:  1280px   // Large desktop
```

---

## 📊 **État de la Documentation**

### **✅ Complété (100%)**

- Guide des bonnes pratiques générales
- Page des classes (refonte complète)
- **Formulaire de classe (création/modification complet)**
- Composant class_card (documentation technique)
- Filtres des évaluations
- Cartes d'évaluation

### **🔄 En cours (0-80%)**

- Design tokens centralisés
- Guidelines d'accessibilité
- Tests automatisés frontend

### **📋 À faire**

- Documentation page Dashboard
- Documentation gestion des élèves
- Composants de formulaire
- Guide de performance
- Process de build/deploy

---

## 🧪 **Tests & Validation**

### **Tests Rapides**

```bash
# Validation syntaxe tous les templates
find templates/ -name "*.html" -exec echo "Testing {}" \;

# Test des composants principaux
uv run python -c "
from app import create_app
app = create_app()
with app.app_context():
    templates = ['classes.html', 'components/class/class_card.html']
    for template in templates:
        try:
            t = app.jinja_env.get_template(template)
            print(f'✅ {template}')
        except Exception as e:
            print(f'❌ {template}: {e}')
"
```

### **Tests Complets**

- **Syntaxe** : Tous templates Jinja2 valides
- **Responsive** : Tests sur tous breakpoints
- **Accessibilité** : Tests axe-core + validation manuelle
- **Cross-browser** : Chrome, Firefox, Safari, Edge
- **Performance** : Métriques Lighthouse > 90

---

## 🔗 **Liens Utiles**

### **Références Externes**

- **TailwindCSS Docs** : [tailwindcss.com/docs](https://tailwindcss.com/docs)
- **WCAG Guidelines** : [w3.org/WAI/WCAG21](https://www.w3.org/WAI/WCAG21/quickref/)
- **Jinja2 Templates** : [jinja.palletsprojects.com](https://jinja.palletsprojects.com/en/3.0.x/)
- **Flask Documentation** : [flask.palletsprojects.com](https://flask.palletsprojects.com/)

### **Outils Recommandés**

- **Design** : Figma, Adobe XD
- **Development** : Live Server, DevTools
- **Testing** : axe DevTools, Lighthouse, Percy
- **Performance** : WebPageTest, GTMetrix

---

## 📝 **Contribution**

### **Ajouter une Nouvelle Page**

1. Créer le fichier `PAGENAME_PAGE.md`
2. Suivre la structure de [CLASSES_PAGE.md](./CLASSES_PAGE.md)
3. Documenter les composants créés
4. Mettre à jour ce README.md

### **Ajouter un Composant**

1. Créer le fichier `COMPONENTNAME_COMPONENT.md`
2. Suivre la structure de [CLASS_CARD_COMPONENT.md](./CLASS_CARD_COMPONENT.md)
3. Inclure API, exemples, et tests
4. Référencer dans [COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)

### **Standards de Documentation**

- **Format** : Markdown avec emojis et structure claire
- **Code examples** : Syntaxe highlighting appropriée
- **Images** : Screenshots et diagrammes si pertinent
- **Liens** : Cross-references entre documents
- **Versioning** : Dates de mise à jour et changelogs

---

**🎓 Cette documentation évolue avec Notytex. Chaque ajout de fonctionnalité frontend doit être documenté selon ces standards.**