moraneus/preview-first

Que fait preview-first ?

Regardez avant de construire. Cette compétence insère une étape de conception avant toute écriture de code applicatif : le développeur voit plusieurs directions de design complètes et clairement différentes dans son navigateur, en choisit une, et ce choix devient un contrat écrit que toutes les sessions ultérieures suivront.

Il s'agit d'un studio de conception, pas d'un générateur de site web. La compétence n'écrit jamais le code applicatif du développeur. Elle produit une décision et un contrat. Les scripts sont déterministes et utilisent Python standard ; le jugement (lecture du brief, nomination des directions, rédaction du contenu) vous incombe.

Quand l'exécuter, quand la proposer

Exécutez l'étape complète lorsque le développeur s'apprête à démarrer, redémarrer ou restyler un projet web : "construis-moi une landing page pour X", "démarre le frontend", "je n'aime pas l'apparence actuelle", "choisis des couleurs et des polices", ou un /preview-first explicite.

Proposez-la en une ligne lorsqu'un projet possède déjà du code d'interface mais pas de fichier design/DESIGN.md : "Vous voulez d'abord voir des directions de design ? Je peux montrer l'apparence actuelle à côté d'alternatives." Si accepté, importez l'apparence existante comme une direction (voir Imports) afin qu'elle soit comparée sur un pied d'égalité.

Ne la déclenchez jamais pour de petites modifications d'une application déjà stylée ("ajoute un bouton", "corrige le remplissage"). Quand design/DESIGN.md existe, passez à Après la remise.

Le flux

Tous les scripts se trouvent dans le répertoire scripts/ de cette compétence. Exécutez-les avec python3 (ou uv run python3 si le projet utilise uv). Les chemins ci-dessous sont relatifs à la racine du projet.

1. Lire le projet, puis poser quatre questions au maximum

Lisez ce qui existe avant de poser des questions : package.json, configuration Tailwind, propriétés CSS personnalisées, un logo SVG, les polices existantes, un README. Tout ce qui est trouvé est une contrainte, pas une question.

Ne demandez que ce que le dépôt ne peut pas répondre, en langage clair, en un seul message :

1. Quel est le produit et à qui s'adresse-t-il, en une phrase.
2. Trois mots pour décrire l'émotion recherchée, ou un site qu'ils admirent.
3. Quelque chose de fixe : une couleur de marque, un logo, une police, clair ou sombre uniquement.
4. Quel type de page est le plus important : marketing, application, contenu ou boutique.

2. Rédiger le brief

Normalisez les réponses dans .design-preview/brief.json :

{
  "product": "Ledgerline, un outil de facturation pour les développeurs freelances",
  "audience": "développeurs solo et petits studios",
  "product_type": "product-type.saas",
  "moods": ["précis", "calme", "digne de confiance"],
  "page_type": "marketing",
  "constraints": {"brand_colors": ["#154d8c"], "fonts": [], "scheme": "both"},
  "admired": ["https://linear.app"],
  "words": {"name": "Ledgerline", "tagline": "Des factures qui suivent votre git log"}
}

Mappez le texte libre aux identifiants de nœuds avec recommend.py --list product-types et --list moods. Les mots inconnus sont acceptables ; le système de recommandation utilise des alias et un chevauchement de tokens comme solution de repli. Le texte libre dans product_type est également accepté.

3. Rédiger le contenu, puis ouvrir l'aperçu en moins d'une minute

Rédigez d'abord .design-preview/copy.json ; cela prend une courte réponse et c'est ce qui permet à une ébauche d'être lue comme le produit plutôt que comme un modèle. Utilisez les noms propres du produit : la navigation correspond à ses sections, les fonctionnalités sont les choses qu'il fait, le titre est une affirmation qu'un utilisateur répéterait.

