# 🎨 Guide des Bonnes Pratiques - Composants Frontend

> **Guide**: Design System Notytex  
> **Audience**: Développeurs Frontend & UI/UX Designers  
> **Version**: 1.0  
> **Mise à jour**: 7 août 2025

## 🎯 **Philosophie du Design System**

Notytex adopte une approche **moderne, cohérente et accessible** pour ses composants frontend. Chaque composant doit être **réutilisable**, **maintenable** et **évolutif**.

### 🏗️ **Principes Fondamentaux**
- **🔄 Réutilisabilité** : Un composant = plusieurs contextes
- **🎨 Cohérence** : Design tokens centralisés
- **📱 Responsive-first** : Mobile d'abord
- **♿ Accessibilité** : WCAG 2.1 AA minimum
- **⚡ Performance** : Optimisation native

---

## 📁 **Architecture des Composants**

### **Structure de Répertoires**
```
templates/components/
├── common/
│   ├── macros.html           # Macros réutilisables
│   └── base_components.html  # Composants de base
├── assessment/
│   └── assessment_card.html  # Cartes d'évaluation
├── class/
│   └── class_card.html       # Cartes de classe
├── forms/
│   ├── form_inputs.html      # Champs de formulaire
│   └── form_validation.html  # Validation UI
└── ui/
    ├── buttons.html          # Système de boutons
    ├── modals.html           # Modales
    └── notifications.html    # Toasts/Alerts
```

### **Convention de Nommage**
```
Type_Domain_Component.html
│    │      │
│    │      └─ Nom spécifique (card, button, modal...)
│    └──────── Domaine métier (assessment, class, user...)
└─────────────  Type (component, macro, layout...)
```

**📝 Exemples:**
- `assessment_card.html` ✅
- `class_list_item.html` ✅
- `user_profile_widget.html` ✅
- `genericCard.html` ❌ (PascalCase)
- `card.html` ❌ (trop générique)

---

## 🎨 **Design Tokens & Cohérence**

### **Palette de Couleurs Système**
```scss
// Couleurs Primaires
$blue:   from-blue-500 to-blue-600     // Actions principales
$green:  from-green-500 to-green-600   // Succès, validation
$purple: from-purple-500 to-purple-600 // Évaluations, analytique
$orange: from-orange-500 to-orange-600 // Avertissement, en cours
$red:    from-red-500 to-red-600       // Erreur, critique
$pink:   from-pink-500 to-pink-600     // Spécial, mise en avant

// Couleurs Neutres
$gray-50:  #f9fafb    // Fond très clair
$gray-100: #f3f4f6    // Fond clair
$gray-600: #4b5563    // Texte secondaire
$gray-900: #111827    // Texte principal
```

### **Typography Scale**
```scss
// Hiérarchie Textuelle
.text-4xl  { font-size: 2.25rem }  // Titres Hero
.text-3xl  { font-size: 1.875rem } // Titres principaux
.text-2xl  { font-size: 1.5rem }   // Titres sections
.text-xl   { font-size: 1.25rem }  // Sous-titres
.text-lg   { font-size: 1.125rem } // Texte large
.text-base { font-size: 1rem }     // Texte standard
.text-sm   { font-size: 0.875rem } // Texte petit
.text-xs   { font-size: 0.75rem }  // Métadonnées
```

### **Spacing System**
```scss
// Système d'espacement (Tailwind)
space-1: 0.25rem    // 4px
space-2: 0.5rem     // 8px
space-3: 0.75rem    // 12px
space-4: 1rem       // 16px
space-6: 1.5rem     // 24px
space-8: 2rem       // 32px
space-12: 3rem      // 48px
```

---

## 🧩 **Anatomie d'un Composant**

### **Template Structure**
```jinja2
{# 1. Commentaire de description #}
{# Composant pour [FONCTION] dans [CONTEXTE] #}

{# 2. Import des dépendances #}
{% from 'components/common/macros.html' import helper_macro %}

{# 3. Définition du macro principal #}
{% macro component_name(required_param, optional_param=default) %}

{# 4. Logique de configuration #}
{% set config = {
    'variant': optional_param,
    'classes': 'base-classes ' + (additional_classes if condition else '')
} %}

{# 5. Structure HTML avec données dynamiques #}
<div class="{{ config.classes }}" data-component="component-name">
    <!-- Contenu structuré -->
    {% if caller %}
        {{ caller() }}
    {% else %}
        <!-- Contenu par défaut -->
    {% endif %}
</div>

{# 6. Fin du macro #}
{% endmacro %}
```

