Étape 6 - Theming Drupal

⏱️ Durée estimée : 5h

🎯 Objectifs de cette étape

À la fin de cette étape, vous serez capable de :

• ✅ Créer un thème personnalisé Drupal
• ✅ Comprendre le système de templates Twig
• ✅ Personnaliser l’affichage du contenu
• ✅ Ajouter des CSS et JavaScript au thème
• ✅ Intégrer Tailwind CSS dans Drupal
• ✅ Utiliser Alpine.js pour les interactions

📋 Prérequis

• Étape 5 terminée (navigation, blocs, menus)
• HTML/CSS : Structure sémantique, flexbox/grid, responsive design
• Twig : Notion de templating (sera approfondi dans cette étape)
• Template TailStore analysé (référence visuelle depuis l’Étape 1)
• Node.js >= 18.x et npm >= 9.x installés (pour Tailwind/Alpine.js)

🧰 Avant de commencer

Vérifier votre environnement

# Node.js et npm (pour Tailwind/Alpine)
node --version  # >= 18.x
npm --version   # >= 9.x

# Composer (pour dépendances Drupal)
composer --version  # >= 2.x

# Drush
drush --version  # >= 12.x

Créer un backup de sécurité

# Sauvegarder la base de données avant modifications
drush sql:dump > backup-avant-etape6.sql

# En cas de problème, restaurer avec :
# drush sql:cli < backup-avant-etape6.sql

Activer le mode développement

# Désactiver le cache pour voir les modifications en temps réel
drush state:set system.performance css_preprocess 0 --input-format=string
drush state:set system.performance js_preprocess 0 --input-format=string
drush cr

📚 Sommaire

Approche progressive : Nous suivrons une méthodologie logique — d’abord la structure du thème, puis les outils (CSS/JS), ensuite les templates Twig pour personnaliser l’affichage, et enfin l’interactivité avec Alpine.js.

1. Créer un thème

Structure et fichiers de base d’un thème. Voir →

2. Templates Twig

Personnaliser l’affichage avec Twig. Voir →

3. Assets (CSS/JS)

Ajouter des librairies CSS et JavaScript. Voir →

4. Tailwind CSS

Intégrer Tailwind CSS v4 dans Drupal. Voir →

5. Alpine.js

Ajouter des interactions dynamiques. Voir →

🏗️ Architecture du thème TailStore

Structure de fichiers

themes/custom/tailstore/
├── tailstore.info.yml          # Déclaration du thème
├── tailstore.libraries.yml      # CSS et JS
├── tailstore.theme              # Fonctions PHP
├── tailstore.breakpoints.yml    # Points de rupture responsive
│
├── css/
│   ├── base/
│   │   ├── reset.css
│   │   └── typography.css
│   ├── components/
│   │   ├── buttons.css
│   │   ├── cards.css
│   │   ├── forms.css
│   │   └── navigation.css
│   ├── layout/
│   │   ├── grid.css
│   │   └── regions.css
│   └── tailstore.css            # Import principal
│
├── js/
│   ├── tailstore.js             # Scripts principaux
│   ├── cart.js                  # Panier
│   └── slider.js                # Carousel
│
├── images/
│   ├── logo.svg
│   └── icons/
│
├── templates/
│   ├── layout/
│   │   ├── page.html.twig
│   │   └── region.html.twig
│   ├── block/
│   │   ├── block.html.twig
│   │   └── block--system-branding-block.html.twig
│   ├── node/
│   │   ├── node.html.twig
│   │   ├── node--product.html.twig
│   │   ├── node--product--teaser.html.twig
│   │   └── node--product--card.html.twig
│   ├── field/
│   │   └── field--field-price.html.twig
│   ├── views/
│   │   └── views-view--products-catalog.html.twig
│   └── misc/
│       ├── pager.html.twig
│       └── breadcrumb.html.twig
│
└── config/
    └── install/
        └── tailstore.settings.yml

