# Agent instructions - Viti Theme Bundle

Ce dossier contient le bundle Symfony UX charge des themes front raccordes a Viti-core.

## Objectif

Creer et maintenir des themes Twig reutilisables pour les sites viticoles bases sur Viti-core.

## Contraintes techniques

- Framework : Symfony 7.4.
- Rendu : Twig serveur uniquement.
- Interactivite : Symfony UX, Stimulus, Turbo, TwigComponent ou LiveComponent selon le besoin.
- Ne pas generer de React, Vue, shadcn/ui ou dependance front hors stack Symfony UX sans validation.
- Ne pas modifier le bundle `cpcreation/viti-core` depuis ce dossier.
- Garder les templates compatibles avec les variables et routes exposees par Viti-core.
- Favoriser des composants Twig reutilisables et des blocs Twig stables.
- Les themes peuvent vivre dans `themes/<theme>` pour un theme embarque ou dans un package Composer dedie de type `viti-theme`.
- Les assets sources de theme vivent dans `assets` a la racine du theme resolu.
- Les assets publics publiables vivent dans `public` a la racine du theme resolu.
- Les templates de theme vivent dans `templates` a la racine du theme resolu.

## Themes

- Le premier theme est `theme-default`.
- Chaque theme doit contenir son propre `AGENTS.md`, `theme.json` et une reference de design lisible par les agents.
- La reference de design du theme vit generalement dans `DESIGN.md` a la racine du theme.
- Si le theme dispose d'un support Stitch, il peut aussi contenir une reference `.stitch/DESIGN.md`.
- Ne pas supposer qu'un theme a un support Stitch : la source de verite visuelle est la reference de design disponible pour ce theme.
- `theme.json` est la source de verite machine pour Symfony.
- Un theme distribue hors bundle doit fournir un `composer.json` avec `type: viti-theme` et `extra.viti-theme.name`.

## Workflow theme

1. Lire le `AGENTS.md` du theme.
2. Lire la reference de design disponible pour ce theme (`DESIGN.md`, puis `.stitch/DESIGN.md` si le theme l'utilise).
3. Produire du HTML semantique compatible Twig.
4. Convertir les references visuelles, maquettes ou ecrans sources en templates Twig et CSS/SCSS.
5. Respecter les blocks existants et ne pas renommer les variables metier.

## Contrat de surcharge des themes

- Un theme reutilisable doit permettre au projet hote de modifier les variations courantes sans recopier un template complet.
- Definir des blocks Twig semantiques et stables pour les zones de markup qui varient reellement : marque, navigation, actions du header, colonnes et liens du footer, mentions legales, media ou contenu d'un hero.
- Ne pas creer un block pour chaque valeur atomique. Utiliser une prop de composant, la configuration, les traductions ou les donnees administrables pour un chemin d'image, un libelle, une URL ou une option simple.
- Preferer un composant Twig partage pour un module repete, par exemple le logo clair/sombre, plutot que dupliquer son markup dans le header, le menu mobile et le footer.
- Considerer les noms des blocks, props et templates surchargeables comme une interface publique : ne pas les renommer sans strategie de compatibilite.
- Un block declare dans un template charge par `include` n'est pas surchargeable depuis le template parent. Pour permettre une surcharge partielle d'un partial, exposer le theme actif sous le namespace stable `@viti_theme`.
- Le namespace `@viti_theme` doit pointer directement vers les templates du theme actif et contourner les templates projet. Cela permet a une surcharge projet d'heriter du template original sans recursion :

```twig
{% extends '@viti_theme/partials/_site_footer.html.twig' %}

{% block footer_navigation %}
    {{ parent() }}
{% endblock %}
```

- Conserver en parallele la resolution Twig non nommee dans l'ordre projet hote, theme actif, puis theme par defaut.
- Exposer aussi le projet hote puis le theme actif dans le namespace `@CpCreationVitiCore` afin que les rares controllers du coeur qui rendent un chemin nomme explicitement conservent la resolution projet, theme, coeur.
- Conserver le namespace `@viti_core_default` comme acces explicite aux vues fonctionnelles non surchargees du coeur, utile pour les fallbacks de wrappers sans recursion.
- Avant de terminer un theme, verifier `@viti_theme` avec `debug:twig`, puis rendre une vraie surcharge projet qui utilise `extends`, redefinit un block et appelle `parent()`.
- Supprimer les copies projet devenues identiques au theme. Une variation locale doit rester une surcharge minimale.
- Toute surcharge partielle doit conserver les hooks fonctionnels, attributs Symfony UX, formulaires, Turbo, Alpine, Stimulus et elements SEO du template d'origine.

## Qualite attendue

- HTML semantique.
- Accessibilite clavier et lecteurs d'ecran.
- SEO propre.
- Mobile first.
- Aucun couplage visuel dans Viti-core.
