notytex/docs/frontend/README.md

📚 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	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	Page des classes modernisée - Architecture & guide d'utilisation	✅
CLASS_FORM.md	Formulaire création/modification classes - Interface & UX	✅
ASSESSMENT_RESULTS_PAGE.md	Page résultats évaluation - Heatmaps & analyses avancées	✅
CONSEIL_DE_CLASSE_JS.md	Module JavaScript Conseil de Classe - Mode Focus & Auto-save	✅
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	Composant carte de classe - API & usage	✅
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
2. Explorer : CLASSES_PAGE.md comme exemple complet
3. Formulaires : CLASS_FORM.md pour interfaces de saisie
4. Composants : 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
2. Exemples concrets : 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
2. Tests : Procédures de validation dans chaque documentation
3. Evolution : Guidelines de versioning et migration

---

🎨 Design System en Bref

Couleurs Principales

// 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

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)
• Page des résultats d'évaluation (heatmaps & analyses)
• 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

# 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
• WCAG Guidelines : w3.org/WAI/WCAG21
• Jinja2 Templates : jinja.palletsprojects.com
• Flask Documentation : 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
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
3. Inclure API, exemples, et tests
4. Référencer dans 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.