Moddingflow/better-design

Better Design - Meilleure Conception

Rendez la tâche demandée claire et actionnable : l'utilisateur peut voir où il se trouve, comprend une action avant de l'activer, reçoit un résultat et peut se remettre d'une erreur. Évaluez la cohérence, l'expressivité et l'accessibilité séparément. Ne promettez pas une UX parfaite.

1. Établir la portée et l'ancrage visuel

• Choisissez un mode : création, amélioration ciblée, audit ou plan. Les audits restent en lecture seule ; n'implémentez pas de modifications dans un plan. N'ajoutez pas de fonctionnalités que l'utilisateur n'a pas demandées.
• Établissez la plateforme à partir de la demande et du projet. En l'absence de contexte, utilisez le web réactif, le HTML sémantique et les WCAG 2.2 AA comme cible initiale.
• Définissez la matrice des appareils et des zones d'affichage réels avant de composer ou de modifier une surface réactive. Pour un site web, incluez les mises en page mobile, tablette, desktop et ultra-large que le produit prend en charge ; pour un jeu mobile, incluez les téléphones petits et typiques ainsi que les tablettes. Les contraintes de conception et le comportement de la mise en page doivent s'adapter à ces surfaces plutôt que de simplement réduire une composition de bureau. Pour le travail sur navigateur, incluez le zoom du navigateur dans la matrice car 75 %, 100 % et 150 % peuvent exposer différents problèmes de rognage, de densité, de reflow et d'interaction.
• Avant tout travail d'interface, recherchez le DESIGN.md du projet (racine, docs/, design/, ou le chemin nommé dans les instructions de l'agent) et lisez-le complètement. C'est la source unique des valeurs d'interface : polices, échelle typographique, rôles de couleur, espacement, rayons, tailles de composants, icônes et mouvement. Prenez chaque valeur dans le code nouveau ou modifié à partir de celui-ci par rôle ou nom de jeton ; ne faites jamais au jugé, n'arrondissez pas et n'introduisez pas de quasi-doublon. Les règles sont dans design-md.md.
• Inspectez l'écran existant dans l'environnement d'exécution actuel ou via des captures actuelles confirmées, puis inspectez les composants, jetons, styles et règles de projet à proximité. L'absence de DESIGN.md ne signifie pas qu'il n'y a pas de système de conception : les jetons de code sont alors le système. Préservez le travail en cours non lié.
• Distinguez un défaut d'implémentation d'une demande de refonte. Traitez d'abord la cause : ordre peu clair, action imprévisible, mauvais retour, perte de données ou contenu perdu.
• Prenez les décisions dans cet ordre : tâche explicite et contraintes → DESIGN.md et le système existant → conventions de la plateforme → tâches du domaine → la ligne de base configurable de cette compétence. La fonctionnalité et les exigences d'accessibilité applicables s'appliquent à chaque niveau.
• Direction visuelle par défaut. Lorsque l'utilisateur ne nomme aucun style visuel et que le projet n'a pas de DESIGN.md, de marque, de jetons de code ou d'interface utilisateur en direct à hériter, construisez dans le style maison : ultra-minimal haut de gamme dans l'esprit d'Apple (toile noire, Geologica presque blanc aux graisses 500 et 340, deux gris, un bleu pour les liens et le focus, actions en pilule, surfaces séparées par le ton, le contenu réel comme seule couleur). Les règles et le préréglage DESIGN.md prêt sont dans house-style.md ; lisez-le en entier avant d'écrire un style. Deux erreurs de lecture envoient les agents ailleurs, alors vérifiez-les explicitement (house-style.md section 1) : le domaine, l'industrie, le public ou le nom du produit n'est pas un indice visuel ("une torréfaction", "pour les développeurs"), et les valeurs par défaut du scaffold non touché ne sont pas un système à hériter (le thème par défaut de shadcn/ui, la palette par défaut de Tailwind, create-next-app, les starters Vite ou Expo, les valeurs par défaut de Bootstrap, MUI ou Chakra) ; mappez plutôt le style maison sur eux. Lorsqu'il s'applique, commencez à partir du fichier de référence house-style.html, pas d'une page vierge : prenez ses jetons, classes de type, navigation, boutons, tuiles et rythme de section (ou portez-les dans les composants de la pile), puis remplacez son contenu (house-style.md section 1). Tout indice visuel de l'utilisateur (couleurs, ambiance, thème, référence, marque, style d'audience) le remplace : suivez la demande et n'appliquez que les parties du style maison que la demande laisse ouvertes et ne contredit pas. Ne restylisez jamais un produit existant dans ce style sauf si cela est demandé. Les jeux conservent leur propre direction artistique.
• Préservez la marque, la densité, la composition de type jeu, éditoriale ou expressive établie. Ne les remplacez pas par un CRM gris générique. En cas de conflit réel, choisissez le plus petit ajustement accessible et expliquez la déviation spécifique.
• Clarifiez uniquement les inconnues qui changent matériellement la décision ; énoncez brièvement les hypothèses raisonnables. Cette compétence n'introduit pas une nouvelle approbation ou passerelle HTML. Les exigences de projet existantes pour les prototypes, l'approbation et les builds restent applicables.

2. Définir la tâche et un contrat proportionné

• Décrivez le scénario principal en langage clair et son résultat observable. Parcourez : entrée → action → résultat → erreur/réessayer → retour/annuler.
• Séparez la tâche principale, les actions secondaires et l'aide. Choisissez des noms et des schémas familiers à l'utilisateur ; maintenez la cohérence de l'emplacement de la navigation et des actions sur tous les écrans.
• Une simple correction n'a besoin que d'un court enregistrement de la décision modifiée et des vérifications. Pour un nouveau flux, rédigez un contrat compact avant la mise en œuvre ; c'est un outil de travail, pas un document obligatoire pour l'utilisateur.
• Utilisez design-contract.md pour la structure, les valeurs numériques par défaut et les exceptions. L'exemple JSON illustre le format ; ne l'ajoutez pas en bloc au projet pour un petit changement.
• Limitez le contrat à la plateforme, aux objectifs, au système existant, à la direction, aux composants affectés, à leurs actions/états, au comportement réactif et aux preuves d'acceptation. Une vérification planifiée n'est pas une vérification terminée.

3. Définir une direction artistique avant le style

Les règles négatives ne font que déplacer la sortie vers le modèle le plus courant suivant ; le caractère vient d'un processus. Lors de la création ou de la refonte d'une surface dont l'identité fait partie de la tâche (marque, page d'accueil, portfolio, application grand public, jeu, éditorial, lanceur), suivez art-direction.md avant de choisir les jetons. Lorsque le style maison s'applique (section 1), la palette, le type, la forme et les jetons de mouvement proviennent de son préréglage ; écrivez toujours le concept et laissez-le choisir l'imagerie, l'élément principal de chaque section et un détail de signature (house-style.md section 10). Sinon :

