Ahmed8881/ahmed-ui-craft

Ahmed UI Craft

Les modèles de langage dérivent vers la moyenne statistique du web : Inter, un dégradé violet, trois cartes rondes identiques, un emoji par fonctionnalité. Ce résultat est reconnaissable au premier coup d'œil et indique à l'utilisateur que personne n'a pris de décision. Cette compétence force les décisions à être prises, écrites sous forme de tokens, et vérifiées avant de remettre quoi que ce soit.

Suivez le workflow dans l'ordre. Chaque étape existe parce que sauter est la raison pour laquelle une UI générique apparaît.

Étape 0 – Lire le projet avant de concevoir

Regardez avant d'inventer. Vérifiez, dans cet ordre :

1. Framework : package.json (next, react, vue, svelte, astro), ou du .html simple.
2. Styling : tailwind.config.* ou @import "tailwindcss" / @theme (Tailwind v4), *.module.css, styled-components, ou CSS simple.
3. Tokens existants : cherchez --color-, --space-, @theme, theme.extend.
4. Bibliothèque de composants : components/ui/ + components.json (shadcn/ui), @mui/material, Radix, Headless UI, Vuetify.

Pourquoi : un beau composant qui ignore les tokens et la bibliothèque existants du projet est une régression, pas une amélioration. Si le projet a déjà un système de design, travaillez à l'intérieur : étendez ses tokens, restylez ses primitives (pour shadcn/ui, modifiez les variables CSS dans globals.css et les fichiers de composants, ne les enveloppez pas). N'importez assets/tokens.css que lorsqu'il n'y a pas de système à étendre.

Si rien n'existe, par défaut : HTML sémantique + propriétés personnalisées CSS depuis assets/tokens.css, mappées dans Tailwind si Tailwind est présent.

Étape 1 – Réflexion design (avant tout code)

Écrivez quatre courtes lignes, dans votre tête ou dans la réponse :

• Objectif : quel travail fait cet écran ? (ex. "convaincre un responsable d'équipe de démarrer un essai")
• Public : qui regarde, sur quel appareil, dans quelle humeur ? (ex. "ingénieurs ops, ordinateur de bureau, scannant rapidement")
• Ton : trois adjectifs. (ex. "précis, calme, dense")
• Différenciateur : une chose dont quelqu'un se souviendrait après avoir fermé l'onglet.

Le différenciateur doit être concret et visible, pas "propre et moderne". Bons exemples : "les prix sont affichés dans un grand chiffre condensé qui va d'un bord à l'autre" ; "chaque carte a une règle fine et un numéro d'index mono comme une fiche technique" ; "le titre principal est en italique serif sur un fond de papier blanc cassé".

Pourquoi : si vous ne pouvez pas nommer le différenciateur, le résultat sera la moyenne, car la moyenne est ce que le modèle produit quand rien ne le tire ailleurs.

Si l'utilisateur a fourni une marque, une capture d'écran ou un site existant, le ton vient de là. N'imposez pas une nouvelle direction à une marque établie.

Étape 2 – S'engager dans une direction esthétique

Choisissez une direction et appliquez-la partout : type, couleur, rayon, ombre, mouvement, imagerie et rythme de copie. Des directions mélangées se lisent comme de l'indécision.

Direction	Type	Couleur	Forme et profondeur	Mouvement
Éditorial	Serif d'affichage, corps humaniste	Blanc cassé papier, encre, un accent fort	Règles fines, rayon quasi nul, pas d'ombres	Fondu lent, rien au défilement
Brutaliste	Grotesk lourd ou mono, grandes tailles	Noir/blanc brut + une couleur vive	Rayon 0, bordures épaisses, ombres dures décalées	Instantané, vif
Doux / organique	Serif d'affichage arrondi ou doux	Neutres chauds teintés, accent terreux mat	Grand rayon sur les conteneurs uniquement, ombres diffuses	Élastique, doux
Industriel / technique	Condensé ou grotesk + mono	Neutre sombre, accent de signal (ambre, citron, cyan)	Petit rayon, bordures 1px, lignes de grille visibles	Rapide, plutôt linéaire
Luxe	Serif à fort contraste, grandes lettres espacées	Presque noir, crème, accent métallique ou bijou profond	Espace blanc généreux, bordures fines	Lent, longues transitions
Ludique	Police d'affichage épaisse, sans empattement amicale	Deux couleurs saturées qui détonnent volontairement	Formes d'autocollant, ombres décalées	Rebond avec dépassement

