design-brief

Design brief

Livré à lui-même, un agent de codage conçoit de mémoire, et la mémoire donne la moyenne de tout : le héros centré, le dégradé violet, trois cartes avec une icône chacune. Les produits réels ont déjà résolu chaque écran que vous allez construire, et des composants finis existent déjà, bien meilleurs que tout ce qui est improvisé en une seule séance. Traitez donc vos propres instincts de design comme une moyenne et arrêtez d'inventer. Le travail consiste à trouver, comparer, choisir et adapter.

Deux sources font le travail, et elles font des tâches différentes :

Source	Ce qu'elle vous donne	À utiliser pour
Refero	Écrans, flux et styles de produits réels expédiés	Décider ce qu'un écran doit faire et à quoi il doit ressembler
21st.dev	Composants finis créés par des personnes et notés par la communauté	Le composant réel qui va dans le code

Refero vous dit quoi construire ; 21st.dev vous donne la pièce. Utilisez les deux. Un composant choisi sans référence est souvent joli mais inadapté à l'écran, et une référence sans composant est reconstruite à la main, et mal.

Configuration

# Refero (un serveur MCP). Exécutez ensuite /mcp et connectez-vous.
claude mcp add --transport http refero https://api.refero.design/mcp

# CLI 21st.dev
npx @21st-dev/cli login     # ouvre le navigateur ; ensuite la commande est `21st`
21st whoami                 # vérifiez que vous êtes connecté

Les recherches et les aperçus sont gratuits sur 21st.dev. Le téléchargement du code d'un composant utilise un quota quotidien (21st usage indique ce qu'il reste) : comparez d'abord et ne téléchargez que ce que vous avez choisi.

Si un outil est manquant ou déconnecté, prévenez l'utilisateur une fois, avec la commande qui résout le problème, et continuez avec celui qui fonctionne. Ne passez pas silencieusement à une UI construite à la main.

Ordre de travail

1. Fixez la direction : couleurs et typographie.
2. Trouvez le motif pour chaque écran et flux dans Refero.
3. Choisissez le composant pour chaque section sur 21st.dev.
4. Adaptez le tout à un seul ensemble de tokens.
5. Vérifiez le résultat par rapport au niveau de qualité, dans l'application en cours d'exécution.

Pour tout ce qui est plus grand qu'un composant, écrivez le plan UI avant de coder (modèle à la fin). C'est un petit tableau, et c'est ce qui empêche un écran d'être improvisé en cours de construction.

1. Direction

• Les couleurs et la typographie viennent de ce que l'utilisateur a déjà : son fichier DESIGN.md, son système de design existant, ou une référence qu'il nomme. Ne le remplacez pas.
• S'il n'a rien donné, ancrez la direction dans les styles Refero des produits les meilleurs : refero_search_styles, puis refero_get_style sur les deux ou trois plus forts. Ne faites pas par défaut du thème standard du framework ou de la palette de marque de la plateforme sur laquelle vous construisez. C'est ainsi que tous les projets sur cette plateforme finissent par se ressembler.
• Choisissez un style dominant et conservez ses traits marquants. Empruntez un ou deux détails aux autres. Faire la moyenne de plusieurs références donne le juste milieu sûr que vous cherchiez à éviter.
• Supportez le mode clair et le mode sombre.
• Fournissez un seul design. Ne donnez pas à l'utilisateur trois options à choisir, sauf s'il les demande ; choisir est le travail qu'il vous a confié.
• Écrivez le résultat sous forme de tokens (rôles de couleur, échelle typographique, espacement, rayon, ombres) avant d'installer un composant, afin que chaque choix ultérieur se résolve en un token.

2. Motifs depuis Refero

Outil	Répond à	Exemple de requête
refero_search_styles, puis refero_get_style	À quoi doit-il ressembler et donner l'impression ?	site fintech premium avec typographie retenue
refero_search_screens, puis refero_get_screen	Que contient cet écran, et dans quels états ?	état vide tableau de bord, filtres tableau de données
refero_search_flows, puis refero_get_flow	Quelles sont les étapes de ce parcours ?	onboarding inscription, annulation abonnement

Les recherches d'écrans et de flux nécessitent une platform : web ou ios.