• Dérivez un concept en une phrase du domaine, du public et du contenu du produit — un objet, un lieu ou un artisanat de ce monde — pas d'adjectifs tels que "moderne, propre, minimal". Ajoutez trois qualités cibles et trois contre-qualités concrètes.
• Rassemblez 3 à 5 références réelles (d'abord celles fournies par l'utilisateur ; jamais d'images générées par l'IA) et notez pour chacune exactement ce qui est pris : rythme, densité, présentation des nombres, matériau, lumière.
• Esquissez 2 à 3 directions qui diffèrent par leur dispositif principal (typographique, axé sur l'image, structurel), puis choisissez-en une avec une raison liée à la tâche et au public.
• Dérivez la palette et le type du concept : une palette avec une origine déclarée et des neutres teintés ; trois candidats de type et un choix raisonné. Planifiez un ou deux détails de signature ; le pool optionnel dans effects-library.md contient ceux qui sont testés.
• Dérivez le caractère de mouvement du même concept : comment les choses de ce monde bougent (tempo, poids, physique, si quelque chose rebondit) plus un détail de mouvement de signature. La palette, le type et le mouvement doivent se lire comme une seule voix ; voir motion.md.
• Dans DESIGN.md, une marque existante ou un système de conception dont la direction est héritée : prenez-la de DESIGN.md ou énoncez-la en une phrase à partir de la surface en direct, et travaillez à l'intérieur. Les outils de travail denses expriment leur caractère par la précision et la typographie des données ; sans système et sans indication de l'utilisateur, ils prennent l'échelle d'application et la palette du style maison avec la densité de la solution de repli neutre.
• Enregistrez la direction dans le contrat (direction, y compris direction.motion) et planifiez les vérifications distinctiveness et motion. Écrivez la direction choisie et ses jetons dans DESIGN.md afin que les écrans et sessions ultérieurs soient construits à partir des mêmes valeurs.

4. Construire un système cohérent de décisions

• Réutilisez les jetons et composants de DESIGN.md et des jetons de code. Pour un nouveau système, définissez des rôles sémantiques pour la couleur, la typographie, l'espacement, le rayon, les couches et le mouvement ; puis sélectionnez les variantes de composants.
• Gardez les ensembles fermés afin que chaque écran soit construit à partir des mêmes parties : une ou deux familles de polices, une échelle typographique par paliers de quelques rôles, une échelle d'espacement fixe, quelques rayons, et des tailles de composants fixes (par exemple bouton sm/md/lg). Même rôle, même valeur sur chaque écran. Une valeur manquante est une décision système : ajoutez le rôle à DESIGN.md et aux jetons de code dans le même changement.
• Créez DESIGN.md à partir du modèle lors de la création d'une interface à partir de zéro (à partir du préréglage house-style lorsque le style maison s'applique), ou lorsqu'une refonte ou un changement multi-composants n'en trouve aucun ; dérivez-le des jetons de code en direct plutôt que d'inventer des valeurs, et enregistrez les contradictions au lieu de les corriger silencieusement. Ne le créez pas pour une correction d'un seul élément sauf si on vous le demande ; proposez-le en une ligne. Maintenez DESIGN.md et les jetons de code synchronisés dans chaque changement qui touche à l'un ou l'autre.
• L'API exprime l'intention, la taille, la densité et l'état. Préservez les props natives, la participation aux formulaires, les liens et les noms accessibles ; n'exigez pas de onClick sur un bouton de soumission ou un lien avec href.
• Ne réglez pas chaque élément avec son propre hexadécimal, espace, ombre et rayon. Modifiez un jeton ou une variante partagé lorsque la cause est partagée. Les maths de mise en page, une bordure de 1 px, 0, fr, %, calc, aspect-ratio et les valeurs de projet autorisées ne sont pas des violations en soi.
• Choisissez la taille du texte par rôle et conteneur.
• Construisez la géométrie ; ne la placez jamais à l'œil. Suivez layout-geometry.md pour chaque écran, panneau et menu de jeu, et mesurez le résultat (section 8). Corrigez un désalignement à sa cause (pivots, ancres, un groupe de mise en page manquant, le rembourrage des sprites, les métriques de police), jamais en décalant un seul élément :
  • Intervalles égaux. Les frères d'un même type se trouvent dans un conteneur de mise en page (flex/grid gap, groupes de mise en page Unity, conteneurs de boîtes Godot, boîtes UMG) avec un seul jeton d'espacement, de sorte que chaque espace entre eux est identique. Un espace différent doit signifier un nouveau groupe et un pas clair vers le haut de l'échelle. Échelle de proximité : à l'intérieur d'un contrôle < entre les éléments < entre les groupes ≤ remplissage.
  • Lignes partagées. Les éléments d'une ligne partagent leur haut/centre/bas (les hauteurs mélangées partagent les centres) ; les éléments d'une colonne et chaque étiquette d'une liste de paramètres commencent sur une seule ligne de repère verticale, avec les contrôles sur une deuxième ligne de repère. Utilisez une grille ou une colonne d'étiquettes fixe, jamais de décalages par ligne. Les ensembles de boutons partagent une seule taille.
  • Contenu dans les petits contrôles est centré par son encre visible (hauteur de capitale, pixels d'icône rognés), pas par la boîte de ligne de police ou un rectangle de sprite rembourré ; les icônes asymétriques obtiennent un décalage optique déclaré cuit dans le composant. Les paires icône + étiquette utilisent un seul jeton d'espace.
  • Espace de respiration. Rien ne dépasse ou ne repose sur le bord de son conteneur : le remplissage est au moins les espaces qu'il contient, avec une réserve pour la localisation la plus longue, l'échelle au survol et les anneaux de focus ; l'interface interactive reste dans la zone de sécurité à chaque rapport hauteur/largeur pris en charge. Lorsque le contenu ne tient pas, modifiez la mise en page, pas les marges.
• Sélectionnez la typographie par un processus, pas une liste noire : présélectionnez trois familles dérivées du concept (époque, matériau, voix, densité des données), puis choisissez avec une raison énoncée. La famille doit être lisible à ses tailles et langues réelles et fournir les graisses, styles, chiffres, couverture des glyphes (y compris le cyrillique lorsqu'il est pris en charge) et le comportement de repli requis. Aucune famille n'est interdite, mais une famille choisie par habitude est un défaut : échanger un défaut de tendance (Inter, Uni Sans) pour le suivant (Space Grotesk, DM Sans, Instrument Serif) sans raison est le même modèle. Un type élégant ne doit jamais rendre l'interface plus difficile à lire.
• Construisez la hiérarchie par dominance et contraste : un élément principal par écran ou section, une échelle typographique clairement par paliers (affichage 3-5× le corps sur les surfaces expressives, pas plus petits dans les outils denses), une asymétrie intentionnelle là où elle sert le concept, et des sections adjacentes qui diffèrent dans leur structure plutôt que de répéter un modèle de bloc.
• Le nombre d'or peut informer les proportions, la hiérarchie, le recadrage ou les espaces blancs lorsqu'il améliore la composition, mais c'est un outil visuel plutôt qu'une formule obligatoire. Préférez la tâche réelle, le contenu, les contraintes réactives, la lisibilité et le système existant chaque fois qu'ils entrent en conflit.
• Ne faites pas d'un écran principal un mur de prose ininterrompue lorsque son contenu peut être compris par des actions, des regroupements ou des ancres visuelles. Divisez les explications denses en sections scannables et associez-les, lorsque cela est utile, à des contrôles, icônes, illustrations, aperçus, diagrammes ou autres images pertinentes à la tâche. Un tableau de bord ou une zone de compte, par exemple, doit exposer ses sections principales et ses prochaines actions plutôt que de seulement décrire ce qu'un utilisateur pourrait configurer. N'ajoutez pas d'éléments visuels décoratifs qui nuisent à la compréhension ou créent de fausses affordances.
• Utilisez la couleur pour le sens et l'emphase ; ne transmettez pas l'état uniquement par la couleur. Associez les informations d'erreur/succès/requis/sélectionné à du texte, une icône, une forme, un motif ou un autre indice non chromatique qui reste visible en niveaux de gris et pour les déficiences de la vision des couleurs.
• Vérifiez le contraste sur la paire premier plan/arrière-plan réelle adjacente après l'application de l'opacité, des superpositions, des dégradés, des images et de chaque thème requis ; n'arrondissez pas un résultat proche du seuil. Atteignez au moins 4,5:1 pour le texte normal et les images significatives de texte, et 3:1 uniquement pour le texte grand (au moins 24 px CSS réguliers ou 18,5 px CSS gras). Visez plus haut pour les polices fines, petites ou inhabituelles.
• Assurez un rapport de contraste minimum de 3:1 pour les informations visuelles nécessaires pour identifier un contrôle actif, son focus ou son état, et les objets graphiques significatifs par rapport à leur couleur adjacente. Une bordure est requise uniquement lorsqu'elle est ce qui rend le contrôle identifiable ; lorsqu'elle est utilisée à cette fin, elle doit répondre au même seuil de 3:1 que les objets graphiques significatifs.
• Interactions : les transitions ont une durée (100-300 ms pour les retours immédiats, 200-500 ms pour les changements de vue, 15-30 ms d'avance sur une attente pour laisser les gens se sentir plus rapides) et une courbe d'assouplissement (ease-out pour les entrées des personnes, ease-in-out pour les transitions de l'interface, un ressort de 25-35 % de rebond pour les micro-interactions). Un mouvement non intentionnel est arrêté au bord. Utilisez motion.md pour les détails.
• Écrivez des étiquettes d'action qui décrivent ce qui se passe, pas seulement où vous allez. Utilisez des verbes : "Enregistrer", "Annuler le compte", "Ajouter au panier", pas "Soumettre" sur un bouton de suppression ni des noms de page. L'interface ne fait pas la conversation avec l'utilisateur ("Vous avez supprimé le fichier !", "Êtes-vous sûr de vouloir...")).
• Ne concevez pas avec des bordures de débogage de type "surligné" (cadres roses, bleus ou verts en production).

5. Valider la qualité et corriger les défauts

• Corrigez directement tout ce qui enfreint cette compétence dans les changements que vous effectuez, ainsi que les problèmes évidents que vous trouvez (chevauchés, texte non lisible, actions inaccessibles au clavier, gestion d'état manquante, écran vide).
• Finalisez le produit du travail sans artefacts de l'agent : pas de texte d'espace réservé comme "Acme Corp", pas de texte d'aide comme "L'interface utilisateur dispose désormais de...", pas de débogueur console.log, console.warn, pas de commentaires comme // TODO : implémenter.

Cinq vérifications avant de déclarer un travail terminé

Pour chaque implémentation (pas pour un contrat ou un plan), passez en revue ces vérifications avec le code ou le contenu réel. Ne marquez pas une vérification comme réussie parce qu'elle a été planifiée ; exécutez-la :

1. Le composant : chaque composant nouveau ou modifié est-il nécessaire ? A-t-il un nom accessible en plus de son visuel, un rôle correct, un ordre de tabulation valide, un état désactivé visible, un comportement de focus documenté ? Est-ce que <button>, <a> ou <input> est utilisé là où c'est sémantiquement correct ? Les composants personnalisés (sélect déguisé, glissière, accordéon) implémentent-ils l'interaction clavier complète pour le pattern ARIA correspondant ?
2. Les données : l'interface peut-elle afficher un contenu dynamique dans chaque situation : liste vide, un élément, plusieurs, une chaîne longue, des nombres formatés ? Les formats (dates, devises, pourcentages, numéros de téléphone avec indicatif) sont-ils paramétrés par région ?
3. Le thème : chaque modification survit-elle au changement de thème (clair/sombre, contraste élevé, orientation) sur les surfaces cibles ? Les couleurs sémantiques sont-elles appliquées par rôle, pas par valeur de couleur codée en dur ?
4. Le mouvement : est-ce que tout mouvement, fondu, glissement, retour de pression et animation se produit à une cadence stable, a une courbe d'assouplissement, respecte le prefers-reduced-motion et a été vérifié sur un navigateur avec le paramètre de mouvement réduit ? Les transitions d'entrée retardées pour les éléments défilants sont-elles absentes (les mettre en œuvre correctement nécessite une bibliothèque de défilement, une logique de point d'ancrage, un désabonnement et une vérification de mouvement réduit qui dépasse une correction ponctuelle) ?
5. L'absence de défauts : y a-t-il des chevauchements ? La fenêtre ou la taille de police la plus large a-t-elle été testée avec le plus grand facteur de zoom ? La cible tactile la plus petite fait-elle au moins 44×44 px CSS ou son équivalent natif sur mobile, et chaque cible est-elle entourée d'au moins 8 px d'espace jusqu'à la cible suivante ? Les éléments masqués sont-ils retirés de l'ordre de tabulation (hidden, inert, aria-disabled, display: none, pas seulement opacity: 0 ou visibility: hidden) ? Toute croix de fermeture ou fonction annuler supprime-t-elle ses frais de gestion d'état lors du démontage ? Les sélecteurs ont-ils une option "aucune sélection" ? Les contrôles de carte de crédit acceptent-ils les espaces après chaque groupe de 4 chiffres, et les entrées OTP les acceptent-elles également ?

L'absence d'une vérification de mouvement réduit et de toute entrée retardée est un défaut. Si la demande ne fournit pas de maquettes ou de spécifications de mouvement, utilisez la direction de mouvement du concept, et s'il n'y en a pas non plus, le comportement par défaut de la plateforme. Ne créez pas d'animation quand il n'y a pas d'interaction ni de changement d'état. L'animation intentionnelle est une amélioration ; le mouvement non intentionnel pour attirer l'attention ou par défaut est une distraction.

6. Finaliser DESIGN.md

• Mettez à jour le DESIGN.md du projet avec toutes les nouvelles valeurs, rôles, composants ou décisions de conception introduits dans cette tâche.
• En prime, incluez un enregistrement de l'audit si le mode était un audit ; incluez les constats, leur sévérité et leurs corrections.
• Assurez-vous que les jetons de code sont en miroir de DESIGN.md, et vice versa.

Règles de fin de compétence

• Les actifs privés ne sont pas générés : l'agent ne produit pas d'images, SVGs ou icônes qui n'existent pas déjà dans le projet (ou qu'il n'est pas invité à choisir dans une bibliothèque existante). Utilisez des emojis standard, des SVGs inline de base (qui ne dépassent pas 10 lignes) ou des icônes d'icônes de marque uniquement pour les preuves de concept, les tests ou les maquettes, et seulement lorsqu'un jeu d'icônes n'est pas installé. Remplacez-les par des icônes de la bibliothèque de composants. Ne générez pas d'images à moins que la tâche ne soit explicitement la conception d'une illustration ou d'un actif de jeu.
• Ne produisez pas d'URL vers des sites externes dans le DESIGN.md que vous créez ; faites référence aux pages de manière descriptive.
• Lorsque le DESIGN.md est créé à partir du modèle, laissez la section ## 8. To decide avec la liste de contrôle vide ; ne la remplissez pas avec des hypothèses. Laissez le concepteur humain décider.
• Suivez les fichiers d'instructions de l'agent (tels que CLAUDE.md, CONTEXT.md, CURSOR_RULES.md, memory.md) chaque fois qu'ils sont présents. Lorsque les instructions de l'agent entrent en conflit avec cette compétence, suivez les instructions de l'agent et expliquez explicitement le conflit à l'utilisateur. Si le conflit est une règle de haut niveau indiquant que les fichiers ne doivent pas être créés, suivez l'utilisateur.
• Lorsque la demande de l'utilisateur ne porte pas sur la conception (backend, script, requête API, document, tests de code qui ne modifient pas la surface), n'appliquez pas cette compétence.

Références (ne pas traduire les voies)

• art-direction.md
• design-contract.md
• design-md.md
• effects-library.md
• house-style.md
• layout-geometry.md
• motion.md
• assets/DESIGN.template.md
• assets/DESIGN.house-style.md
• assets/house-style.html
• assets/design-contract.example.json