### **Exemple Concret : Button Component**
```jinja2
{# Composant bouton avec variants et états #}

{% macro button(
    text, 
    url=None, 
    type="primary", 
    size="md", 
    icon=None,
    disabled=False,
    classes=""
) %}

{# Configuration des variants #}
{% set variants = {
    'primary': 'bg-gradient-to-r from-blue-500 to-blue-600 text-white',
    'secondary': 'bg-gray-50 text-gray-700 border border-gray-300',
    'danger': 'bg-gradient-to-r from-red-500 to-red-600 text-white'
} %}

{% set sizes = {
    'sm': 'px-3 py-2 text-sm',
    'md': 'px-4 py-2 text-base', 
    'lg': 'px-6 py-3 text-lg'
} %}

{# Classes finales #}
{% set button_classes = [
    'inline-flex items-center justify-center',
    'rounded-xl font-semibold transition-all duration-300',
    'hover:shadow-lg transform hover:scale-105',
    variants[type],
    sizes[size],
    'opacity-50 cursor-not-allowed' if disabled else '',
    classes
]|join(' ') %}

{# Rendu conditionnel (lien vs bouton) #}
{% if url and not disabled %}
    <a href="{{ url }}" class="{{ button_classes }}">
{% else %}
    <button type="button" class="{{ button_classes }}"{% if disabled %} disabled{% endif %}>
{% endif %}
    {% if icon %}
        <span class="w-5 h-5 mr-2">{{ icon|safe }}</span>
    {% endif %}
    {{ text }}
{% if url and not disabled %}</a>{% else %}</button>{% endif %}

{% endmacro %}
```

---

## 🎛️ **API des Composants**

### **Paramètres Standards**
Chaque composant doit exposer une API cohérente :

```jinja2
{% macro component_name(
    # === OBLIGATOIRES ===
    data,              # Données principales
    title,             # Titre/Label
    
    # === OPTIONNELS ===
    variant="default", # Type/Style (primary, secondary, danger...)
    size="md",         # Taille (sm, md, lg, xl)
    classes="",        # Classes CSS additionnelles
    
    # === COMPORTEMENT ===
    clickable=True,    # Interactif ou non
    disabled=False,    # État désactivé
    loading=False,     # État de chargement
    
    # === CONTENU ===
    icon=None,         # Icône SVG
    badge=None,        # Badge/Compteur
    actions=[],        # Liste d'actions
    
    # === TECHNIQUE ===
    id=None,          # ID HTML personnalisé
    attrs={}          # Attributs HTML additionnels
) %}
```

### **Exemple d'Utilisation**
```jinja2
{# Usage simple #}
{{ button("Sauvegarder") }}

{# Usage avancé #}
{{ button(
    text="Créer évaluation",
    url=url_for('assessments.new'),
    type="primary",
    size="lg", 
    icon='<svg>...</svg>',
    classes="w-full md:w-auto"
) }}
```

---

## 🔄 **États et Variants**

### **États Standardisés**
Tous les composants interactifs doivent gérer ces états :

```scss
// États de base
.default     // État normal
.hover       // Survol
.active      // Actif/Pressé  
.focus       // Focus clavier
.disabled    // Désactivé

// États applicatifs
.loading     // Chargement en cours
.success     // Succès/Validation
.error       // Erreur
.warning     // Avertissement
```

### **Variants de Style**
```scss
// Variants visuels
.primary     // Action principale (bleu)
.secondary   // Action secondaire (gris)
.success     // Succès (vert)
.warning     // Attention (orange) 
.danger      // Danger (rouge)
.ghost       // Transparent
.outline     // Contour seulement
```

### **Exemple : Card States**
```jinja2
{# États d'une carte #}
{% set card_states = {
    'default': 'bg-white shadow-lg hover:shadow-xl',
    'active': 'bg-blue-50 border-2 border-blue-200 shadow-xl',
    'disabled': 'bg-gray-50 opacity-50 cursor-not-allowed',
    'loading': 'bg-gray-50 animate-pulse'
} %}

<div class="rounded-xl transition-all duration-300 {{ card_states[state] }}">
    {% if state == 'loading' %}
        <div class="p-6">
            <div class="animate-pulse">
                <div class="h-4 bg-gray-300 rounded w-3/4 mb-2"></div>
                <div class="h-3 bg-gray-300 rounded w-1/2"></div>
            </div>
        </div>
    {% else %}
        <!-- Contenu normal -->
    {% endif %}
</div>
```

---

## 📱 **Responsive Design**

