pgr/docs/skeletons/003-WEB_FRONTEND.md

Skeleton — Web frontend

Objectif

Cette specification décrit une specialization composable pour créer une baseline frontend Web contrôlée sans confondre langage, package ecosystem, build tool, styles et host.

Elle se compose avec 001-PROJECT_GOVERNANCE_FOUNDATION.md, sélectionne les owners Web réellement applicables de la famille 500 et utilise les templates/guides 008, 009 et 010 lorsqu'ils correspondent aux choix du projet.

Le contrat transversal des skeletons reste possédé par ../rules/220-SKELETONS.md.

Applicabilité

Appliquer cette specialization lorsqu'un projet ou sous-projet possède un frontend Web autonome ou embarqué dont la baseline frontend est contrôlée par le projet.

Elle peut servir de fondation frontend à un host plus spécifique, par exemple Tauri, sans rendre ce host applicable par elle-même.

Pour un projet existant, cette specification sert de référence de comparaison : l'adoption suit ../rules/230-ADOPTION.md et classe les choix existants ADOPT / KEEP-LOCAL / OVERRIDE / DEFER plutôt que de réécrire son layout.

Ne pas appliquer ce skeleton à un backend sans frontend, à une page statique qui n'a besoin d'aucune de ces responsabilités, ni uniquement parce que Vite/TypeScript sont recommandés ailleurs.

Owners sélectionnables

La composition de référence d'un frontend moderne contrôlé est :

GENERAL
+ 500  language / ecosystem family
+ 530  TypeScript
+ 540  JavaScript package ecosystem
+ 550  Vite
+ 560  CSS / Sass

La sélection reste factuelle :

• 530 est sélectionné lorsque TypeScript est utilisé ; TypeScript SHOULD être préféré pour une baseline durable lorsqu'il est compatible avec le besoin ;
• 540 est sélectionné lorsqu'un package.json, un package manager ou des dépendances JavaScript sont réellement utilisés ;
• 550 est sélectionné uniquement si Vite est choisi ; Vite SHOULD être préféré pour les frontends compatibles, sans être obligatoire ;
• 560 est sélectionné si le frontend possède une chaîne CSS/Sass ; CSS seul reste valide et Sass reste optionnel, bien que recommandé pour une chaîne non triviale ou un package exposant une API Sass utile.

Le skeleton ne transforme pas une recommandation SHOULD en MUST.

Fondation et fichiers de départ

Lorsque TypeScript + package ecosystem sont sélectionnés, le projet MAY partir des templates :

templates/web-typescript/package.json
templates/web-typescript/tsconfig.json

Le guide ../templates/008-WEB_TYPESCRIPT_PACKAGE.md possède leur adaptation.

PGR ne fournit pas de vite.config.ts universel. Si Vite est sélectionné, créer ou adapter la configuration réelle à partir des décisions décrites dans ../templates/009-WEB_VITE.md.

PGR ne fournit pas non plus de main.scss ou de thème universel. Si CSS/Sass est sélectionné, organiser les sources selon les besoins réels et suivre ../templates/010-WEB_CSS_SASS.md.

Le nom frontend/ est une convention possible, pas un chemin imposé par ce skeleton.

Décisions destinataire avant matérialisation

Résoudre explicitement au minimum :

1. la racine et le scope exacts du frontend ;
2. TypeScript ou JavaScript ; pour une nouvelle baseline durable, considérer explicitement la recommandation TypeScript sans transformer un choix JavaScript en obligation de justification ou en OVERRIDE ;
3. le package manager réel et la politique de lockfile adaptée au rôle du package ;
4. les versions réelles de TypeScript et des dépendances, ainsi que les déclarations @types/* réellement nécessaires ;
5. Vite ou un build tool alternatif, avec ses chemins root, cache, outputs, base, ports, plugins et assets lorsqu'ils s'appliquent ;
6. CSS seul ou Sass, puis l'implémentation Sass réelle si sélectionnée ;
7. le framework CSS éventuel : aucun, Bootstrap, Tailwind CSS ou autre ; ce choix reste local au projet ;
8. les entrypoints de styles publics des dépendances et les overrides réellement nécessaires ;
9. les scripts de package réellement utiles (typecheck, dev, build, preview ou équivalents) ;
10. la gate frontend indépendante du host et les éventuels smokes navigateur utiles ;
11. les prérequis produits par d'autres owners, s'il en existe, sans les faire absorber par le frontend.

Aucune décision ouverte ne doit être remplacée silencieusement par une valeur observée dans Games ou KSP.

Dépendances et manifest

Le package réel SHOULD rester privé lorsqu'il représente une application non publiée, conformément à 540.

Les dépendances de développement telles que TypeScript, Vite, Sass ou packages de déclarations sont ajoutées uniquement si les choix du projet les rendent nécessaires. Le skeleton MUST NOT préremplir @types/node, @types/bootstrap, sass-embedded, Vite ou Bootstrap sans besoin réel ni version décidée.

Lorsqu'une dépendance fournit déjà ses propres types, ne pas ajouter un package @types/* redondant.

Styles

CSS source et Sass source sont des entrées versionnées. Les CSS compilées/minifiées, sourcemaps et copies dans l'output sont générées sauf contrat de distribution explicite.

Pour du nouveau Sass contrôlé, @use / @forward sont préférés lorsque les dépendances le permettent. Une compatibilité @import peut être conservée pour un package existant qui l'exige encore.

Le choix d'un framework CSS ne rend ni Bootstrap, ni Tailwind CSS, ni un thème spécifique normatif pour les autres projets.

Build et outputs

Lorsque Vite est sélectionné, le cache et build.outDir restent générés et hors Git. Les chemins exacts restent locaux.

build.emptyOutDir = true n'est utilisé que sur un output dédié. vite preview reste un smoke/prévisualisation locale et ne devient pas un serveur de production.

Un autre build tool possède ses propres décisions project-specific tant qu'aucun owner PGR dédié n'existe.

Validation initiale

La validation suit ../validation/005-WEB_FRONTEND_VALIDATION.md.

Selon les profils sélectionnés, elle doit pouvoir prouver indépendamment du host, autant que possible :

restore reproductible
TypeScript typecheck
compilation/transformation des styles
build frontend de production
smoke navigateur seulement si nécessaire

La commande concrète appartient au package manager et aux outils réellement sélectionnés.

Le host reçoit ensuite sa propre gate d'intégration. Un PASS frontend ne constitue pas un PASS Tauri ou plateforme.

Une instanciation temporaire MAY être utilisée pour un dry-run de cette specialization. Elle doit employer les toolchains officielles réelles plutôt qu'un audit Python simulant TypeScript/Vite/Sass.

Composition avec un host

Un host peut composer ce skeleton comme fondation frontend, puis ajouter son propre profil/skeleton.

Cette composition ne transfère jamais au host l'ownership de TypeScript, du package manager, de Vite ou de Sass/CSS.

Le skeleton Tauri reste DEFER pendant 0.1.1. La présence du présent skeleton Web satisfait une pièce de préparation mais ne décide pas à elle seule la promotion du candidat Tauri.

Hors scope

Cette specification ne possède pas :

• Tauri ou un autre host natif ;
• WASM ou ses bindings/générations ;
• backend/serveur Web ;
• deployment/operations ;
• choix de framework UI/CSS universel ;
• configuration de sécurité propre à un host ;
• service worker/PWA tant qu'un owner distinct n'est pas justifié.