Communitygithub.com

Générateur et Auditeur Structurel UX.md

Générer, extraire, auditer, prévisualiser, différencier et valider des spécifications UX/UI structurelles UX.md v1. Définit le squelette de l'application (enveloppe applicative, calcul du budget spatial, propriété du défilement et des z-index, archétypes de pages, graphe d'accessibilité des routes, persistance d'état par URL, matrice de décision des superpositions, contrat de vue à 4 états, ergonomie des formulaires et mutations, et primitives de mise en page obligatoires) en tant que compagnon structurel de DESIGN.md et AGENTS.md. À utiliser lors de l'initialisation d'un projet frontend/UI, de l'extraction de schémas UX d'un produit de référence, de l'audit d'une base de code existante pour détecter les dérives de mise en page, ou de l'ajout de nouvelles routes et vues.

Qu'est-ce que Générateur et Auditeur Structurel UX.md ?

Ce skill consiste en un générateur et auditeur structurel pour le format UX.md v1. Il fournit une approche systématique pour capturer et faire respecter le squelette structurel et les règles d'interaction d'une application, en complément du DESIGN.md (qui spécifie les tokens visuels) et du AGENTS.md (qui spécifie les conventions d'agent). Sans UX.md, les agents IA dérivent entre les sessions en introduisant des incohérences de mise en page, des états manquants ou des règles de mutation contradictoires. Le skill fonctionne selon quatre modes (synthèse, extraction à partir d'une référence, audit d'une base de code existante, évolution) et repose sur six scripts Node.js sans dépendance. Il génère douze sections obligatoires couvrant l'architecture spatiale, le défilement et les z-index, les archétypes de pages, le graphe de navigation, les matrices de décision, les états de vue, l'ergonomie des formulaires, et les primitives de mise en page. Le pipeline de génération en trois phases comprend une extraction et classification déterministes, une synthèse en douze sections avec des règles d'écriture strictes (zéro adjectifs vagues, zéro impasses), et une validation automatisée avec 16 règles lint. Le skill est conçu pour être utilisé avec des agents de codage IA comme Claude Code, Cursor ou Codex, et produit des artefacts qui guident un développement cohérent entre les sessions. Il est idéal lors de l'initialisation d'un projet, de l'ajout de nouvelles pages, de l'audit de dérives de mise en page, ou de l'extraction de schémas UX d'applications de référence.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SolidStateNetwork/ux.md/tree/main/skills/ux-md-generator

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

ScriptObjectifExemple d'utilisation
scripts/extract-ux.mjsAnalyse 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.mjsGé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.jsonnode .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md
scripts/validate-ux.mjsExé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.mjsGé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.mdnode .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux
scripts/preview-ux.mjsGénère un simulateur de maquette interactive autonome et responsive ux-preview.htmlnode .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html
scripts/diff-ux.mjsCompare deux fichiers UX.md pour détecter les régressions de routes, d'archétypes, de budget ou de seuilsnode .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json

Modes de fonctionnement

  1. Synthèse (greenfield / init): Exécute extract-ux.mjs + generate-ux.mjs pour générer le UX.md initial à partir du contexte du projet et de DESIGN.md, puis personnalise les routes, les archétypes et les règles métier.
  2. 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).
  3. Audit et rétro-ingénierie (codebase existante): Exécute extract-ux.mjs pour découvrir les routes existantes (src/app/**, src/pages/**, src/routes/**), détecte les dérives structurelles et génère un UX.md unifié.
  4. É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

  1. Exécutez node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . (ou inspectez directement package.json, AGENTS.md et DESIGN.md) pour détecter l'environnement cible, la limite d'authentification, les routes existantes et les points de rupture de DESIGN.md.
  2. Chargez resources/archetype-taxonomy.md et confirmez :
    • platform_profile : web-app | mobile-native | desktop-app | terminal-tui
    • archetype : b2b-saas-workspace | ai-chat-canvas | analytics-dashboard | ecommerce-storefront | developer-tool
  3. Optionnellement, initialisez UX.md via :
    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 à 11 dans 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 (Mermaid flowchart 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 en px)
    • ## 6. États de Vue Obligatoires (Matrice 4 États) (Chargement, Vide, Erreur, Rempli)
    • ## 7. Mutation, Formulaire et Ergonomie des Permissions (garde isDirty, 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 >= 44x44px avec 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 un Déclencheur d'entrée et une Solution 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

  1. Auditez le UX.md généré par rapport à resources/quality-checklist.md ([UX-01] à [UX-16]).
  2. Exécutez le script linter automatisé :
    node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
    
  3. Résolvez tout résultat error ou warning signalé et réexécutez jusqu'à ce que le validateur se termine avec 0 erreurs.

Skills associés