### **Breakpoints Standard**
```scss
// Mobile First approach
sm:  640px   // Téléphone large / Tablette portrait
md:  768px   // Tablette
lg:  1024px  // Desktop
xl:  1280px  // Large desktop
2xl: 1536px  // Ultra wide
```

### **Grilles Responsives**
```jinja2
{# Grille adaptative standard #}
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
    {% for item in items %}
        {{ item_card(item) }}
    {% endfor %}
</div>

{# Navigation responsive #}
<nav class="flex flex-col md:flex-row md:items-center space-y-4 md:space-y-0 md:space-x-6">
    <!-- Items navigation -->
</nav>
```

### **Typography Responsive**
```scss
// Échelle typographique adaptative
.hero-title {
    @apply text-2xl md:text-4xl lg:text-5xl;
}

.section-title {
    @apply text-lg md:text-xl lg:text-2xl;
}

.body-text {
    @apply text-sm md:text-base;
}
```

---

## ♿ **Accessibilité**

### **Checklist Obligatoire**
- [ ] **Contraste** ≥ 4.5:1 pour texte normal
- [ ] **Contraste** ≥ 3:1 pour texte large
- [ ] **Navigation clavier** complète
- [ ] **ARIA labels** sur éléments interactifs
- [ ] **Focus indicators** visibles
- [ ] **Screen reader** compatible

### **Implémentation**
```jinja2
{# Bouton accessible #}
<button
    type="button"
    class="focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
    aria-label="{{ accessible_label }}"
    {% if disabled %}aria-disabled="true"{% endif %}
    {% if has_popup %}aria-haspopup="true"{% endif %}
>
    {% if icon %}
        <span aria-hidden="true">{{ icon|safe }}</span>
    {% endif %}
    {{ text }}
</button>

{# Card interactive accessible #}
<div
    role="button"
    tabindex="0"
    class="cursor-pointer focus:ring-2 focus:ring-blue-500"
    aria-label="Voir détails de {{ item.name }}"
    onkeydown="if(event.key==='Enter'||event.key===' ') this.click()"
>
    <!-- Contenu carte -->
</div>
```

### **ARIA Patterns**
```html
<!-- Menu dropdown -->
<button aria-expanded="false" aria-haspopup="true" aria-controls="menu-1">
<ul id="menu-1" role="menu" aria-labelledby="menu-button-1">

<!-- Tabs -->
<div role="tablist" aria-label="Sections">
    <button role="tab" aria-selected="true" aria-controls="panel-1">
<div id="panel-1" role="tabpanel" aria-labelledby="tab-1">

<!-- Progress -->
<div role="progressbar" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
```

---

## ⚡ **Performance**

### **Optimisations Obligatoires**
```jinja2
{# 1. Lazy loading d'images #}
<img 
    src="{{ image.url }}" 
    loading="lazy"
    alt="{{ image.alt_text }}"
    class="w-full h-auto"
>

{# 2. SVG inline pour icônes #}
{% set icon_check %}
<svg class="w-5 h-5" fill="currentColor" viewBox="0 0 20 20">
    <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd"/>
</svg>
{% endset %}

{# 3. Classes CSS optimisées #}
{% set optimized_classes = [
    'base-class',
    'conditional-class' if condition else '',
    extra_classes
]|select|join(' ') %}
```

### **Métriques Cibles**
- **Temps de rendu** : <10ms par composant
- **Taille HTML** : <5KB par composant complexe  
- **CSS utilisé** : >80% des classes appliquées
- **JavaScript** : Minimal (interactions natives CSS)

---

## 🧪 **Tests & Validation**

### **Tests Automatisés**
```python
# test_components.py
def test_component_renders_without_error():
    """Test que le composant se rend sans erreur"""
    with app.app_context():
        template = app.jinja_env.get_template('components/class/class_card.html')
        # Test avec données minimales
        result = template.render(class=mock_class_data)
        assert len(result) > 0
        assert 'class_card' in result  # Vérifier présence indicateur

def test_component_handles_missing_data():
    """Test gestion des données manquantes"""
    with app.app_context():
        template = app.jinja_env.get_template('components/class/class_card.html')
        # Test avec données None/vides
        result = template.render(class=ClassGroup(name=None, students=[]))
        assert 'Aucune description' in result  # Message par défaut
        assert 'bg-gray-100' in result  # État "Vide"
```