🎨 Design System TailStore

Tokens CSS (Design Tokens)

💡 Pourquoi des tokens ?

• Centraliser les valeurs de design (couleurs, espacements, typographie)
• Faciliter le rebranding (modifier une variable = tout le site)
• Supporter le mode sombre (dark mode) facilement
• Assurer la cohérence visuelle sur tout le site

Couleurs

Variable	Hex	Usage
--color-primary	#0073e6	Actions principales
--color-secondary	#6c757d	Actions secondaires
--color-success	#28a745	Succès, en stock
--color-warning	#ffc107	Alertes
--color-danger	#dc3545	Erreurs, soldes
--color-dark	#1a1a2e	Texte principal
--color-light	#f8f9fa	Arrière-plans

Typographie

Élément	Font	Size	Weight
H1	Inter	2.5rem	700
H2	Inter	2rem	600
H3	Inter	1.5rem	600
Body	Inter	1rem	400
Small	Inter	0.875rem	400
Price	Inter	1.25rem	700

Espacements

--spacing-xs: 0.25rem;  /* 4px */
--spacing-sm: 0.5rem;   /* 8px */
--spacing-md: 1rem;     /* 16px */
--spacing-lg: 1.5rem;   /* 24px */
--spacing-xl: 2rem;     /* 32px */
--spacing-2xl: 3rem;    /* 48px */

🔄 Workflow de développement

Mode développement

# Désactiver l'agrégation CSS/JS via Drush
drush state:set system.performance css_preprocess 0 --input-format=string
drush state:set system.performance js_preprocess 0 --input-format=string

Activer le débogage Twig dans sites/default/services.yml :

parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

⚠️ Mode développement uniquement

Cette configuration doit être désactivée en production pour des raisons de performance. Le débogage Twig génère des commentaires HTML volumineux.

# Vider le cache après modification
drush cr

Rafraîchir après modification

# Cache des templates
drush cr

# Cache des CSS (si agrégation activée)
drush cc css-js

🛠️ Outils recommandés

Extensions VS Code

• Drupal Syntax Highlighting
• Twig Language 2
• Tailwind CSS IntelliSense
• Alpine.js IntelliSense

Inspection du DOM

1. Activez le débogage Twig
2. Inspectez le HTML source pour voir :
   • Les suggestions de templates
   • Les variables disponibles
   • Les chemins des fichiers

<!-- THEME DEBUG -->
<!-- THEME HOOK: 'node' -->
<!-- FILE NAME SUGGESTIONS:
   * node--product--full.html.twig
   * node--product.html.twig
   * node--1.html.twig
   * node.html.twig
-->
<!-- BEGIN OUTPUT from 'themes/custom/tailstore/templates/node/node--product.html.twig' -->

📊 Composants à créer (par ordre de développement)

Stratégie : Commencer par les composants de base (header, footer), puis les éléments de contenu (produits), et enfin les interactions avancées (slider, panier dynamique).

Priorité	Composant	Template	Difficulté	Étape	Temps
🔴 1	Header + Logo	block--system-branding-block.html.twig	⭐ Facile	6.1-6.2	30min
🔴 2	Footer	region--footer.html.twig	⭐ Facile	6.2	30min
🔴 3	Product Card	node--product--card.html.twig	⭐⭐ Moyen	6.2	1h
🟠 4	Product Teaser	node--product--teaser.html.twig	⭐⭐ Moyen	6.2	45min
🟠 5	Homepage Layout	page--front.html.twig	⭐⭐ Moyen	6.4	1h30
🟠 6	Shop/Catalog	page--shop.html.twig	⭐⭐ Moyen	6.4	1h
🟡 7	Mega Menu	menu--main.html.twig	⭐⭐⭐ Difficile	6.5	2h
🟡 8	Hero Slider	block--hero-banner.html.twig	⭐⭐⭐ Difficile	6.5	2h
🟢 9	Cart Icon (dynamique)	block--cart-summary.html.twig	⭐⭐⭐ Difficile	6.5	1h30
🔵 10	Fiche produit complète	node--product--full.html.twig	⭐⭐⭐⭐ Expert	6.2-6.5	2h