Chaque ligne a un préréglage prêt dans assets/directions/ (polices, palette claire et sombre vérifiée pour le contraste, rayon, ombre, mouvement) et une liste de mouvements signature dans references/directions.md. Chargez le préréglage après tokens.css, utilisez au moins deux de ses mouvements signature, et décaler es teintes vers la marque. Le minimalisme suisse est le septième préréglage.

Règles pour le choix :

• Dérivez-le de l'Étape 1, pas d'une habitude. Un tableau de bord pour des SRE n'est pas "luxe".
• Nommez-le dans votre réponse ("Direction : industriel / technique") afin que l'utilisateur puisse rediriger tôt.
• Si l'utilisateur demande quelque chose de fade ("simple, propre"), choisissez quand même : "minimalisme suisse" est une direction (grille stricte, un grotesk, noir + une couleur, zéro décoration).

Étape 3 – Définir les tokens en premier

Avant d'écrire un seul composant, définissez les tokens pour : couleur, type, espacement, rayon, ombre, mouvement, z-index. Commencez par assets/tokens.css : gardez les noms, remplacez les valeurs.

Les valeurs de départ (Fraunces + Instrument Sans, neutres papier, accent vermillon) sont un espace réservé, pas un style. Avant d'écrire les composants, modifiez au moins l'association de polices (depuis references/typography.md, adaptée à votre direction), la teinte d'accent, et la teinte vers laquelle les neutres sont teintés. Pourquoi : dans les tests, les tokens de départ inchangés ont rendu un formulaire de connexion et une page de tarification pour des produits sans rapport identiques. C'est une nouvelle valeur par défaut, ce qui est le problème que cette compétence vise à résoudre. Gardez-les uniquement si la direction est vraiment éditoriale chaleureuse avec un accent rouge-orange.

Le moyen le plus rapide d'obtenir une nouvelle palette accessible : générez-la, puis collez-la sur les tokens de couleur dans le bloc 2.

node scripts/palette.mjs --hue 250 --accent 130 --dark-first   # neutres ardoise, accent citron

--hue teinte les neutres (utilisez la teinte de la marque), --accent est la teinte d'accent. Chaque paire texte/fond est résolue pour passer WCAG AA en clair et en sombre avant d'être imprimée.

Pour les directions sombre en premier (tableaux de bord de surveillance, outils de développement, thèmes nocturnes de luxe), définissez :root { color-scheme: dark; } de sorte que le sombre soit le défaut et le clair soit opt-in.

Pourquoi : les tokens rendent la direction applicable. Un #6366f1 ou 13px codé en dur dans un composant est une décision prise isolément, et vingt de celles-ci font dériver l'UI. Avec les tokens, le mode sombre, le thème et les restyles ultérieurs sont des modifications d'un seul fichier.

Règles :

• Deux couches : palette brute (--ink-900, --clay-500) et tokens sémantiques (--color-text, --color-accent, --color-surface). Les composants utilisent uniquement les tokens sémantiques.
• Pas de nombres magiques dans les composants. Chaque couleur, taille, espacement, rayon, ombre, durée et z-index vient d'un token. Exceptions : 0, 1px pour les règles fines, 100% et 1fr.
• Mode sombre : chaque couleur sémantique est light-dark(CLAIR, SOMBRE), de sorte que les deux thèmes vivent dans une seule déclaration et les composants ne changent jamais. Voir references/color-and-theming.md.

Tailwind : faites des tokens le thème, de sorte que bg-surface, text-text-muted, font-display et rounded-md existent et bg-indigo-500 n'existe pas.

• v4 : le deuxième bloc dans assets/tokens.css utilise déjà les espaces de noms de Tailwind (--color-*, --font-*, --text-*, --radius-*, --shadow-*, --ease-*). Remplacez le :root de ce bloc par @theme et ajoutez --color-*: initial; comme première ligne pour supprimer la palette par défaut. Conservez le bloc 3 (color-scheme) en CSS simple. Les utilitaires résolvent light-dark() par thème, car ils référencent var(--color-*). N'écrivez pas @theme inline { --color-x: var(--color-x) } ; une variable qui référence son propre nom est un cycle et se résout en rien.
• v3 : dans tailwind.config, définissez theme.colors (pas extend) sur { surface: "var(--color-surface)", ... } et étendez fontFamily, borderRadius, boxShadow de la même manière.

