[Nom du Composant]

Type de ressource : Composant Astro (UI atomique / Îlot interactif)
Fichier source : src/components/[ui|interactive]/[NomComposant].astro
Statut : [Actif / Déprécié / En développement]
Slice : [Numéro de la tranche verticale]
Version : 1.0

---

1. Vue d’ensemble (DOC)

1.1. Description

[Description concise du rôle de ce composant dans l’interface utilisateur]

1.2. Objectif

• [Objectif principal : ex. afficher un bouton d’action réutilisable]
• [Bénéfice pour l’UX ou l’architecture]

1.3. Caractéristiques

Propriété	Valeur
Type	[UI atomique / Îlot interactif]
Hydratation	[Aucune / client:load / client:visible / client:idle]
Framework JS	[Aucun / React / Vue / Svelte / Web Component]
Accessibilité	[WCAG AA conforme / Partiellement conforme / Non testé]
Responsive	[Mobile-first / Desktop-first]

---

2. Architecture et structure (DOC)

2.1. Emplacement dans l’arborescence

src/components/
├── ui/                      # Composants atomiques (HTML + CSS purs)
│   ├── Button.astro
│   ├── Badge.astro
│   └── [NomComposant].astro
└── interactive/             # Îlots dynamiques (React/Vue/Svelte)
    ├── MobileNav.tsx
    ├── Carousel.tsx
    └── [NomComposant].tsx

2.2. Composants dépendants

Composant parent	Fichier	Relation
[Nom du parent]	src/components/[chemin]	[Composition / Wrapper]

2.3. Composants enfants utilisés

Composant enfant	Fichier	Rôle
[Nom de l’enfant]	src/components/[chemin]	[Description]

---

3. Implémentation (CODE)

3.1. Variante : Composant UI atomique (HTML + CSS purs)

src/components/ui/[NomComposant].astro

---
interface Props {
  label: string;
  variant?: 'primary' | 'secondary' | 'outline';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  href?: string;
  onClick?: () => void;
}

const {
  label,
  variant = 'primary',
  size = 'md',
  disabled = false,
  href,
  onClick,
} = Astro.props;

const baseClasses = 'inline-flex items-center justify-center font-medium rounded-lg transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2';

const variantClasses = {
  primary: 'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500',
  secondary: 'bg-gray-600 text-white hover:bg-gray-700 focus:ring-gray-500',
  outline: 'border-2 border-blue-600 text-blue-600 hover:bg-blue-50 focus:ring-blue-500',
};

const sizeClasses = {
  sm: 'px-3 py-1.5 text-sm',
  md: 'px-4 py-2 text-base',
  lg: 'px-6 py-3 text-lg',
};

const classes = `${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]} ${disabled ? 'opacity-50 cursor-not-allowed' : ''}`;
---

{href ? (
  <a
    href={href}
    class={classes}
    aria-disabled={disabled}
  >
    {label}
  </a>
) : (
  <button
    class={classes}
    disabled={disabled}
    onClick={onClick}
  >
    {label}
  </button>
)}

3.2. Variante : Îlot interactif (React)

src/components/interactive/[NomComposant].tsx

import { useState } from 'react';

interface Props {
  initialValue?: number;
}

export default function Counter({ initialValue = 0 }: Props) {
  const [count, setCount] = useState(initialValue);

  return (
    <div class="flex items-center gap-4">
      <button onClick={() => setCount(c => c - 1)}>-</button>
      <span>{count}</span>
      <button onClick={() => setCount(c => c + 1)}>+</button>
    </div>
  );
}

---

4. Contrats d’Entrée/Sortie (SPEC)

4.1. Inputs (Props)

Prop	Type	Obligatoire	Validation
label	string	✅	Non vide
variant	enum	❌	Valeur par défaut
size	enum	❌	Valeur par défaut

4.2. Outputs (Rendu)

Élément	Type	Description
HTML	HTMLElement	Composant rendu
Événements	Event	onClick, onChange, etc.

4.3. États (si interactif)

État	Type	Description
count	number	Valeur du compteur

---

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Rendu avec props	Props valides	Composant rendu correctement
Accessibilité	Test ARIA	Conforme WCAG AA
Responsive	Test mobile/desktop	Adaptation correcte

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Intégration parent	Composant parent	Utilisation dans une page	Fonctionne correctement

5.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Interaction utilisateur	Clic / Interaction	Action utilisateur	Réponse attendue

---

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Page parent	L2	Utilisation du composant	Import et rendu
Layout	L2	Inclusion globale	Import dans layout

6.2. Points d’attention

• Les props doivent être typées avec TypeScript
• L’accessibilité doit être conforme WCAG AA
• Le composant doit être responsive

6.3. Vérification de cohérence

• Le composant fonctionne en isolation
• Le composant s’intègre correctement avec les parents
• Les tests d’accessibilité passent
• Les tests E2E passent

---

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Validation des props
• ✅ Protection XSS (Astro par défaut)
• ✅ Sanitization du contenu utilisateur

7.2. Règles de sécurité

• ✅ Ne jamais exécuter de code utilisateur non sécurisé
• ✅ Valider toutes les entrées
• ✅ Utiliser les attributs ARIA appropriés

---

8. Performance et limites

8.1. Hydratation

Directive	Description
client:load	Hydratation immédiate
client:visible	Hydratation quand visible
client:idle	Hydratation quand le navigateur est inactif

8.2. Limitations

• ❌ Les îlots interactifs augmentent le bundle size
• ❌ L’hydratation peut affecter le LCP

---

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Composant non rendu	Props manquantes	Vérifier les props
Hydratation échoue	Erreur JavaScript	Vérifier la console
Accessibilité échoue	ARIA manquant	Ajouter les attributs

9.2. Commandes de debug

# Lancer les tests
npm run test

# Lancer les tests E2E
npm run test:e2e

---

10. Bonnes pratiques

10.1. Architecture

• ✅ Composants atomiques réutilisables
• ✅ Props typées avec TypeScript
• ✅ Accessibilité par défaut

10.2. Code

• ✅ Utiliser les classes Tailwind pour le style
• ✅ Éviter les effets de bord
• ✅ Documenter les props complexes

10.3. Maintenance

• ✅ Documenter les changements dans ce fichier
• ✅ Tester les modifications en local

---

11. Évolutions et roadmap

11.1. Améliorations planifiées

• [Évolution 1]
• [Évolution 2]

11.2. Limitations connues

• ❌ [Limitation 1]
• ❌ [Limitation 2]

---

12. Ressources liées

• Documentation Astro : Components
• Documentation Astro : Islands
• DAT L2 : §5.4 - Stratégie d’Hydratation

---

13. Historique des modifications

Date	Version	Description	Auteur
YYYY-MM-DD	1.0	Création initiale	[Nom]