Légende priorités :

• 🔴 Priorité haute — Fondations du thème (commencer par là)
• 🟠 Priorité moyenne — Contenu principal (après les bases)
• 🟡 Priorité basse — Fonctionnalités avancées (quand le reste fonctionne)
• 🔵 Bonus/Expert — Fonctionnalités complexes (si temps disponible)

🎨 Système de design

Architecture des composants

Le thème suit une approche atomique pour une maintenabilité optimale :

1. Atomes (Atoms)

• Boutons : .btn, .btn-primary, .btn-secondary
• Champs de formulaire : .form-input, .form-select
• Icônes : .icon, .icon--large

2. Molécules (Molecules)

• Product Card : Image + titre + prix + bouton
• Search Bar : Input + bouton recherche
• Navigation Item : Lien + icône

3. Organismes (Organisms)

• Header : Logo + menu + recherche + panier
• Footer : Liens + newsletter + réseaux sociaux
• Product Grid : Collection de product cards

Parcours utilisateur e-commerce

1. Homepage → 2. Catalogue → 3. Fiche produit → 4. Panier → 5. Checkout → 6. Confirmation
   (page.html)   (views)       (node--product)    (custom)    (custom)     (custom)

Chaque étape nécessite des templates et styles spécifiques.

🚨 Erreurs courantes à éviter

❌ Erreur 1 : Oublier de vider le cache

Symptôme : Modifications CSS/Twig non visibles dans le navigateur
Solution : drush cr après CHAQUE modification de template ou CSS
💡 Astuce : En mode dev avec cache: false, seul le cache de routing nécessite un flush

❌ Erreur 2 : Mélanger Tailwind et CSS custom

Problème : Conflits entre utility classes et CSS personnalisé
Bonne pratique : Utiliser Tailwind à 95%, CSS custom pour <5% des cas exceptionnels
Exemple valide : Animations complexes, reset CSS spécifique

❌ Erreur 3 : Modifier les templates du core

Danger : Modifications perdues lors des mises à jour Drupal
Bonne pratique : TOUJOURS copier les templates dans themes/custom/tailstore/templates/
Jamais : Modifier directement dans core/themes/ ou modules/contrib/

❌ Erreur 4 : Template trop générique

Problème : node.html.twig s’applique à TOUS les types de contenu
Bonne pratique : Utiliser les suggestions spécifiques :

• ✅ node--product--full.html.twig (type + mode d’affichage)
• ✅ node--product.html.twig (type de contenu)
• ❌ node.html.twig (trop large)

❌ Erreur 5 : Ignorer le responsive

Problème : Site cassé sur mobile/tablette
Bonne pratique : Tester sur plusieurs tailles (F12 → Toggle Device Toolbar)
Points de rupture Tailwind : sm: (640px), md: (768px), lg: (1024px), xl: (1280px)

❌ Erreur 6 : Charger tous les assets globalement

Problème : 200KB de JS/CSS sur toutes les pages, même inutiles
Bonne pratique : Charger conditionnellement via hook_preprocess_HOOK()
Exemple : Slider JS uniquement sur la homepage

🎯 Mission finale de cette étape

À la fin de l’étape 6, vous devrez avoir réalisé :

Livrables obligatoires

• Thème fonctionnel : Structure complète avec tailstore.info.yml et tailstore.libraries.yml
• 3 templates Twig personnalisés : Au minimum header, product card, footer
• Tailwind CSS intégré : Configuration fonctionnelle avec purge activé
• 1 interaction Alpine.js : Menu mobile, modale, ou panier dynamique
• Homepage stylisée : Reprenant visuellement le template TailStore

Critères de validation