Étape 4 – Construire mobile-first, avec chaque état

Écrivez les styles de base pour une fenêtre de 360px, puis ajoutez des media min-width ou des requêtes de conteneur. Pourquoi : il est plus facile d'ajouter de l'espace que d'en enlever, et la plupart des bugs de mise en page (défilement horizontal, tableaux écrasés) n'apparaissent qu'aux petites largeurs.

Chaque élément interactif est livré avec tous ses états. Les états manquants sont la raison la plus courante pour laquelle une UI semble inachevée.

État	Ce qu'il doit montrer
défaut	le design au repos
survol	changement subtil (couleur ou ombre), uniquement sous @media (hover: hover)
focus-visible	un anneau clairement visible, jamais supprimé
actif	retour d'enfoncement (plus foncé, ou translateY(1px))
désactivé	contraste plus faible + cursor: not-allowed, et le vrai attribut disabled
chargement	spinner ou squelette, aria-busy="true", la largeur ne saute pas
erreur	message texte près du champ, pas seulement une bordure rouge
vide	un vrai message et une action suivante, jamais une boîte vide

Utilisez d'abord le HTML sémantique : <button> pour les actions, <a href> pour la navigation, <label for> pour chaque entrée, <dialog> pour les modales, <table> pour les données tabulaires, les repères (<header> <nav> <main> <footer>). Ajoutez ARIA uniquement lorsque HTML n'a pas d'équivalent natif. Pourquoi : les éléments natifs viennent avec le comportement clavier et la sémantique du lecteur d'écran gratuitement ; ARIA est une promesse que vous devez ensuite implémenter.

Écrivez du contenu réel. Le texte de remplacement ("Lorem ipsum", "Fonctionnalité 1", "Jean Dupont") masque les problèmes de mise en page et fait ressembler le résultat à un modèle. Utilisez un contenu spécifique et plausible qui correspond à l'objectif de l'Étape 1.

Étape 5 – Auditer avant de livrer

Exécutez scripts/audit.md : bash scripts/audit.sh <fichiers modifiés> (vérifications de motif plus contraste des tokens), puis, si Playwright est disponible ou si l'utilisateur accepte de l'installer, node scripts/browser-check.mjs <page> et regardez les captures d'écran qu'il enregistre. Corrigez ce qui échoue. Les ratios écrits dans les commentaires sont des affirmations, pas des mesures ; calculez-les. Ne signalez pas le travail comme terminé avec des échecs connus ; si quelque chose ne peut pas être corrigé (par exemple, une couleur de marque qui échoue au contraste), dites-le explicitement.

Mode multi-agent (lorsqu'un outil de sous-agent est disponible)

L'agent principal effectue toujours les Étapes 0 à 4 lui-même : la réflexion et la construction ont besoin du même contexte, et les séparer perd ce que l'Étape 0 a trouvé. Utilisez les sous-agents à deux moments uniquement :

1. Propositions de direction (Étape 2, briefs ouverts uniquement). S'il n'y a pas de marque, de capture d'écran ou de système de design existant, lancez 2 à 3 sous-agents en parallèle. Donnez à chacun les lignes de l'Étape 1 et attribuez à chacun une direction différente du tableau. Dites à chacun de lire d'abord sa section de references/directions.md et references/typography.md, et donnez à chacun les directions des autres agents pour qu'ils les évitent. Chacun ne renvoie que : direction, paire de polices, teinte d'accent + neutre, différenciateur, deux mouvements signature. Rejetez une proposition qui réutilise la paire de polices, la teinte d'accent ou le différenciateur d'un autre, ou qui conserve les valeurs de départ de tokens.css. Choisissez-en une (ou montrez les options à l'utilisateur), puis continuez seul. Pourquoi : un agent converge vers la moyenne ; des points de départ différents forcés ne le font pas. Ignorez cette étape lorsque la marque définit déjà la direction.