{
  "headline": "Live scores for 501, Cricket and Around the Clock",
  "subhead": "Oche tient le score pour que les joueurs puissent continuer à jouer.",
  "lead": "Conçu pour les joueurs de ligue de pub et les amis à la maison.",
  "cta_primary": "Nouvelle partie", "cta_secondary": "Reprendre",
  "nav": ["Parties", "Joueurs", "Statistiques", "Paramètres"],
  "features": [{"title": "501 et 301 avec sorties", "body": "Chaque score restant affiche le chemin de sortie standard."}],
  "proof": "", "meta": {"city": "Leeds", "year": "2026"},
  "footer": "Oche tient le score."
}

Puis une commande :

python3 <skill>/scripts/quick_start.py --brief .design-preview/brief.json --copy .design-preview/copy.json --count 5 --open

Elle recommande des lots, écrit directions.json, construit l'aperçu et démarre le serveur. Donnez immédiatement l'URL au développeur. Si vous omettez --copy, les ébauches utilisent un contenu dérivé des noms du brief ; ne laissez jamais cela dans une direction que vous présentez comme terminée. Affinez directions.json (noms, justification, mise en page, programme) pendant qu'ils regardent, et reconstruisez ; la page se rafraîchit à la même URL.

Chaque page d'aperçu comporte trois générateurs dans sa barre, afin que le développeur n'ait jamais à revenir pour en obtenir plus : Surprise-moi (une direction composée aléatoirement : un style inutilisé, une palette et un appariement appropriés, un tirage aléatoire d'idées, de sections et de programme), Variations (cinq versions de la direction qu'ils regardent : même style, autres palettes, appariements, idées et programmes) et, sur la galerie, Afficher tous les styles (une direction par style pour ce brief). Chacune atterrit sur la nouvelle ébauche, qui comporte les mêmes boutons. Depuis le terminal : random_direction.py --directions .design-preview/directions.json --build .design-preview [--like B | --all].

3a. Lots candidats à la main

python3 <skill>/scripts/recommend.py --brief .design-preview/brief.json --count 4

Chaque lot est un style, une palette, un appariement typographique, des traitements de composants, des motifs de mouvement, un ensemble d'icônes et huit à douze idées de conception (ideas : des mouvements sourcés comme une navigation scindée avec l'heure en direct, un héro de spécimen, des chiffres géants, un grain de film, des boutons en forme de crochets, un pied de page de colophon), avec les arêtes du graphe qui les justifient et des alternatives en direct pour les échanger. La diversité est imposée : familles de styles distinctes, au maximum deux palettes d'une même température, au maximum deux appariements d'une même catégorie typographique, aucune palette ou appariement utilisé deux fois. Trois à cinq lots par défaut, jusqu'à huit lorsque le développeur demande à en voir plus. Ne descendez pas en dessous de trois ; si le brief est restreint (sombre uniquement, une seule couleur de marque), dites-le et montrez quand même trois lots.

4. Rédiger directions.json

Transformez les lots en .design-preview/directions.json (schéma dans knowledge/schema.json, files.directions). Pour chaque direction, fournissez ce qu'un script ne peut pas :

• name : une idée, pas un style ("Ledger", "Greenhouse", "Night shift"). Jamais "Moderne" ou "Propre".
• rationale : un paragraphe qui cite les mots du brief et explique pourquoi cette direction y répond. Mentionnez le choix audacieux et ce qui reste discret.
• copy : le vrai contenu du brief : titre, sous-titre, deux appels à l'action, quatre étiquettes de navigation, trois à six fonctionnalités avec un titre et une phrase chacune, une ligne de preuve honnête (ou vide), un titre de formulaire avec des étiquettes de champs et un texte de soumission, une ligne de pied de page. Casse de phrase, voix active, noms de produit, pas de tirets cadratins, pas d'emoji, pas de flèches, pas de "Que vous soyez X ou Y", pas de tricolons, pas de lorem ipsum, pas de chiffres inventés. Le contenu est le même dans toutes les directions, sauf si la voix d'une direction diffère réellement.
• layout (facultatif) : remplace les variantes de section ; sinon, les idées de la direction puis les valeurs par défaut du style les choisissent.
• bundle.ideas (conserver ou modifier) : les idées attachées par le système de recommandation. Supprimez-en une qui ne correspond pas au produit, ajoutez-en une de recommend.py --list ideas lorsque le brief ou un site admiré le demande. Les idées avec un crochet de rendu modifient l'ébauche ; les autres vont dans le contrat.
• copy.numbers et copy.stats (facultatif) : des chiffres sourcés {value, label, source} ; le héros de nombres et le mur de statistiques ne s'affichent que lorsque ceux-ci existent, jamais avec des chiffres inventés.
• copy.meta (facultatif) : {"city": "Lisbon"} pour la navigation scindée, le colophon et l'horloge superposée.
• Le type de produit apporte un kit thématique (types d'illustrations, un composant thématique tel qu'un terminal, un solde, un planning, un compositeur, un tableau de score, et les noms du produit). Le premier écran et la section qui le suit l'utilisent, donc un tableau de score s'ouvre sur un score et une boutique sur des produits. Définissez layout.topic à none pour supprimer le composant thématique.
• overrides (facultatif) : {"brand_primary": "#hex", "brand_accent": "#hex"} lorsque le brief fixe une couleur de marque. Le constructeur recalcule les couleurs de contraste et signale toute défaillance de contraste.