### **Tests Visuels**
```bash
# Validation syntaxe tous templates
find templates/components -name "*.html" -exec echo "Testing {}" \; -exec uv run python -c "
from app import create_app
app = create_app()
with app.app_context():
    try:
        template = app.jinja_env.get_template('{}')
        print('✅ Syntaxe valide')
    except Exception as e:
        print(f'❌ Erreur: {e}')
        exit(1)
" \;

# Test responsive (manuel avec DevTools)
# 1. Mobile (375px)
# 2. Tablette (768px) 
# 3. Desktop (1024px)
# 4. Large screen (1440px)
```

### **Validation Accessibilité**
```bash
# Outils recommandés
axe-core        # Test automatisé
WAVE            # Extension navigateur
Lighthouse      # Audit complet
Screen Reader   # Test manuel (NVDA/JAWS/VoiceOver)
```

---

## 🔧 **Maintenance & Évolution**

### **Versioning des Composants**
```jinja2
{# Header de composant avec version #}
{# 
Component: class_card
Version: 1.2.0
Last Modified: 2025-08-07
Breaking Changes: None
Dependencies: macros.html v2.1+
#}
```

### **Changelog**
```markdown
## class_card v1.2.0 (2025-08-07)
### Added
- Support pour classes sans description
- Badge "Vide" pour classes sans élèves
- Extraction intelligente niveau de classe

### Changed
- Couleurs selon niveau au lieu d'année scolaire
- Actions regroupées en grid 2 colonnes

### Fixed
- Gestion cas classe.name None
- Responsive sur petits écrans

### Breaking Changes
- Paramètre `year` remplacé par extraction automatique
```

### **Dépréciation**
```jinja2
{# Composant déprécié - Prévoir migration #}
{% macro old_class_card(class) %}
{# 
⚠️  DEPRECATED: Ce composant sera supprimé en v3.0
    Utiliser class_card de components/class/class_card.html
    Migration guide: docs/frontend/MIGRATION_v2_to_v3.md
#}
<!-- Implementation dépréciée -->
{% endmacro %}
```

---

## 📚 **Ressources & Références**

### **Documentation Externe**
- **TailwindCSS** : [tailwindcss.com](https://tailwindcss.com)
- **WCAG Guidelines** : [w3.org/WAI/WCAG21/quickref](https://www.w3.org/WAI/WCAG21/quickref/)
- **Jinja2 Templates** : [jinja.palletsprojects.com](https://jinja.palletsprojects.com)
- **Design Tokens** : [design-tokens.github.io](https://design-tokens.github.io)

### **Outils Recommandés**
```bash
# Développement
Live Server        # Preview temps réel
DevTools           # Inspect & debug
ColorZilla         # Extraction couleurs
Figma/Adobe XD     # Design source

# Tests
axe DevTools       # Accessibilité
Lighthouse         # Performance & SEO
Browser Stack      # Tests cross-browser
Percy/Chromatic    # Visual regression
```

### **Templates de Référence**
- `assessment_card.html` - Carte complexe avec états multiples
- `hero_section` macro - Section d'en-tête avec gradient
- `simple_filter_section` - Filtres interactifs compacts
- `progress_indicator` - Indicateur de progression dynamique

---

## ✅ **Checklist Validation Composant**

Avant de valider un nouveau composant :

### **📝 Code Quality**
- [ ] **Syntaxe Jinja2** valide
- [ ] **Paramètres documentés** dans commentaires
- [ ] **Gestion d'erreurs** (None, empty, invalid data)
- [ ] **Performance** optimisée (classes, rendering)
- [ ] **Sécurité** (XSS prevention, safe filters)

### **🎨 Design System**
- [ ] **Couleurs** du design system utilisées
- [ ] **Typography** scale respectée  
- [ ] **Spacing** cohérent (multiples de 4px)
- [ ] **Animations** fluides (300ms transitions)
- [ ] **États visuels** définis (hover, focus, disabled)

### **📱 Responsive & Accessibility**
- [ ] **Mobile-first** approche
- [ ] **Breakpoints** standards utilisés
- [ ] **Contraste** suffisant (4.5:1 minimum)
- [ ] **Focus indicators** visibles
- [ ] **Screen reader** compatible

### **🧪 Tests**
- [ ] **Template rendering** sans erreur
- [ ] **Données variées** testées (vide, None, long text)
- [ ] **Navigation clavier** fonctionnelle  
- [ ] **Multi-browser** compatible
- [ ] **Visual regression** validé

### **📖 Documentation**
- [ ] **Usage examples** fournis
- [ ] **API parameters** documentés
- [ ] **Dependencies** listées
- [ ] **Migration guide** si breaking changes

---

**🎯 En suivant ce guide, tous les composants Notytex maintiendront un niveau de qualité et de cohérence exceptionnels !**