# Module — Design & templates des sites clients

> Industrialise l'**apparence** des boutiques WooCommerce des clients yima, là où le [connecteur](woocommerce-connector.md) industrialise la **donnée**. Plugin WordPress `yima-wc-design/`, indépendant du connecteur.

## 1. Objectif

Réduire le coût de conception d'un site client — aujourd'hui le poste le plus manuel et le moins
reproductible de l'offre — en fournissant des **kits sectoriels prêts à l'emploi** et une palette
pilotée depuis un écran unique, sans jamais enfermer le client : tout reste modifiable dans
**Elementor** après import.

Personas : l'**intégrateur yima** (monte le site d'une nouvelle boutique en quelques minutes) et le
**manager de boutique** (retouche ensuite ses pages seul, sans savoir-faire technique).

## 2. Périmètre

**In (v1)**
- Jetons de design (couleurs, polices, arrondis, largeur, densité) → variables CSS **et** couleurs/polices globales Elementor.
- En-tête et pied de page rendus par le plugin, en modèle Elementor éditable ou en rendu par défaut.
- Neutralisation de l'en-tête/pied du thème actif (Hello Elementor, Astra, OceanWP, GeneratePress, repli CSS).
- Sept widgets Elementor : bannière, grille produits, catégories, réassurance, contact, **menu** et **panier**. Les deux derniers comblent une lacune d'Elementor gratuit, qui n'en fournit aucun (réservés à Pro) — sans eux, aucun en-tête ne pourrait être construit dans l'éditeur.
- Habillage des pages WooCommerce sans surcharge de gabarit.
- Bibliothèque de kits sectoriels importables en un clic, réimport idempotent.
- **Aucune image de démonstration** : les bannières s'habillent d'un dégradé issu de la palette, les vignettes de catégorie ont un repli typographique, et les visuels produit viennent du catalogue réel. Le dépôt reste sans binaire et l'intégrateur ajoute les vraies photos.

**Out (initial)**
- Elementor **Pro** et son Theme Builder : la cible est la version **gratuite**.
- Pilotage du design depuis la PWA yima (couleurs/logo poussés par le backend) — voir §11.
- Surcharge des gabarits `woocommerce/*.php`, création automatique de sites WordPress, hébergement.
- Verrouillage des kits par plan de licence.

## 3. Entités

**Aucune entité côté yima.** Le plugin est autonome et stocke tout dans les options WordPress du
site client :

| Option | Contenu |
|---|---|
| `yima_design_tokens` | tableau des jetons (couleurs, polices, `radius`, `container_width`, `button_style`, `density`) |
| `yima_design_layout_enabled` | l'en-tête/pied Yima remplace-t-il celui du thème |
| `yima_design_header_id` / `yima_design_footer_id` | modèles `elementor_library` utilisés (0 = rendu par défaut) |
| `yima_design_hide_selectors` | sélecteurs CSS de repli pour un thème non pris en charge |
| `yima_design_woo_styling` / `woo_columns` / `woo_per_page` | habillage et grille de la boutique |
| `yima_design_shop_name` / `phone` / `whatsapp` | coordonnées, utilisées si le connecteur est absent |
| `yima_design_active_kit` / `yima_design_imported` | dernier kit appliqué et état des imports (pages, modèles, menu créés) — support de l'idempotence |

Ce choix est **contraint** : le backend yima ne stocke aujourd'hui aucune donnée de branding
(`StoreSetting` ne porte que le bloc WhatsApp, et `Company.logo` est servi derrière un
`MediaController` authentifié, donc inaccessible depuis WordPress).

## 4. Permissions

Sans objet côté yima (aucun endpoint). Côté WordPress : l'écran de réglages exige
`edit_theme_options`, l'import d'un kit exigera `manage_options` *(E3‑B)*, chaque soumission étant
protégée par un nonce.

## 5. API

**Aucun nouvel endpoint.** Le plugin ne dialogue pas avec yima. Il lit uniquement, en local et en
lecture seule, les options posées par `yima-wc-connector` (`yima_wc_wa_enabled`, `yima_wc_wa_number`,
`yima_wc_wa_message`) via `Yima_Design_Bridge` — sans jamais en dépendre.

## 6. Écrans