2. Révision indépendante (Étape 5, toujours pour les nouvelles pages ou écrans). Après la réussite de votre propre audit, lancez un nouveau sous-agent qui n'a pas écrit le code. Donnez-lui les fichiers modifiés, les lignes de l'Étape 1 et la direction choisie, et demandez-lui de : lire references/anti-patterns.md, exécuter scripts/audit.sh, et lister chaque endroit où l'UI semble générique, manque un état, ou enfreint la direction. Il classe chaque constatation comme bloquante / majeure / mineure et ne modifie pas. Corrigez chaque constatation bloquante et majeure, réexécutez scripts/audit.sh, et listez les mineures non corrigées dans la réponse. Un passage de révision, pas de boucle. Pourquoi : le constructeur juge le résultat par ce qu'il avait l'intention de faire, pas par ce qui est à l'écran.

Pas d'outil de sous-agent : faites les deux passages vous-même, dans l'ordre. Pour la révision, relisez les fichiers comme si quelqu'un d'autre les avait écrits.

Règles de qualité (et pourquoi)

Typographie

• Ne prenez pas par défaut Inter, Roboto, Arial, Helvetica ou system-ui pour le texte d'affichage. Évitez également les nouveaux défauts de l'IA : Poppins, Montserrat, Space Grotesk, DM Sans. Pourquoi : ce sont ceux que chaque page générée utilise, donc ils signalent "généré".
• Associez une police d'affichage à une police de corps qui contraste dans la structure (serif + sans, condensé + large, grotesk + mono). Deux familles maximum, plus un mono optionnel.
• Utilisez une échelle modulaire avec des tailles fluides (clamp()), et rendez le plus grand titre considérablement plus grand que le texte du corps. Une hiérarchie timide (32px sur 16px) semble inachevée.
• Texte du corps : 16px minimum, hauteur de ligne 1,5-1,7, mesure 60-75ch. Les tableaux de bord denses peuvent utiliser 12-14px pour les métadonnées et les cellules de tableau, jamais pour les paragraphes ou les entrées.

Couleur

• Une couleur dominante porte la marque ; un accent vif est réservé à l'action principale et aux données clés. Les neutres font la plupart du travail. Environ 60/30/10. Pourquoi : une palette de cinq couleurs uniformément répartie n'a pas de point focal, donc rien n'est lu comme important.
• Teintez vos neutres vers la teinte de la marque au lieu d'utiliser du gris pur.
• Pas de dégradés violet-bleu ou violet-sur-blanc, sauf si la marque est vraiment violette.
• Contraste du texte d'au moins 4,5:1 (3:1 pour le texte de 24px+ ou 18,66px+ en gras, et pour les limites des composants d'interface et les anneaux de focus).

Mise en page et forme

• Évitez la grille identique de trois ou quatre cartes. Variez la taille et l'emphase : un élément en vedette couvrant deux colonnes, une liste à côté d'un grand visuel, une répartition asymétrique.
• Le rayon suit la direction et est cohérent par niveau. Ne mettez pas rounded-2xl partout ; les petits contrôles ont un petit rayon, ou pas de rayon.
• Pas de défilement horizontal à 320px. Utilisez min-width: 0 sur les enfants flex/grid, overflow-wrap: anywhere pour les longues chaînes, et des conteneurs à défilement pour les tableaux larges.
• Cibles tactiles d'au moins 44x44 px (le rembourrage compte).

Icônes et imagerie

• Pas d'emoji comme icônes. Utilisez un ensemble d'icônes (Lucide, Phosphor, Heroicons, Tabler) avec une épaisseur de trait, ou SVG en ligne. Pourquoi : les emoji s'affichent différemment selon les OS, ne peuvent pas être colorés avec des tokens, et sont annoncés par les lecteurs d'écran ("fusée").
• Les icônes décoratives obtiennent aria-hidden="true" ; les boutons à icône uniquement obtiennent une aria-label.

Mouvement

• Animez uniquement transform et opacity (plus filter avec parcimonie). Pourquoi : les autres propriétés déclenchent une mise en page ou un affichage à chaque image et bégayent sur les téléphones bas de gamme.
• Durées issues des tokens : 120-200ms pour le retour d'interface, 250-400ms pour l'entrée des éléments.
• Respectez prefers-reduced-motion : supprimez le mouvement, gardez les fondus courts ou instantanés.

Accessibilité ...