feat: documenting frontend
This commit is contained in:
216
docs/frontend/README.md
Normal file
216
docs/frontend/README.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# 📚 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 | ✅ |
|
||||
| [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 | 📋 |
|
||||
|
||||
### ⚡ **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. **Étudier** : [CLASS_CARD_COMPONENT.md](./CLASS_CARD_COMPONENT.md) pour l'API des composants
|
||||
4. **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)
|
||||
- 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.**
|
||||
|
||||
Reference in New Issue
Block a user