spnngl/agent-skills

Expert UI

Cette compétence détermine ce qu'est l'interface et prouve qu'elle fonctionne pour les utilisateurs. Les idiomes de code (TypeScript, React, Next.js, tests, lint) proviennent de la compétence ts-coding : chargez-la dès que vous touchez à un fichier .ts ou .tsx.

Flux de travail

1. S'orienter. Lisez les sources de vérité de l'UI : package.json (react, next, tailwindcss, la bibliothèque de primitives : react-aria-components, @radix-ui/*, @base-ui-components/react, ou le components.json de shadcn ; le jeu d'icônes ; @playwright/test, @axe-core/playwright), la feuille de style contenant @import "tailwindcss" et @theme, le mécanisme de mode sombre, le répertoire des composants partagés, et deux ou trois écrans existants à côté de celui que vous modifiez. Les choix existants du projet priment sur les valeurs par défaut de cette compétence ; réutilisez ses primitives, ses tokens, son rythme d'espacement et sa terminologie. Fait quand : vous pouvez nommer le système de style, le fichier de tokens, la bibliothèque de primitives, le jeu d'icônes, le commutateur de thème, la commande de développement et l'URL qui affichent le travail, et le lanceur de tests navigateur (ou qu'il n'en existe pas).

2. Cadrer le brief. Avant tout balisage, écrivez ce bloc dans votre réponse et construisez-le :

   Utilisateur et tâche : qui utilise ceci, et la seule tâche qu'il sert
   Point focal : le seul élément sur lequel l'œil se pose en premier
   Action principale : la seule action affirmative ; les actions destructrices nommées séparément
   Densité : sparse | comfortable | dense, adaptée aux écrans voisins
   Humeur : un adjectif que le résultat doit mériter ("précis", "calme", "chaleureux")
   États : vide, chargement, erreur, partiel, débordement, absence d'autorisation : ceux qui s'appliquent
   

   Mise en page, composition et savoir-faire visuel : references/taste.md. Fait quand : chaque champ contient une réponse concrète pour cet écran, suffisamment spécifique pour qu'un relecteur puisse rejeter une construction qui ne la respecte pas.

3. Résoudre les tokens. Associez chaque couleur, taille, espace, rayon, ombre et durée à un token sémantique de l'étape 1. Ajoutez un token manquant à la source avec des valeurs clair et sombre, en suivant references/tokens.md. Fait quand : le diff ne contient aucune couleur brute, valeur arbitraire (p-[13px], bg-[#1a1a1a]) ou style en ligne pour une propriété thématisable, chaque nouveau token a une valeur claire et une valeur sombre, et node scripts/contrast.ts <theme.css> (chemin relatif au répertoire de cette compétence) passe.

4. Construire. Composez à partir des primitives du projet (React Aria Components s'il n'en a pas), mobile-first, en suivant les Règles et references/components.md. Détails sur la sémantique, le clavier et WCAG : references/accessibility.md. Texte de l'interface : references/copy.md. Fait quand : chaque élément interactif couvre chaque état qui s'applique, chaque vue de données affiche chaque état nommé dans le brief, et les styles sans préfixe sont la mise en page à 320px.

5. Vérifier. Exécutez les vérifications de ts-coding, puis les portes statiques et navigateur dans references/verification.md : dérive des tokens, emoji, contraste des tokens, axe en clair et sombre, clavier, reflow à 320px, taille des cibles, mouvement réduit. Fait quand : chaque porte se termine avec un code 0 et vous rapportez ce qu'elle a affiché ; une porte que vous n'avez pas pu exécuter est signalée comme "non vérifiée" avec la raison.

6. Regarder. Capturez d'écran le travail en 1280 et 390 de large, en clair et sombre, plus chaque état du brief ; ouvrez chaque image avec l'outil de lecture et cliquez sur chaque contrôle. Ensuite, plaidez pour le rejet avec references/review.md. Lorsqu'un outil de sous-agent est disponible, transmettez les captures d'écran et ce fichier à un nouvel agent : un critique qui n'a pas construit l'écran voit plus clairement. Fait quand : vous avez visionné chaque capture d'écran, chaque contrôle a produit un changement visible, et chaque constat Critique ou Majeur est corrigé ou signalé à l'utilisateur.

Modifications mineures (un ajustement d'espacement, de couleur ou de texte dans un composant existant) : exécutez les étapes 1, 3 et les portes statiques de l'étape 5, puis capturez d'écran l'élément modifié en clair et sombre et visualisez les deux.

Révision d'une UI existante : exécutez l'étape 1, rédigez le brief de l'étape 2 tel que vous l'inférez, exécutez les étapes 5 et 6 dessus, et rapportez dans le format de references/review.md. Sans rendu, dites-le et limitez les constats à ce que la source prouve.

Règles

Preuve

• Énoncez un rapport de contraste, une réussite ou un score uniquement lorsqu'une commande vient de l'afficher ; sinon dites "non vérifié". Une porte qui a sauté (pas de navigateur, pas de serveur) n'a rien mesuré.
• Les portes prouvent l'exactitude, jamais la qualité : jugez la hiérarchie et le savoir-faire à partir des captures d'écran.

Hiérarchie

• Un seul élément mène : le point focal du brief est l'élément le plus grand, le plus lourd ou le plus contrasté, et ses pairs deviennent plus discrets. Sur les pages marketing et d'atterrissage, la police d'affichage fait au moins 2,5 fois la taille du corps ; les écrans de produit maintiennent le titre de page à un ou deux niveaux au-dessus du corps, le poids et la position faisant le reste.
• L'espacement croît vers l'extérieur : les espaces à l'intérieur d'un groupe < le rembourrage de son conteneur < l'espace entre les sections.
• Un état vide remplit sa région et nomme la première action. Une page se termine intentionnellement : un résumé, un pied de page, une prochaine étape.

Tokens et couleur

• Token par intention : choisissez le token dont la signification correspond à l'action. Une action destructive porte le token destructif à la fois sur son déclencheur et dans sa confirmation ; le primaire marque la seule action affirmative principale par vue.
• Chaque statut associe une couleur à une icône ou un texte. Un seul accent ; les neutres portent le reste.
• Le thème est une seule modification à la source du token : chaque écran lit les mêmes tokens sémantiques.
• Le clair et le sombre suivent la préférence système ; un paramètre Système / Clair / Sombre le remplace et persiste (references/tokens.md).

États

• Éléments interactifs : défaut, survol, focus-visible, enfoncé, désactivé, en attente, invalide, sélectionné. Chacun qui s'applique est visuellement distinct, en clair et sombre ; sélecteurs dans references/components.md.
• En attente maintient le contrôle à pleine puissance avec un indicateur de progression ou une étiquette de chargement (isPending, aria-busy). Désactivé marque une action que l'utilisateur ne peut pas entreprendre maintenant, avec la raison visible à proximité.
• Le feedback rapporte ce qui s'est passé : un toast de succès apparaît après la modification des données, et la vue affiche déjà le changement.

Mise en page

• Le mobile est la base : les utilitaires sans préfixe sont la mise en page téléphone ; sm:, md:, lg: s'ajoutent sur les écrans plus larges. Les composants réutilisés à différentes largeurs répondent à leur conteneur (@container, @md:).
• Une région qui défile horizontalement montre un indice visible : un dégradé de bord, une barre de défilement.

Garde-fous

• Les icônes proviennent de lucide-react (ou du jeu du projet) en SVG avec currentColor. Zéro emoji dans l'UI, le texte, le code et les commits.
• Les surfaces se séparent avec une bordure complète de 1px, un palier de surface ou un espacement. Une bordure colorée sur un seul côté d'une carte, alerte, toast ou appel est interdite.
• Le contenu est réaliste : noms plausibles, chaînes longues, grands nombres, zéro et un éléments. Le texte de substitution et les contrôles de débogage ne sont jamais rendus dans le produit.

Références

Chargez celle qui correspond à la branche sur laquelle vous travaillez :

• references/taste.md: indicateurs de médiocrité, composition, typographie, couleur, profondeur ; tout nouvel écran ou restylage.
• references/tokens.md: @theme Tailwind v4, tokens sémantiques, thème système et son paramètre de remplacement, ajout ou audit de tokens.
• references/components.md: React Aria Components, attributs d'état, formulaires, superpositions, vues de données, icônes, animation.
• references/accessibility.md: sémantique, clavier et focus, contraste, critères WCAG 2.2, couleurs forcées, RTL.
• references/copy.md: étiquettes, erreurs, états vides, confirmations, toasts, indicateurs de texte généré.
• references/verification.md: analyses de dérive, d'emoji et de contraste, rendu des états de composants, portes Playwright et axe, matrice de captures d'écran.
• references/review.md: lentilles de critique, heuristiques, gravité, format des constats.