Chapitre 2.4 — Poser design & conventions au départ

⏱️ TL;DR — Au kickoff, tu ne construis pas tout le design system ni toutes les conventions — tu poses le socle minimal qui empêche la dérive : d’où viennent les composants, quels tokens, et 4-6 règles de code non négociables. Ce socle prend 20 minutes et devient la matière du CLAUDE.md (Partie 3) et du design system (Partie 4). L’erreur inverse — « on verra le design plus tard » — garantit dix écrans dépareillés qu’on ne rattrapera jamais vraiment.

🎯 Objectifs

Poser un socle de design minimal mais suffisant dès le premier jour.
Choisir d’où viennent les composants (la décision la plus structurante pour la cohérence UI).
Formuler 4-6 conventions de code non négociables.
Semer ce socle pour qu’il soit vivant (fichier-modèle + futur CLAUDE.md).

« On verra le design plus tard » : le piège fondateur

C’est la décision de cadrage qu’on saute le plus souvent — et celle qui coûte le plus cher. Le design n’est pas une couche de peinture qu’on ajoute à la fin : c’est un système de contraintes (espacements, couleurs, primitives) que chaque écran hérite. Si tu ne le poses pas au départ :

l’écran 1 invente ses marges, l’écran 2 les siennes ;
un Button naît ici, un autre là, légèrement différent ;
à l’écran 10, « harmoniser » = tout réécrire.

Poser le socle au départ ne fige pas ta créativité : il te donne une base cohérente que tu fais évoluer globalement (changer un token propage partout) au lieu de rustines locales.

La décision-clé : d’où viennent les composants ?

Avant les couleurs et les polices, tranche la source des composants. C’est ce qui détermine 80 % de la cohérence UI. Trois grandes familles :

Approche	Quand	Effet sur la cohérence
Primitives maison (`src/components/ui/`)	tu veux contrôle total, design distinct	forte si tu imposes de passer par elles
Kit copié-collé (ex. shadcn/ui)	démarrer vite avec des bases solides et éditables	forte : tout part du même moule
Lib de composants lourde	prototypage, admin interne	moyenne : styles imposés, personnalisation limitée

Le point crucial n’est pas laquelle — c’est de l’écrire et d’imposer qu’on passe par là. « Tout composant d’UI vient de src/components/ui/ ; on n’introduit pas de nouvelle lib sans décision » est une phrase qui, dans ton CLAUDE.md, empêche l’agent de réinventer un Modal à chaque feature.

⚠️ Piège — Laisser coexister deux sources de composants (« un peu de maison, un peu de lib, un peu à la main »). C’est la recette de l’incohérence UI. Une source primaire, écrite, et des exceptions décidées — pas subies.

Les tokens minimaux

Tu n’as pas besoin d’un design system complet au jour 1. Tu as besoin de tokens — les variables de design dont tout hérite :

Couleurs sémantiques (brand, surface, muted, danger…), pas des hex en dur dans les composants.
Espacements (l’échelle Tailwind par défaut suffit souvent).
Rayons et ombres (2-3 valeurs).
Typo (une police, une échelle de tailles).

L’important : que ces tokens soient définis à un seul endroit (config Tailwind / CSS variables) et que la règle « pas de couleur en dur, on utilise les tokens » soit posée. On approfondit en Partie 4.

Les 4-6 conventions non négociables

Le kickoff n’est pas le moment d’un guide de style de 40 règles (personne ne le suivra, l’agent non plus — un CLAUDE.md obèse se fait ignorer). Choisis les 4 à 6 conventions qui structurent vraiment :


1. Organisation : feature-folders sous src/features/<feature>/.
2. Imports : alias @/ (jamais de ../../..).
3. TypeScript : mode strict, any interdit, erreurs typées.
4. Données : lecture via queries.ts, mutations via server actions dans actions.ts.
5. UI : composants d'UI depuis src/components/ui/ uniquement.
6. Validation : un schéma Zod par entité, partagé client/serveur.