• Cherchez ce qui est littéralement à l'écran (« page tarifs bascule annuel mensuel »), pas des adjectifs. Les adjectifs appartiennent à une recherche de styles.
• Essayez trois à cinq angles par écran, y compris un produit connu qui le fait bien. Le premier résultat est rarement le meilleur.
• Regardez aussi les états, pas seulement l'écran heureux : vide, chargement, erreur, succès.
• Quand un écran est proche, refero_get_similar_screens trouve rapidement ses proches.
• Gardez deux ou trois références par écran et notez ce que vous prenez de chacune : structure, hiérarchie, états, formulation. Les références informent l'écran. Ce ne sont pas un modèle à copier.

3. Composants depuis 21st.dev

21st.dev est un catalogue organisé de composants finis, pas de génération IA. Pour chaque élément d'UI (en-têtes, champs de saisie, cartes, listes déroulantes, chat, états de chargement, animations), recherchez, comparez et utilisez le meilleur.

21st search "<composant>" --type c --limit 10     # composants uniquement
21st get <id>                                     # affiche le code et la démo de celui choisi
21st add <auteur>/<slug>                          # l'installe (shadcn en coulisse)
npx shadcn@latest add "https://21st.dev/r/<auteur>/<slug>"   # même installation avec shadcn standard
21st logo <marque>                                # logos de marques réelles en SVG, gratuit

Comment choisir :

1. Cherchez par l'emplacement, pas par l'ambiance. « Tableau de tarifs », « menu de commande », « téléchargement de fichier », pas « section moderne et propre ». Essayez deux ou trois formulations.
2. Comparez plusieurs, et ne prenez jamais le premier résultat. Ouvrez les aperçus. Un nom et une description ne vous disent pas à quoi ressemble ou bouge un composant.
3. Préférez le plus téléchargé ou ajouté aux favoris. Les compteurs sont sur la page de chaque composant sur 21st.dev. La popularité est une preuve qu'un composant fonctionne dans des projets réels. Elle ne prouve pas l'adéquation, qui est la vérification suivante.
4. Vérifiez la correspondance avec la référence Refero pour cet écran. Il doit faire le même travail à la bonne densité, et avoir les états dont vous avez besoin (survol, focus, désactivé, chargement, vide). Vérifiez qu'il tient sur la largeur d'un téléphone et au clavier, et regardez les dépendances qu'il apporte.
5. Adaptez une ou deux choses à vos tokens : couleur, rayon, police. Si vous vous retrouvez à réécrire le composant, vous avez choisi le mauvais. Revenez en arrière et choisissez à nouveau.
6. Gardez les frères cohérents. Les composants de différents auteurs doivent se lire comme un seul produit une fois relookés.
7. Construisez à la main uniquement la colle qui n'a pas de candidat, et dites-le.

Signalez chaque choix pour que l'utilisateur puisse le remplacer : section · composant · auteur · raison en une ligne.

4. Barre de qualité

• Vrais logos, pas d'icônes génériques et de points colorés.
• Peu de texte. Pas de murs de copie ; laissez l'interface porter le message.
• Vrais motifs d'UI : onglets, listes déroulantes, fenêtres modales, boutons à bascule, graphiques. Tout n'est pas une pile de cartes.
• Bons états de chargement, vides et d'erreur, avec une progression pour les actions lentes.
• Animations, et son et retours haptiques là où ils conviennent.
• Tout découvrable : chaque page accessible depuis l'endroit où les gens sont déjà, et tout ce qui est cliquable a l'air cliquable.
• Onboarding sans friction.
• Les flux restent dans l'application au lieu d'envoyer les gens sur des sites tiers.
• Responsive, et le mobile a l'air natif plutôt que desktop rétréci.
• Une plainte est un motif. Lorsque l'utilisateur signale une chose, trouvez et corrigez ses frères dans toute l'application.

Le médiocre n'est jamais une option.

5. Vérifiez dans l'application en cours d'exécution

Ouvrez l'application dans le navigateur ou le simulateur et utilisez-la : mode clair et sombre, largeur bureau et téléphone, états vides et de chargement. Comparez chaque écran avec ses références et corrigez les écarts. La recherche n'est pas la ligne d'arrivée ; l'écran rendu l'est.

Modèle de plan UI

**Direction :** <le DESIGN.md de l'utilisateur, ou les styles Refero : noms> · clair et sombre
**Tokens :** <rôles de couleur, polices, rayon, espacement>

| Écran ou flux | Références Refero | Ce que nous prenons | Composant 21st.dev |
|---|---|---|---|
| Onboarding | <app : écran>, <app : flux> | Trois étapes, barre de progression, passer | <auteur>/<slug> |

**Construit à la main (aucun candidat) :** <quoi, et pourquoi>