Générateur et Auditeur Structurel UX.md (v1)
Aperçu
Alors que DESIGN.md spécifie les tokens visuels (couleurs, typographie, coins arrondis, ombres, échelle d'espacement), UX.md spécifie le squelette structurel et les règles d'interaction d'une application.
Sans UX.md, les agents de codage IA dérivent entre les sessions : mélange de largeurs de conteneurs, déplacement des appels à l'action principaux, alternance arbitraire entre modales et tiroirs, omission des états vides ou d'erreur, perte de l'état du filtre lors du rechargement F5, et introduction de routes sans issue.
Ce skill fonctionne selon quatre modes en utilisant un pipeline en trois phases soutenu par six scripts Node.js sans dépendance dans scripts/.
Scripts CLI fournis
| Script | Objectif | Exemple d'utilisation |
|---|---|---|
scripts/extract-ux.mjs | Analyse package.json, AGENTS.md, DESIGN.md et les routes source (src/app, src/pages) en JSON structuré | node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json |
scripts/generate-ux.mjs | Génère un UX.md en 12 sections à partir d'un archétype, d'un préréglage produit (--preset linear) ou de ux-scan.json | node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md |
scripts/validate-ux.mjs | Exécute 16 règles structurelles déterministes et de lint --check-code (parité des routes, primitives, gestionnaires morts, z-index aberrants) | node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code |
scripts/scaffold-ux.mjs | Génère des propriétés personnalisées CSS ux-contract.css et des primitives de mise en page React/TypeScript (AppShell.tsx, PageHeader.tsx, PageSection.tsx, DataStateBoundary.tsx) à partir de UX.md | node .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux |
scripts/preview-ux.mjs | Génère un simulateur de maquette interactive autonome et responsive ux-preview.html | node .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html |
scripts/diff-ux.mjs | Compare deux fichiers UX.md pour détecter les régressions de routes, d'archétypes, de budget ou de seuils | node .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json |
Modes de fonctionnement
- Synthèse (greenfield /
init): Exécuteextract-ux.mjs+generate-ux.mjspour générer leUX.mdinitial à partir du contexte du projet et deDESIGN.md, puis personnalise les routes, les archétypes et les règles métier. - Extraction à partir d'une référence (produit de référence ou URL): Extrait l'enveloppe spatiale, les règles d'interaction, les raccourcis clavier et les archétypes de pages d'un produit de référence nommé (par exemple Linear, ChatGPT Canvas, Stripe Dashboard, Shopify ou Supabase).
- Audit et rétro-ingénierie (codebase existante):
Exécute
extract-ux.mjspour découvrir les routes existantes (src/app/**,src/pages/**,src/routes/**), détecte les dérives structurelles et génère unUX.mdunifié. - Évolution (ajout de fonctionnalité / synchronisation de routes):
Met à jour la Section 3 (Archétypes de pages) et la Section 4 (Navigation, Graphe de routes et Persistance URL) lors de l'ajout de nouvelles pages ou workflows, en vérifiant la parité avec
validate-ux.mjs UX.md --check-code.
Pipeline de génération en trois phases
Phase 1 : Extraction déterministe et classification des archétypes
- Exécutez
node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .(ou inspectez directementpackage.json,AGENTS.mdetDESIGN.md) pour détecter l'environnement cible, la limite d'authentification, les routes existantes et les points de rupture deDESIGN.md. - Chargez resources/archetype-taxonomy.md et confirmez :
platform_profile:web-app|mobile-native|desktop-app|terminal-tuiarchetype:b2b-saas-workspace|ai-chat-canvas|analytics-dashboard|ecommerce-storefront|developer-tool
- Optionnellement, initialisez
UX.mdvia :node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --archetype <archetype> --project "<Nom du Projet>" --output UX.md
Phase 2 : Synthèse en 12 sections spécifique au domaine
Chargez resources/ux-md-format.md, resources/layout-primitives.md et resources/writing-style-guide.md. Adaptez UX.md à la racine du dépôt avec :
- En-tête YAML : Configuration complète (
spec_version: "1.0",shell_budget,z_index_scale,thresholds,layout_primitives). - Sections
0à11dans l'ordre séquentiel :## 0. Topologie Produit & Domaine## 1. Architecture Spatiale & Enveloppe Applicative(maquette ASCII et tableau de budget de fenêtre d'affichage)## 2. Contrat de Défilement, Fenêtre d'Affichage et Z-Index## 3. Archétypes de Pages Principaux (Plans)(en utilisant les en-têtes### Archetype: <ArchetypeID>)## 4. Navigation, Graphe de Routes et Persistance URL(Mermaidflowchart LR, tableau d'accessibilité des routes et matrice de persistance d'état)## 5. Matrice de Décision des Superpositions et des Retours(nombre de champs et seuils enpx)## 6. États de Vue Obligatoires (Matrice 4 États)(Chargement,Vide,Erreur,Rempli)## 7. Mutation, Formulaire et Ergonomie des Permissions(gardeisDirty, règles de destruction à 2 niveaux, portes de permissions à 3 voies)## 8. Contrainte en Conditions Réelles, Densité et Troncature(mode de mise à l'échelle de liste unique,min-w-0 truncate, jeton de cellule vide-,tabular-nums)## 9. Réorganisation Réactive et Chorégraphie des Entrées(ordre de repliement, cibles tactiles>= 44x44pxavec espacement>= 8px, équivalents tap pour les interactions au survol, padding de défilement safe-area)## 10. Primitives de Mise en Page Obligatoires (Contrat de Code)(<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>)## 11. À Faire, À Ne Pas Faire et Guide de Prompt pour l'Agent
Contraintes de rédaction :
- Zéro adjectifs vagues : N'écrivez pas "petit formulaire", "mise en page propre", "requête lente" ou "navigation intuitive" sans nombres explicites (
<= 4 champs,1280px,>= 150ms). Voir resources/anti-patterns.md. - Zéro impasses : Chaque route de la Section 4 fait référence à un
<ArchetypeID>valide de la Section 3 et définit à la fois unDéclencheur d'entréeet uneSolution de repli en cas de sortie/annulation. - Appliquer les primitives de mise en page : Assurez-vous que toutes les routes composent les 4 primitives de mise en page obligatoires (
<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>) définies à la Section 10.
Phase 3 : Contre-audit et validation automatisée
- Auditez le
UX.mdgénéré par rapport à resources/quality-checklist.md ([UX-01]à[UX-16]). - Exécutez le script linter automatisé :
node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code - Résolvez tout résultat
errorouwarningsignalé et réexécutez jusqu'à ce que le validateur se termine avec0 erreurs.