Avant de construire, exécutez la vérification anti-cliché dans references/anti-patterns.md sur chaque direction. Refusez un cliché à moins que le brief ne le demande par son nom, et dans ce cas, dites-le dans la justification.

La règle du premier écran : aucune direction ne s'ouvre sur le modèle générique (titre centré, deux boutons, une capture d'écran, puis trois cartes identiques). Chaque style utilise par défaut un archétype de mise en page observé sur des sites admirés (paragraphe de déclaration avec figures légendées, texte enveloppant un disque plat, scène centrée sur le produit, police d'affichage à côté d'un objet, illustration à fond perdu, index latéral, type affiche) et des illustrations générées à partir de la palette (plan, figures isométriques, terminal, composition suisse, contours, demi-teintes, anneaux orbitaux, autocollants, sparklines, une seule marque). Conservez ces valeurs par défaut sauf si le brief demande explicitement l'apparence familière. Au moins deux des directions proviennent de styles marqués distinct ; le système de recommandation l'applique, et il s'assure également qu'aucune deux directions ne partagent un dispositif de navigation, un dispositif de premier écran ou une texture.

5. Construire et ouvrir l'aperçu

python3 <skill>/scripts/build_preview.py --directions .design-preview/directions.json
python3 <skill>/scripts/serve_preview.py --dir .design-preview --open

build_preview.py écrit .design-preview/ : une galerie, et pour chaque direction une tuile de style (palette avec grades de contraste dans les deux modes, échelle typographique, espacement, rayon, élévation, icônes, chaque composant dans chaque état, motifs de mouvement jouables), une page ébauchée pour le type de page du brief, et une vue appareils qui rend l'ébauche à l'intérieur de cadres CSS des téléphones, pliables, tablettes et ordinateurs portables les plus populaires avec les vraies tailles d'écran. Les contrôles sur chaque page permettent d'échanger en direct la palette, l'appariement typographique, le rayon, la densité, le niveau de mouvement et le thème.

serve_preview.py démarre un serveur localhost détaché, écrit .design-preview/server.json, imprime l'URL et revient immédiatement. Ajoutez --vendor-fonts à la construction pour une session hors ligne ; sinon, la tuile affiche un avis visible lorsqu'une police web n'a pas pu être chargée.

Si le navigateur ne peut pas s'ouvrir (SSH, conteneur, CI), imprimez l'URL et la liste des directions avec une ligne chacune, et continuez dans le chat.

6. Informer le développeur, puis attendre

Dites ce que vous avez construit, donnez l'URL, nommez les directions en une ligne chacune, et arrêtez-vous. Ne choisissez pas à leur place, ne commencez pas à coder, ne faites pas de sondage. Le développeur peut passer beaucoup de temps dans l'aperçu. Lorsqu'il répond :