✅ Fonctionnel : Le site affiche correctement tous les contenus
✅ Responsive : Mise en page adaptée mobile/tablette/desktop
✅ Performance : CSS < 100KB, pas de JS inutile chargé
✅ Code propre : Templates commentés, structure logique
✅ Debug désactivé : Pas de {{ dump() }} oublié dans les templates

💡 Checkpoint de progression

Après chaque sous-étape, vérifiez :

Sous-étape	Résultat visible
6.1 Création thème	Thème activable dans l’admin, logo affiché
6.2 Twig	Header et footer personnalisés visibles
6.3 Assets	CSS chargé (inspecter le <head>)
6.4 Tailwind	Classes Tailwind appliquées (ex: bg-blue-500 fonctionne)
6.5 Alpine.js	Menu mobile ou interaction fonctionnelle

🧠 Bonnes pratiques essentielles

🔒 Sécurité Twig

⚠️ Échappement automatique

Twig échappe automatiquement toutes les variables pour prévenir les attaques XSS.

Ne JAMAIS utiliser {{ variable|raw }} sauf si vous êtes absolument certain du contenu.

Préférer :

{{ content.field_body }}  {# Échappe automatiquement #}
{{ content }}             {# Rendu Drupal sécurisé #}

Éviter :

{{ unsafe_html|raw }}     {# Danger XSS ! #}

⚡ Performance

💡 Optimisation Tailwind

Problème : Tailwind génère 3MB+ de CSS en mode développement.

Solution : Configurer le purge pour supprimer les classes inutilisées en production.

Objectif : < 50KB de CSS final après purge et minification.

Configuration dans tailwind.config.js :

module.exports = {
  content: [
    './templates/**/*.twig',
    './js/**/*.js',
  ],
  // ... autres configs
}

Le purge analyse vos fichiers et ne garde que les classes utilisées.

♿ Accessibilité (WCAG)

♿ Checklist accessibilité

Chaque composant créé DOIT respecter :

✅ Contraste : Minimum WCAG AA (4.5:1 pour texte normal, 3:1 pour texte large)
✅ Navigation clavier : Tab, Enter, Esc fonctionnels
✅ Attributs ARIA : aria-label, role, aria-expanded quand nécessaire
✅ Ordre des headings : h1 → h2 → h3 (pas de saut de niveau)
✅ Images : Attribut alt obligatoire (description ou alt="" si décorative)

Outils de test :

• Extension Chrome/Firefox : axe DevTools
• Lecteur d’écran : NVDA (Windows), JAWS, VoiceOver (Mac)
• Vérificateur de contraste : WebAIM Contrast Checker

🎨 Ressources et inspirations

Thèmes Drupal à étudier

• Olivero (thème par défaut Drupal 10/11) : Système de tokens CSS moderne
• Claro (admin theme) : Composants UI accessibles
• Gin (contrib) : Interface admin moderne avec design system

Librairies CSS/JS recommandées

• Tailwind UI : Composants e-commerce prêts à l’emploi (payant)
• Flowbite : Composants Tailwind + Alpine.js (gratuit)
• DaisyUI : Framework de composants basé sur Tailwind
• Headless UI : Composants accessibles sans style (à combiner avec Tailwind)

Documentation technique

• Twig Documentation : Référence complète du moteur de template
• Drupal Twig Functions : Fonctions et filtres Drupal
• Drupal Theme System : Guide officiel theming
• Tailwind CSS v4 Docs : Documentation officielle Tailwind

Outils de développement

Extensions VS Code recommandées :

• Drupal Syntax Highlighting : Coloration syntaxique Drupal
• Twig Language 2 : Support Twig avec autocomplétion
• Tailwind CSS IntelliSense : Autocomplétion classes Tailwind
• Alpine.js IntelliSense : Support Alpine.js

🚀 C’est parti !

Vous avez maintenant une vision complète de l’étape 6. Commencez par Créer le thème.