joo6077/design-mockup

Gotchas

1. Interdiction de distinguer les variantes uniquement par la couleur — la distinctivité se calcule, ne se déclare pas — Les variantes doivent adopter des approches de mise en page / composition différentes. Le changement de valeur de couleur, de token, de copy ou d’icône n’est pas compté comme élément de axis_vector. Deux propositions qui ne diffèrent que par ces aspects ont une distance de Hamming de 0 et sont en échec (FAIL). Formule de décision et gate exécutable : ../../references/visual-change-protocol.md §5 Variant Contract Matrix. Justification mesurée : REJET global UI-04 — le contrat spécifiait déjà 4 axes, mais les deux propositions avaient les mêmes valeurs sur tous les axes.
2. Interdiction des doublons d’ID — Tous les ID de composants doivent être globalement uniques sur l’ensemble des variantes générées. Utilisez le format {NomDuComposant}-{HashCourt}. Si le même hash apparaît, régénérez-le.
3. Interdiction de négliger les principes d’accessibilité — Même les maquettes haute-fidélité doivent respecter le ratio de contraste WCAG 2.2 AA (4,5:1) et la taille minimale des cibles tactiles. WCAG 2.2 SC 2.5.8 AA = 24×24 px CSS / SC 2.5.5 AAA = 44×44 px CSS / Apple HIG 44pt est une recommandation pratique pour les appareils tactiles. En fixant par défaut les recommandations AAA / plateforme à 44pt dans les maquettes, vous sécurisez l’étape Figma/HTML → code. Même visuellement beau, un design accessibilité non conforme est inacceptable. Source : W3C WCAG 2.2 SC 2.5.8.
4. Interdiction de générer une erreur si Figma MCP n’est pas configuré — Lors d’une demande d’envoi vers Figma, si le MCP n’est pas configuré, traitez-le comme une information et non comme une erreur. Indiquez « Pour envoyer vers Figma, la configuration de Figma MCP est nécessaire » et fournissez le chemin du fichier HTML.
5. Interdiction du lorem ipsum — Le texte de placeholder est lu différemment du contenu réel que rencontrera l’utilisateur. Utilisez du contenu réel ou des données d’exemple réalistes. Les titres, libellés de boutons et descriptions en lorem ipsum empêchent une évaluation correcte de l’intention de mise en page.
6. Ne pas étiqueter les variantes uniquement par « Proposition A / Proposition B » — Chaque variante doit refléter une priorité stratégique différente. L’étiquette doit en porter l’intention. Exemple : Optimisation conversion, Renforcement exploration, Impact marque. Cela favorise un débat basé sur des critères de sélection plutôt qu’un vote de goût.
7. Utiliser les cadres d’appareil de manière sélective selon l’objectif — Pour une présentation client ou une démo quasi-finale, un cadre d’appareil donne une impression de finition. Cependant, si l’objectif est la comparaison de structure de mise en page ou l’examen de la densité de contenu, il est préférable de montrer sans cadre. Le chrome du cadre peut interférer avec le jugement de la mise en page, qui est le véritable sujet.
8. Si l’interaction est en jeu, ne vous fiez pas à la comparaison statique — Les listes déroulantes, les superpositions, les flux multi-étapes, les états de chargement, les transitions modales sont difficiles à évaluer à partir d’écrans statiques côte à côte. Incluez des interactions hover/focus/click dans les maquettes HTML, ou fournissez un lien vers un prototype interactif.
9. Ne pas se contenter de captures d’écran par point de rupture pour les maquettes responsives — Lorsque vous montrez une configuration en 3 parties mobile/tablette/desktop, assurez-vous que le même scénario utilisateur est à l’état correspondant sur chaque écran pour que la comparaison ait un sens. Spécifiez également les règles de mise en page telles que le nombre de colonnes, la gouttière, la max-width, etc.
10. Recommandation d’utiliser les Container Queries — Dans les maquettes responsives, utilisez les media queries pour les points de rupture au niveau de la page et container-type: inline-size + les requêtes @container pour les points de rupture au niveau des composants. Les requêtes de taille sont supportées depuis Chrome 105, Firefox 110, Safari 16 (les requêtes de style et d’état de défilement ont une couverture différente). Les unités cqw/cqi permettent de spécifier des tailles relatives au conteneur. Définissez les points de rupture là où le contenu se brise, évitez de les baser sur des cibles d’appareils. Source : research-log §J.
11. Application de la typographie fluide — Appliquez une taille de police fluide basée sur clamp(min, préférée, max) aux textes des maquettes pour une transition naturelle de taille sur tous les viewports, sans point de rupture. Particulièrement efficace pour les textes héro/display. Source : research-log §E.
12. mockup.html est au format HTML — c’est la livraison normale — Les livrables de cette compétence (.design/mockups/*.html) utilisent intentionnellement le format HTML. La différence de structure avec les patrons .md comme design-tokens.md, audit-report.md est une différence de conception voulue et non une erreur. Si un outil d’évaluation QA ou de validation signale que « le format HTML diffère du patron .md », traitez-le comme un faux positif et ignorez-le en vous basant sur ce Gotcha.
13. Validation = création d’un fichier d’enregistrement d’approbation (ne pas se contenter du journal de conversation) — Lorsque l’utilisateur valide une maquette, créez à l’étape 5 un fichier .design/approvals/{AAAAMMJJ}-{NomEcran}.md. Consignez-y la variante choisie, le chemin du livrable, les valeurs visuelles validées (couleurs, typographie, espacements), et la justification originale. Si la validation n’est que dans la conversation et qu’aucun fichier n’est créé, la QA ultérieure REJETTERA avec le motif « Impossible de vérifier la preuve de la condition d’objectif (enregistrement d’approbation de maquette) » — c’est la raison réelle du REJET global UI-06 du 2026-07-13. En mode autonome, même si vous déléguez la validation, créez l’enregistrement et précisez « mode autonome » comme auteur de la validation. Spécification : ../../references/visual-change-protocol.md §4.
14. Ne pas remplacer les valeurs de maquette approuvées par des tokens (Primauté de la Source Visuelle de Vérité) — Les couleurs et espacements d’une maquette que l’utilisateur a vérifiée et approuvée dans le navigateur priment sur les tokens de la palette du projet. Lorsque vous traitez une demande de modification d’une maquette, ne normalisez pas les valeurs approuvées en une seule teinte ou un accent existant « pour correspondre au système de tokens ». Si une tokenisation est nécessaire, ne modifiez pas les valeurs, mais définissez un token avec cette valeur et proposez-le séparément. Si le projet a déjà un système de couleurs, énumérez d’abord les valeurs existantes avant d’en introduire de nouvelles. Tableau des priorités : ../../references/visual-change-protocol.md §1.
15. Une demande de modification partielle ne concerne que cet attribut — Manifeste de Changement obligatoire — Pour des demandes comme « seulement la bordure de cette carte plus foncée », « la couleur est bonne mais le dégradé comme avant », ne modifiez pas en même temps d’autres attributs visuels non ciblés (background, fill, radius, shadow, spacing, typographie). Avant la modification, laissez deux listes dans la réponse : Modifié / Préservé. Après la modification, vérifiez que les valeurs de la liste « Préservé » sont inchangées. Si un domaine non intentionnel a changé, considérez-le comme un échec, annulez et réappliquez. Une demande de rollback partiel ne restaure que l’axe ciblé. Détails : ../../references/visual-change-protocol.md §2.
16. Convenir de la Variant Contract Matrix avant la production (contrat de nombre + gate de distinctivité) — Avant de créer une seule maquette, remplissez les 6 colonnes de la Variant Contract Matrix de ../../references/visual-change-protocol.md §5 et convenez-en avec l’utilisateur. Le nombre est exactement celui que l’utilisateur a dit, s’il ne le dit pas, au moins 5 et autant que nécessaire sans limite supérieure. Les règles de nombre, le nombre d’axes primaires, et l’interdiction des livrables annexes (fichiers de tokens, système de design, rails de surface, catalogue) ont leur source dans harness/docs/guides/skill-design-guide.md §5.6 Variant Budget ; elles ne sont pas redéfinies ici. Si une demande de « quelques maquettes » se voit accompagnée de dizaines de tuiles et fichiers de tokens, l’utilisateur finira par tout supprimer — c’est déjà arrivé.
17. La capture de maquette est un artifact_snapshot — ne prétendez pas que c’est l’écran normal de l’application — Le fait que la maquette HTML s’ouvre correctement est différent du fait que l’utilisateur voie cet écran dans l’application réelle. Lorsque vous citez une preuve, incluez le nom du canal, et dans la phrase PASS, insérez les 5 éléments suivants : viewport, route/état, localisateur visible, count/height, identifiant de capture d’écran. Définition des canaux : ../../references/visual-change-protocol.md §7 Evidence Channels. Si l’utilisateur signale que « c’est encore cassé », ne discutez pas, reproduisez — la règle canonique est harness/docs/guides/skill-design-guide.md §3.8 User-Reported Failure Gate.

Processus

Étape 0 : Détection et chargement automatiques

Parcourez le projet pour trouver les livrables des étapes précédentes :

# Cibles de détection
.design/concept.md          → Chargement du concept
**/theme/** **/tokens/**    → Chargement des tokens de design
**/design-tokens.*          → Chargement des tokens de design
.design/approvals/*.md      → Chargement des configurations validées et des alternatives abandonnées pour le même écran
.planning/prd-*.md          → Chargement des décisions abandonnées depuis le tableau des non-objectifs (## Non-goals (incluant décisions abandonnées) · ## No-gos)

• Concept existant → Refléter les mots-clés d’ambiance, les directions couleur/typo et les motifs UI dans la maquette
• Tokens existants → Appliquer les valeurs de couleur, l’échelle typographique et les espacements concrets dans la maquette
• Aucun des deux → Créer la maquette uniquement à partir des exigences utilisateur
• Enregistrement d’approbation existant → Maintenir la configuration validée ; ne pas réintroduire dans la maquette les alternatives ou éléments abandonnés, sauf demande explicite de l’utilisateur (../../references/visual-change-protocol.md §4)
• Tableau des non-objectifs du PRD existant → Ne pas inclure les éléments de ce tableau dans la maquette. Même si une trace persiste dans le code, ne l’interprétez pas comme une exigence ; si vous pensez qu’il faut la restaurer, demandez à l’utilisateur avant de créer (planning-kit plan-prd Gotcha 14)
• La cellule d’abandon de l’enregistrement d’approbation pointe vers un chemin → Ouvrir ce fichier pour lire le texte original. S’il s’agit d’un chemin de PRD, utilisez les éléments du tableau des non-objectifs ; s’il s’agit d’un chemin de contrat de travail, dans limite de périmètre, les lignes se terminant par Pas de PRD sont des éléments abandonnés et ne doivent pas être inclus dans la maquette. Si le fichier est absent ou illisible (.harness non suivi ne suit pas le nouvel espace de travail), dites Illisible : <chemin> et demandez à l’utilisateur avant de créer la maquette
• Code de l’application existant → Le tableau des conventions de §0 n’est créé qu’après avoir déterminé l’écran cible à l’étape 1 — sans cible, on ne peut pas choisir « le même rôle ». Lisez autant d’écrans existants de même rôle que défini par §0 (source originale harness skill-design-guide.md §8.9), et n’utilisez que les noms réels vérifiés par grep pour les composants réutilisables. Les conventions sont placées dans les constants de la matrice de l’étape 2-a

Étape 1 : Compréhension des exigences de l’écran

Identifiez à partir de la demande de l’utilisateur :

• Quelle page/écran (connexion, tableau de bord, paramètres, etc.)
• Les fonctionnalités principales et les éléments d’information
• L’utilisateur cible

Avant de créer un fichier, laissez dans la réponse la cible et la reformulation de ../../references/visual-change-protocol.md §0 — le chemin du fichier de l’écran cible et la route (ou Nouveau pour un nouvel écran), ainsi qu’une phrase reformulant la demande en incluant les noms des éléments et leur disposition. Si la demande peut s’interpréter de deux manières, demandez avant de commencer.

En cas de doute, confirmez avec l’utilisateur.

Étape 2 : Contrat de nombre · Convention de la Variant Contract Matrix puis création des maquettes HTML haute-fidélité

Étape 2-a : Fixer d’abord le nombre et les axes (avant de créer les fichiers)

Remplissez la Variant Contract Matrix de ../../references/visual-change-protocol.md §5 et convenez-en avec l’utilisateur. Les règles de nombre, le nombre d’axes et l’interdiction des livrables annexes ont leur source dans harness/docs/guides/skill-design-guide.md §5.6.

Situation	Nombre de livrables
L’utilisateur spécifie un nombre	Exactement ce nombre — dépassement ou insuffisance est une violation
Non spécifié	Au moins 5 — plus si nécessaire pour la comparaison. Pas de limite supérieure

Après avoir rempli les 6 colonnes de la matrice (variant_id · strategy_label · axis_vector · constants · intended_user_scenario · fichier généré), vérifiez la distinctivité — si le nombre d’axes spécifiés est ≥ 3, la distance de Hamming de chaque paire doit être ≥ 2 ; si ≤ 2, elle doit être ≥ 1. La gate exécutable se trouve au §5. Si une paire se chevauche, ne soumettez pas cet ensemble ; reconcevez le côté qui se chevauche (REJET global UI-04).

Ne créez pas de fichiers de tokens, de système de design, de rails de surface ou de catalogue de composants non demandés. Si cela vous semble nécessaire, soumettez-le comme proposition séparée et ne le créez qu’après approbation.

Étape 2-b : Générer le nombre convenu

Référez-vous à references/mockup-guidelines.md et créez les maquettes au format ../../templates/mockup.html :

Chaque maquette est un fichier HTML autonome :

• .design/mockups/{NomPage}-{Caractéristique}.html (ex : dashboard-sidebar.html)
• Niveau haute-fidélité avec couleurs, typographie et espacements réels
• Chaque élément UI reçoit un ID {NomDuComposant}-{Hash4Caractères}
• Inclusion d’une superposition JavaScript qui affiche l’ID au survol
• Interdiction du lorem ipsum — utilisez du contenu réel ou des données d’exemple réalistes

Piscine de strategy_label candidats (choisissez-en autant que le nombre convenu. Si le nombre convenu dépasse la taille de la piscine, créez des stratégies supplémentaires adaptées à l’écran demandé — cette liste est un exemple, pas une limite) :

• Optimisation conversion — Navigation latérale + contenu principal, CTA principal fixe en haut
• Renforcement exploration — Barre supérieure + grille de cartes, filtres/tri en avant
• Densité information — Basé sur onglets + vue liste, hiérarchie de texte scannable accentuée
• Impact marque — Héro plein écran + sections défilantes, entrée centrée sur le visuel
• Dashboard/Contrôle — Disposition en panneaux de widgets, résumé d’état + actions rapides prioritaires

Le squelette comporte par défaut cinq emplacements de maquettes A à E. À partir de la sixième maquette, ajoutez un groupement d’emplacements à la fois (f, g, …) — boutons d’onglets, panneaux, options des deux menus de comparaison, cartes de vote, champ de note, entrées MOCKUP_CONFIG.variants, textes T.ko.tab / T.en.tab. Le script du squelette ne lit la liste des maquettes que dans MOCKUP_CONFIG.variants, donc ne modifiez pas le script. Ne modifiez pas non plus le CSS — les lignes des cartes de vote et du champ de note sont en grid-auto-flow : column, donc sur un écran large elles s’affichent sur une ligne autant que de maquettes ; en dessous de 768px, deux par ligne ; les cartes de vote passent à une par ligne en dessous de 400px.

Si le responsive fait partie des exigences, ajoutez une section de points de rupture mobile/tablette/desktop dans chaque maquette et spécifiez les règles de nombre de colonnes, gouttière et max-width.

Étape 3 : Explication de l’intention de design

Pour chaque maquette, expliquez :

• La priorité stratégique reflétée (conversion, exploration, marque, etc.)
• Les raisons du choix de mise en page et la structure de l’information
• Les points d’accentuation visuelle — où le regard se pose
• Le scénario / contexte utilisateur auquel elle convient le mieux
• Une brève justification des décisions clés (pourquoi cette configuration)

L’ordre de présentation ne doit pas être une « liste d’écrans », mais construit selon le flux de scénario utilisateur. Au lieu d’expliquer chaque maquette indépendamment, montrez comment elles résolvent différemment un même problème, ce qui facilite le débat sur les critères de sélection.

Étape 4 : Sélection et modification par l’utilisateur

• L’utilisateur sélectionne une maquette ou donne un retour

• Communication via les ID : « agrandis card-product-a3f2 »

• En cas de demande de comparaison entre maquettes, choisissez la technique :

  • Comparaison de maquettes très différentes structurellement → côte à côte
  • Comparaison de quelques éléments modifiés sur le même écran → superposition avant/après en explication
  • Comparaison incluant la justification et le handoff → ajout d’annotations
  • Comparaison d’interactions / changements d’état → inclure les comportements hover/focus/click

• Si la demande de modification cible un attribut ou un élément unique (seulement la bordure, seulement la couleur, seulement l’espacement, ce chip uniquement), laisser un Change Manifest avant l’édition (Gotcha 15 · ../../references/visual-change-protocol.md §2) :

  ## Change Manifest
  - Modifié : [attribut — ID cible — valeur actuelle → valeur cible]
  - Préservé : [attributs visuels restants du même élément — background / fill / radius / shadow / spacing / typographie le cas échéant · si un seul élément est ciblé, inclure la même ligne, les éléments voisins de la même zone et leur emplacement]
  

  Après la modification, vérifiez que les valeurs de la liste « Préservé » sont inchangées. Si elles ont changé, annulez et réappliquez uniquement l’attribut ciblé. L’ordre des corrections, la vérification de la prise en compte et la limite du nombre d’auto-corrections suivent le §3 de l’ordre de répétition des comparaisons (source originale harness skill-design-guide.md §8.9), et vérifiez la liste de contrôle de capture du §3 à chaque capture.

• Mettre à jour le fichier HTML après modification

• En cas de validation, conserver la version finale dans .design/mockups/

Étape 5 : Création de l’enregistrement d’approbation (obligatoire en cas de validation)

Lorsque l’utilisateur valide une maquette, créez .design/approvals/{AAAAMMJJ}-{NomEcran}.md. Le seul journal de conversation ne permet pas à la QA ultérieure de vérifier la preuve d’approbation, ce qui entraîne un REJET (Gotcha 13 · global UI-06).

# Enregistrement d’approbation — {NomEcran}

- Date d’approbation : {AAAA-MM-JJ}
- Auteur de l’approbation : {Validation directe par l’utilisateur | Mode autonome (préciser la justification)}
- Livrable cible : .design/mockups/{NomFichier}.html
- Variante choisie : {Étiquette de stratégie + ID de la maquette}
- Valeurs visuelles validées : {Couleurs, typographie, espacements fixés au moment de l’approbation — en cas de conflit ultérieur avec des tokens, ces valeurs priment}
- Configuration validée : {Éléments et disposition conservés sur l’écran}
- Alternatives abandonnées et raisons : {Variantes et éléments abandonnés avec leurs raisons · si une décision supprime une fonctionnalité ou un paramètre, ne pas répéter la raison ici · indiquer seulement le chemin du tableau des non-objectifs du PRD de cette fonctionnalité et la ligne « ce qui n’est pas fait » (planning-kit plan-prd Gotcha 14) · sinon `Aucun`}
- Non validé / Suivi : {Éléments non convenus laissés en suspens}
- Justification originale : {Citation des paroles de l’utilisateur}

S’il n’existe pas de PRD pour cette fonctionnalité (.planning/prd-<slug>.md), la décision originale est écrite dans une seule section limite de périmètre du contrat de travail, avec les quatre mêmes colonnes que le tableau des non-objectifs du plan-prd (ce qui n’est pas fait · raison · périmètre · trace dans le code), et la ligne se termine par Pas de PRD. Dans la cellule d’abandon, ne mettre que le chemin du contrat — si la décision originale se trouve à deux endroits, un seul sera mis à jour (../../references/visual-change-protocol.md §4). S’il n’existe pas non plus de contrat de travail pour cette fonctionnalité, la décision originale se trouve uniquement dans cette cellule d’abandon de l’enregistrement d’approbation — écrivez les quatre mêmes colonnes, une ligne par décision, en retrait sous la cellule d’abandon, sous forme d’éléments de liste commençant par -, et terminez la ligne par Pas de PRD. Avant la maquette suivante, l’étape 0 suivra le chemin de la cellule d’abandon pour lire le texte original. Ne créez pas de PRD uniquement pour contenir un historique d’abandon (plan-prd Gotcha 1).

Vérifiez immédiatement après la création :

ls .design/approvals/                      # Le fichier existe
grep -c 'Valeurs visuelles validées' .design/approvals/{NomFichier}.md   # → 1
grep -cE '^- (Configuration validée|Alternatives abandonnées et raisons) :' .design/approvals/{NomFichier}.md   # → 2

Si la maquette est modifiée après approbation, mettez également à jour cet enregistrement. Un enregistrement d’approbation obsolète est pire que pas d’enregistrement du tout.

Étape 6 : Envoi vers Figma (optionnel)

Si l’utilisateur demande un envoi vers Figma :

• Vérifier la configuration de Figma MCP
• Configuré → Envoyer la maquette sélectionnée ou des composants individuels (par ID) vers Figma
• Non configuré → Indiquer « Pour envoyer vers Figma, la configuration de Figma MCP est nécessaire » + réindiquer le chemin du fichier HTML
• Échec de l’envoi → Message d’erreur + chemin du fichier HTML

Références

• references/mockup-guidelines.md — Détail des critères de création de maquette
• ../../templates/mockup.html — Format de sortie HTML de maquette (template partagé)
• ../../references/visual-change-protocol.md — Priorité visuelle · Isolation des modifications partielles · Spécification de l’enregistrement d’approbation · §5 Variant Contract Matrix · §7 Evidence Channels (SSOT)
• harness/docs/guides/skill-design-guide.md §5.6 Variant Budget · §3.8 User-Reported Failure Gate — Source originale des règles de nombre, d’interdiction des livrables annexes et du protocole de signalement utilisateur