| Écran | Emplacement | Contenu |
|---|---|---|
| **Yima Design** | Apparence → Yima Design | bandeau d'état (Elementor / thème / connecteur), palette + palettes prédéfinies, typographie et formes, en-tête/pied, boutique, coordonnées |
| **Kits Yima** | Apparence → Kits Yima | vignettes des kits (aperçu de palette généré, sans capture d'écran à maintenir), import ou réimport en un clic |

Un kit est un simple dossier `kits/<slug>/` : `kit.json` (palette, en-tête, pied, pages, menu) et
des gabarits Elementor en JSON. **Ajouter un secteur ne demande donc aucun code.** Les gabarits
portent des marqueurs (`{{SHOP_NAME}}`, `{{WHATSAPP_LINK}}`, `{{URL:shop}}`) substitués à l'import.

Kits livrés :

| Kit | Parti pris |
|---|---|
| **Mode & accessoires** | Noir et sable, Playfair Display, angles nets, espacement aéré. Accueil : bannière, réassurance, nouveautés, rayons, promotions, contact. |
| **Alimentation & épicerie** | Vert, Poppins, angles très arrondis, boutons pilule. Les **rayons passent avant les produits** (grille 4 colonnes), puis meilleures ventes et promotions ; le panier affiche le total ; contact orienté « envoyez votre liste ». |
| **Électronique & téléphonie** | Bleu, Montserrat, angles nets. Sélection mise en avant d'abord, puis univers et nouveaux arrivages ; réassurance garantie / SAV / conseil ; la page « à propos » devient **Garantie & SAV**. |

Côté Elementor, une catégorie **Yima** regroupe les widgets.

## 7. Règles métier

- **Les jetons sont la source de vérité du style.** Aucune couleur n'est écrite en dur dans la
  feuille de style ni dans les gabarits des kits : tout passe par les variables CSS et les globales
  Elementor. Changer la palette re-skinne donc le site **sans rouvrir Elementor**.
- **Le POS reste maître de la visibilité produit.** La grille produits interroge WooCommerce avec
  `visibility = catalog` : un produit masqué par `Yima_Wc_Sync::apply_stock()` (rupture ou non
  publié dans yima) ne réapparaît jamais dans un widget.
- **Un seul bouton WhatsApp flottant.** Le flottant appartient au connecteur ; les widgets de ce
  plugin ne produisent que des boutons inline.
- **L'import d'un kit est idempotent** : réimporter met à jour les pages et modèles existants au
  lieu de les dupliquer, et **réversible** : « Retirer » remet les contenus à la corbeille et
  restaure le réglage de page d'accueil d'origine (mémorisé au premier import). On peut donc
  essayer plusieurs kits sans laisser de pages orphelines.
- **Qui rend l'en-tête ?** Si *Header Footer Elementor* est installé et fournit l'en-tête ou le
  pied, Yima Design lui laisse cette partie — la décision se prend **partie par partie**, sans quoi
  un site équipé des deux plugins afficherait deux pieds de page.
- **Dégradation sans erreur** : sans Elementor, seuls les jetons et l'habillage WooCommerce
  s'appliquent ; si un hook de thème disparaît, le masquage CSS prend le relais ; si un modèle
  d'en-tête est supprimé, le rendu par défaut reprend la main.

## 8. Projection e-commerce

Sans objet : le plugin vit entièrement sur le site WordPress du client et ne réplique aucune donnée.

## 9. Tests

Comme pour `yima-wc-connector`, il n'existe pas de suite automatisée côté plugin WordPress. La
vérification repose sur `php -l`, la validation JSON des gabarits et un **banc d'essai hors
WordPress** livré avec le plugin :

```bash
php yima-wc-design/tools/check-kits.php
```

Il rejoue `Yima_Design_Importer::prepare()` sur les kits réels et contrôle l'arbre
`section > column > widget`, l'unicité des identifiants Elementor, la substitution complète des
marqueurs, l'**absence de widget réservé à Elementor Pro**, la résolution des entrées de menu et
l'unicité de la page d'accueil. Sortie non nulle en cas d'erreur, donc branchable sur une CI.
**À lancer après toute modification d'un kit.** Le script est gardé par `PHP_SAPI !== 'cli'` : il ne
peut jamais s'exécuter via un serveur web.

**Vérifié en réel (E3‑D)** sur `127.0.0.1:81/amansa` — WordPress 7.0.2, Astra 4.13.6,
Elementor 4.2.0 **gratuit**, WooCommerce, 42 produits, connecteur yima actif : widgets enregistrés,
import en 268 ms, réimport sans doublon, cycle import → retrait → état d'origine identique, pages en
HTTP 200 sans erreur PHP, en-tête d'Astra neutralisé par hook natif, cohabitation HFE sans doublon.

La procédure reste **vérification manuelle consignée dans le [suivi](../07-suivi.md)**
sur le WordPress local (`127.0.0.1:81/amansa`) avec Elementor gratuit, WooCommerce et Hello
Elementor. Points contrôlés : palette → variables CSS + couleurs globales Elementor ; en-tête/pied
sur les quatre thèmes pris en charge ; grille produits respectant les produits masqués ;
cohabitation avec le connecteur (un seul bouton flottant) ; désactivation non destructive.

## 10. Dépendances

- **WordPress** 6.0+, **WooCommerce** 6.0+, **Elementor** 3.5+ (gratuit).
- Thème recommandé : **Hello Elementor**.
- `yima-wc-connector` : **optionnel**, uniquement pour reprendre le numéro WhatsApp.

## 11. Notes / ADR liés

- [ADR‑009](../notes/decisions.md) — design des sites clients par plugin de kits Elementor.
- Suite envisagée (**E3‑D**, non planifiée) : piloter le design depuis la PWA. Cela suppose
  d'étendre `StoreSetting` (couleurs, `themeKey`), d'enrichir `GET /api/connector/config` et de
  réutiliser `SiteConfigPusher` — le patron existe déjà pour WhatsApp. Le logo reste bloqué tant que
  `MediaController` exige une session authentifiée.
- `License.plan` (`standard`/`pro`) est le levier tout trouvé si le design devient une option
  facturée ; il ne conditionne rien aujourd'hui.