• Si .design-preview/selection.json existe, lisez-le. Il contient l'identifiant de la direction et les remplacements en direct (palette, appariement, rayon, densité, mouvement, thème) sur lesquels ils se sont arrêtés.
• Sinon, prenez le choix de leurs mots ("B", "le sombre", "A mais avec la typographie de D") et écrivez selection.json vous-même avec les remplacements correspondants.
• Pour une mutation ("B mais plus chaud", "moins d'angles arrondis", "échange la police du titre"), modifiez directions.json (ou utilisez une alternative du lot), reconstruisez, et renvoyez-les vers la même URL. Le serveur continue de tourner ; demandez-leur de rafraîchir la page.
• Pour "montre-m'en plus", exécutez recommend.py à nouveau avec --count 5 ou un brief modifié, ajoutez les nouvelles directions sous de nouveaux identifiants, et reconstruisez.

serve_preview.py --dir .design-preview --wait 1800 bloque jusqu'à ce qu'une sélection existe, pour une utilisation scriptée uniquement. --status et --stop gèrent le serveur.

7. Exporter le contrat

python3 <skill>/scripts/export_design.py --selection .design-preview/selection.json \
  --directions .design-preview/directions.json --project .

Ceci écrit design/DESIGN.md (le contrat : identité, idées de design avec sources et notes de construction, palette avec tableau de contraste, typographie, espacement et rayon, élévation, mise en page, chaque composant avec états et tokens, tokens de mouvement et motifs autorisés, iconographie, imagerie, style d'écriture, niveau d'accessibilité minimal, vérifications sur appareils, et une liste "à ne pas faire"), design/tokens.json (format W3C Design Tokens), design/tokens.css, design/tailwind.css lorsque Tailwind v4 est détecté, une ligne de pointeur dans CLAUDE.md, et une entrée .gitignore pour .design-preview/. La ré-exportation conserve la section "Notes du projet" et copie les fichiers précédents dans design/history/.

Confirmez en un court message ce qui a été écrit et ce que le développeur doit valider (design/ et la ligne CLAUDE.md). Construisez ensuite selon le contrat.

Après la remise

Lorsque design/DESIGN.md existe :

• Lisez-le avant tout changement d'interface. Utilisez les tokens --pf-* de design/tokens.css, jamais les valeurs hexadécimales, pixel ou millisecondes brutes dans les composants.
• Respectez les motifs de mouvement autorisés et le niveau de mouvement. Respectez la réduction de mouvement.
• Exécutez contrast.py FG BG --role body|label|large|ui sur chaque nouvelle paire de couleurs.
• Suivez la liste "à ne pas faire" ; lorsqu'une demande entre en conflit avec le contrat, dites-le et proposez de relancer l'étape plutôt que de diverger silencieusement.
• Après la construction d'une page significative, proposez la vérification sur appareils : ouvrez .design-preview/<id>/devices.html?url=http://localhost:PORT/path pour voir la page réelle dans les mêmes cadres. Les pages qui envoient des en-têtes de blocage de cadre ne peuvent pas être affichées ; dites-le.
• Conservez les sections libres de design/DESIGN.md (en dessous du marqueur de fin) pour les décisions du projet.

Imports

Pour comparer l'apparence actuelle du projet, ou un site que le développeur admire, comme une direction :

python3 <skill>/scripts/import_direction.py --css src/styles.css --into .design-preview/directions.json --name "Aujourd'hui"
python3 <skill>/scripts/import_direction.py --tailwind tailwind.config.js --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --tokens design-tokens.json --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --url https://example.com --into .design-preview/directions.json --name "Référence"

L'import dérive une palette, un appariement et le style le plus proche, puis reconstruit. Les palettes importées sont vérifiées comme toutes les autres ; les échecs apparaissent dans la tuile.

Connaissances et rafraîchissement

Les décisions proviennent de knowledge/graph.json : styles, palettes (OKLCH, les deux modes), appariements typographiques, traitements de composants, motifs de mouvement, types de produits, humeurs, ensembles d'icônes, fonctionnalités de plateforme, sites de référence, reliés par des arêtes pondérées pairs_with, suits, avoid_with, requires, ex...