Ces règles sont prescriptives et vérifiables. « Écris du code propre » n’en est pas une (invérifiable). « Pas de any » en est une (le lint la vérifie — futur hook, Partie 7).

💡 Réflexe d’architecte — Une convention n’a de valeur que si on peut dire, sur un bout de code, « ça la respecte » ou « ça la viole ». Si tu ne peux pas trancher, ce n’est pas une convention, c’est un vœu. Réserve le CLAUDE.md aux règles tranchables, et délègue leur application aux hooks/lint quand c’est mécanique.

Semer le socle : le rendre vivant

Poser le socle, c’est bien ; le rendre présent pour l’agent, c’est indispensable. Deux gestes :

Le premier composant bien fait devient le fichier-modèle. Fais soigner un Button (tokens, types, a11y) puis dis à l’agent : « pour tout nouveau composant d’UI, suis exactement le style de src/components/ui/button.tsx ». Un exemple vivant vaut dix règles écrites.
Les conventions vont dans le CLAUDE.md (Partie 3), pour survivre aux sessions.

🧭 Sur TaskFlow — À l’atelier 2.5, on posera : composants depuis src/components/ui/, tokens Tailwind custom, et les 6 conventions ci-dessus. On fera soigner un composant Button comme référence. Toute la Partie 4 s’appuiera sur ce socle pour tenir la cohérence dans la durée.

✏️ Exercices

Exercice 1 — La source des composants. Pour ton projet, écris la phrase qui fixe d’où viennent les composants d’UI et l’exception admise. Teste-la : est-elle assez claire pour qu’un agent sache quand il a le droit de créer une nouvelle primitive ?

✅ Solution

Une bonne formulation est positive + bornée : « Tout composant d’UI réutilisable vit dans src/components/ui/ et suit le style de button.tsx. On n’ajoute pas de lib de composants ni de nouvelle primitive sans que je valide. » L’agent sait alors qu’il compose avec l’existant par défaut, et demande avant d’élargir.

Exercice 2 — Six conventions tranchables. Écris tes 6 conventions non négociables. Pour chacune, vérifie qu’on peut dire « respectée / violée » sur un exemple concret. Barre celles qui sont des vœux.

✅ Solution

Gardent leur place : structure de dossiers, alias d’import, no-any, pattern de data/mutations, source des composants, validation. Se font barrer : « code lisible », « bonnes pratiques », « performant » — invérifiables tels quels. Une convention floue ne guide personne ; transforme-la en règle concrète ou supprime-la.

🧠 Quiz de révision

1. Pourquoi « on verra le design plus tard » est-il un piège coûteux ?

Parce que le design est un système de contraintes hérité par chaque écran, pas une peinture finale. Sans socle, chaque écran invente le sien ; à l’écran 10, harmoniser = tout réécrire. La dette visuelle devient irrattrapable.

2. Quelle est la décision de design la plus structurante ?

D’où viennent les composants (primitives maison / kit copié / lib lourde) — et surtout imposer qu’on passe par cette source. Elle détermine l’essentiel de la cohérence UI.

3. Qu’est-ce qu’un « token » et pourquoi le centraliser ?

Une variable de design (couleur sémantique, espacement, rayon, typo) définie à un seul endroit, dont tous les composants héritent. Centralisé, un changement se propage partout ; en dur, il faut le corriger écran par écran.

4. Qu’est-ce qui distingue une vraie convention d’un « vœu » ?

Une vraie convention est tranchable : sur un bout de code, on peut dire « respectée » ou « violée » (no-any, alias @/). Un vœu (« code propre ») est invérifiable et ne guide ni toi ni l’agent.

5. Comment rendre le socle « vivant » ?

Avec un fichier-modèle (un composant exemplaire que l’agent imite) et le CLAUDE.md (conventions écrites, persistantes). Un exemple concret vaut dix règles ; les deux ensemble rendent la cohérence par défaut.

Chapitre suivant : Atelier — kickoff de TaskFlow — on déroule un vrai démarrage, du dossier vide au premier composant modèle.