Promptory Web Build
Trois outils, une pile, chacun avec un rôle :
| Outil | Rôle | Règle empirique |
|---|---|---|
| Lenis | Moteur de défilement — défilement fluide et inertiel par-dessus le défilement natif | Installé une fois, globalement. Jamais par section. |
| GSAP (+ ScrollTrigger) | Moteur d'animation — timelines personnalisées, animation pilotée par le défilement, pinning | Tout ce qui est spécifique à la conception de ce site. |
| React Bits | Composants animés prêts à l'emploi (texte, arrière-plans, curseurs, cartes, boutons) | Utilisez-le en premier lorsqu'un composant du catalogue réalise déjà l'effet. |
Ils partagent une boucle d'animation : le ticker de GSAP pilote Lenis, et ScrollTrigger lit le défilement de Lenis. Faire fonctionner ce câblage correctement est la chose la plus importante de cette compétence (§3).
Périmètre : Web/DOM en temps réel uniquement. Pour le rendu vidéo (Remotion, reels), cette compétence ne s'applique pas.
0. Règle d'or — ne pas redessiner
Implémentez la conception et les effets demandés par l'utilisateur. Ne modifiez pas la mise en page, les couleurs, les polices, l'espacement ou le texte par vous-même, et n'ajoutez pas de sections supplémentaires ou d'effets « bonus » non demandés. Si un effet ou une correction améliore clairement quelque chose, suggérez-le en une ligne et attendez un accord. Le mouvement et les vérifications qualité doivent servir la conception existante, pas la remplacer.
0.5 Questionnaire d'admission — PREMIÈRE étape pour toute nouvelle demande de site Web
Avant d'écrire du code pour un nouveau site, exécutez le questionnaire d'admission dans references/intake-questionnaire.md :
- Lisez la demande et ignorez tout ce qui est déjà répondu.
- Posez les questions restantes en 3 courtes séries au maximum (projet → mouvement → livraison). Utilisez l'outil
AskUserQuestionde Claude Code lorsqu'il est disponible (options cliquables + boîte de texte libre « Autre » automatique) ; sinon, affichez chaque série comme un bloc de code avec des options lettrées et une ligne vide « ✎ أخرى » pour chaque question. - Affichez le Brief du Projet dans un bloc de code et attendez le feu vert.
- Ensuite, construisez, en suivant exactement les réponses.
Si l'utilisateur dit « ابدأ على طول » / « passez », utilisez les valeurs par défaut ⭐ et indiquez-les dans le Brief. Pour les petites modifications sur un site existant, passez le questionnaire à moins que la demande ne soit ambiguë.
Le brief doit enregistrer : la langue et la direction (arabe/RTL, anglais/LTR, ou les deux), la cible d'accessibilité (par défaut WCAG 2.2 AA), les formulaires et leur backend, et l'outil d'analyse si présent.
0.6 Références visuelles — Prompt Motion
https://prompt-motion.com/ est la bibliothèque visuelle pour la direction du mouvement (typographie cinétique, UI produit, particules, formes, graphiques…, chacun avec l'invite derrière lui). Utilisez-la uniquement lorsque l'utilisateur demande de l'inspiration, choisit « a besoin d'une proposition » / « mouvement audacieux » dans le questionnaire, ou partage un lien depuis celle-ci. Empruntez l'idée de mouvement, reconstruisez-la avec GSAP / Lenis / React Bits, gardez la conception du client. Workflow, carte catégorie→composant et le modèle de spécification de mouvement : references/visual-references.md.
0.7 Barre de qualité — vérifiez avant de montrer quoi que ce soit
Analysez la construction pour les signes révélateurs de sortie générique (accent indigo par défaut, icônes émoji, métriques inventées, lorem ipsum, sections de modèle standard). Corrigez ce qui est dans votre propre code ; suggérez une correction d'une ligne pour tout ce qui est dans la conception du client. Liste complète : references/quality-bar.md.
0.8 Direction de conception — chaque site a un aspect différent
Lorsque le client n'a pas sa propre conception, choisissez une direction avant d'écrire du code. Lisez references/design-styles.md et :
- Présélectionnez trois directions du guide d'adaptation pour le secteur et le public du brief.
- Ignorez toute direction utilisée dans les trois derniers sites de ce chat ou projet (Journal des Styles).
- Écrivez une ligne dans le Brief du Projet :
Direction : <nom> — <pourquoi>, avec une alternative. - Construisez avec les choix signature de cette direction, puis effectuez la vérification de Variété : au moins quatre des six axes doivent différer du site précédent.
Les directions sont des références pour la structure et l'ambiance. Ne copiez jamais la marque, les photos, le texte ou la mise en page exacte d'une référence. Si le client fournit une conception, suivez-la et ignorez cette étape (§0 règle d'or).
0.9 Conception visuelle distinctive (lorsque le brief laisse le champ libre)
Source : anthropics/skills, compétence frontend-design (Apache-2.0, voir son LICENSE.txt). S'applique uniquement lorsque le brief laisse la direction visuelle ouverte. §0 prévaut : suivez la conception du client et les propres termes du brief, y compris lorsque le brief demande l'un des looks listés ci-dessous.
- Identifiez d'abord le sujet : produit, public, tâche principale. Si le brief ne le dit pas, proposez-en un et confirmez. Le secteur d'activité et les matériaux sont les sources des choix distinctifs.
- La section Hero s'ouvre avec la chose la plus caractéristique du monde du sujet (titre, image, démo en direct ou interaction). Évitez le défaut d'un grand nombre, d'une petite étiquette et d'un accent dégradé, sauf si c'est clairement la meilleure option.
- Typographie : une famille, ou deux qui sont clairement distinctes. Définissez une échelle typographique claire. Dans les titres, le traitement typographique fait partie de la conception.
- Longueur de ligne inférieure à 80 caractères. Le texte en corps sérif a besoin d'un interlignage légèrement plus grand que le sans-serif.
- Évitez les marqueurs typographiques : un mot en italique ou coloré dans un titre, des étiquettes en majuscules, et des étiquettes au-dessus des titres qui n'ajoutent rien.
- Marqueurs numérotés (01 / 02 / 03) uniquement lorsque le contenu est vraiment une séquence.
- Mouvement : un moment orchestré (chargement de page ou une seule révélation). Pas de fondu-glissade sur chaque section, pas de transition au survol sur chaque carte. Le mouvement qui répond à une action de l'utilisateur (ouverture, expansion, confirmation) est acceptable.
- Planifiez avant le code : 4 à 6 couleurs hexadécimales nommées, rôles typographiques, un concept de mise en page (wireframe ASCII autorisé), et des principes. Passez en revue le plan par rapport au brief. Si une partie ressemble à la valeur par défaut générique pour n'importe quelle page similaire, révisez-la et dites ce qui a changé.
- Looks par défaut à éviter sauf si le brief les demande : fond crème avec accent terre cuite ; noir presque pur avec accent vert acide ou vermillon ; format journal avec filets fins et rayon nul ; cartes SaaS arrondies identiques avec un rayon et une ombre grise ; sourcil EN MAJUSCULES au-dessus de chaque titre ; chaînes de métacharactères à point médian ('A·B·C') ; étiquettes 'MOT — fragment' ; #0B0B0B ou #111 comme substitut du noir ; monospace pour les petites étiquettes ; '→' sur chaque lien.
- Utilisez l'audace à un seul endroit. Gardez tout le reste autour calme. Supprimez la décoration qui ne sert pas le brief.
- Plancher de qualité : réactif sur mobile, focus visible, mouvement réduit respecté, contraste accessible.
- Surveillez la spécificité des sélecteurs CSS, en particulier le remplissage et la marge entre les sections, où les règles s'annulent mutuellement.
- Texte : mots simples pour l'utilisateur final, voix active, casse de phrase. Gardez un verbe tout au long d'un flux (« Publier » mène à « Publié »). Les erreurs disent ce qui s'est passé et comment y remédier, sans s'excuser. Les états vides invitent à l'action suivante.
1. Flux de décision — quel outil pour quelle demande
- Site arabe, bilingue ou RTL → lisez
references/rtl-arabic.mdavant d'écrire une mise en page. La direction est structurelle ; la rétro-ingénierie est coûteuse. - Défilement fluide n'importe où sur le site → Lenis (fournisseur global, §3). Faites-le une fois à la configuration du projet lorsqu'une animation de défilement existe.
- Existe-t-il un composant React Bits qui réalise déjà l'effet ? → vérifiez
references/react-bits-catalog.md→ installez-le (§4). Cas typiques : texte divisé/flou/brouillé, texte révélé au défilement, arrière-plans animés (aurore, particules, grilles, shaders), curseurs personnalisés, cartes magnétiques/inclinées, marquees, galeries, dock/menus, boutons/compteurs animés. - L'effet est spécifique à cette conception (séquence d'introduction hero, section de narration épinglée, section à défilement horizontal, révélations synchronisées de plusieurs éléments) → timeline GSAP / ScrollTrigger (§5, détails complets dans
references/gsap.md). - Le projet n'est PAS React (HTML simple/vanilla) → React Bits n'est pas disponible ; utilisez Lenis + GSAP uniquement (
assets/vanilla-setup.js). - Tout formulaire, liste, réservation ou section pilotée par les données →
references/forms-and-states.md(étiquettes, erreurs, cinq états). - Choix d'un service tiers (polices, backend de formulaire, analyse, hébergement, images) →
references/free-services.md, puis vérifiez les limites actuelles. - Nouveau site sans conception client → choisissez d'abord une direction (§0.8,
references/design-styles.md).
2. Installation
npm install gsap @gsap/react lenis
@gsap/react→ uniquement pour les projets React (fournituseGSAP).lenis/reactetlenis/snapsont livrés danslenis— pas de paquets supplémentaires.- Tous les plugins GSAP (ScrollTrigger, SplitText, Flip, ScrollSmoother, Draggable…) sont livrés dans
gsap. - Les composants React Bits sont ajoutés individuellement via la CLI (§4) ; certains apportent leurs propres dépendances (
motion,three,ogl,matter-js…) — la CLI les installe, mais vérifiez la colonne Dépendances dans le catalogue avant de choisir, pour éviter de gonfler le bundle.
N'utilisez jamais ScrollSmoother de GSAP avec Lenis — ce sont deux moteurs de défilement fluide concurrents. Lenis est le moteur de défilement de cette pile.
3. Câblage de Lenis + GSAP + ScrollTrigger (faites exactement cela)
React / Next.js
Copiez assets/SmoothScroll.jsx dans le projet (par exemple components/SmoothScroll.jsx) et enveloppez l'application une fois :
// app/layout.jsx (Next.js App Router)
import SmoothScroll from '@/components/SmoothScroll';
import ScrollToTopOnRoute from '@/components/ScrollToTopOnRoute';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<SmoothScroll>
<ScrollToTopOnRoute />
{children}
</SmoothScroll>
</body>
</html>
);
}
Pour l'arabe, définissez lang et dir à partir de la locale sur <html> (voir references/rtl-arabic.md §1).
Pour Vite/React, enveloppez <App /> dans main.jsx de la même manière et ignorez ScrollToTopOnRoute (il utilise next/navigation).
Ce que fait le fournisseur — et pourquoi chaque ligne est importante :
<ReactLenis root options={{ autoRaf: false }}>→ une instance globale sur<html>;autoRaf: falseparce que GSAP la pilotera.lenis.on('scroll', ScrollTrigger.update)→ ScrollTrigger se recalcule à chaque frame de défilement fluide. Si manque = les animations se déclenchent tard/aux mauvaises positions.gsap.ticker.add(t => lenis.raf(t * 1000))→ une boucle partagée (le temps GSAP est en secondes, Lenis veut des ms).gsap.ticker.lagSmoothing(0)→ pas de bégaiement pour rattraper après un changement d'onglet.ScrollTrigger.refresh()après les polices et le chargement → les positions de déclenchement correspondent à la mise en page finale.
Vanilla HTML/JS
Utilisez assets/vanilla-setup.js comme module d'entrée, importez lenis depuis celui-ci si nécessaire.
4. React Bits — choisir et installer les composants
- Trouvez le composant dans
references/react-bits-catalog.md(groupé : Animations de texte, Animations, Composants, Micro, Arrière-plans — nom, ce qu'il fait, dépendances). - Choisissez la variante correspondant au projet :
JSouTS, puisCSSouTW(Tailwind). - Installez :
Pour la forme courtenpx shadcn@latest add @react-bits/SplitText-TS-TW@react-bits/, lecomponents.jsondu projet doit contenir :Pas de{ "registries": { "@react-bits": "https://reactbits.dev/r/{name}.json" } }components.json/ pas un projet shadcn ? Utilisez l'URL directe à la place :npx shadcn@latest add https://reactbits.dev/r/SplitText-TS-TW.json # ou npx jsrepo@latest add https://reactbits.dev/r/SplitText-TS-TW - Ouvrez le fichier installé et lisez ses props avant de l'utiliser — chaque composant est configurable (couleurs, vitesse, délai, easing, déclencheurs). Définissez les props pour qu'elles correspondent aux jetons de conception existants du site (couleurs, polices) plutôt que de laisser les valeurs par défaut de démo.
- Si l'utilisateur souhaite le flux de travail agent :
npx shadcn@latest mcp init --client claudeconnecte Claude Code au registre via MCP.
Notes d'intégration :
- Les composants React Bits qui s'animent au défilement (ScrollReveal, ScrollFloat, AnimatedContent, SplitText…) utilisent GSAP ScrollTrigger ou IntersectionObserver en interne → ils fonctionnent avec Lenis automatiquement tant que §3 est en place.
- Les composants sont des composants client (
'use client'). Dans Next.js, rendez-les dans des composants client ou des pages qui le permettent. - Les arrière-plans WebGL/shader (dépendances
three,ogl,vgpu) sont lourds : maximum un ou deux par page, chargez paresseusement ceux en dessous de la ligne de flottaison (next/dynamicavecssr: falseouReact.lazy), et donnez-leur un conteneur de taille fixe. Mettez-les en pause lorsqu'ils sont hors écran ou lorsque l'onglet est caché. - N'empilez pas deux effets de curseur ou deux arrière-plans dans la même zone d'affichage.
- Vérifiez chaque composant pour une commande de pause s'il boucle pendant plus de 5 secondes (voir
references/accessibility-motion.md§5). - Licence : React Bits est MIT + Commons Clause — libre d'utilisation à l'intérieur de tout site Web client (y compris le travail client rémunéré), mais les composants eux-mêmes ne doivent pas être revendus ou redistribués en tant que pack/modèle. Ne collez jamais le code source de React Bits dans cette compétence ou une bibliothèque partagée ; installez toujours depuis le registre.
5. Essentiels GSAP (animation personnalisée)
Toujours dans React via useGSAP avec un scope — jamais de useEffect brut :
'use client';
import { useRef } from 'react';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import { useGSAP } from '@gsap/react';
gsap.registerPlugin(ScrollTrigger, useGSAP);
export default function Story() {
const root = useRef(null);
useGSAP(() => {
const tl = gsap.timeline({
scrollTrigger: { trigger: root.current, start: 'top top', end: '+=150%', scrub: 1, pin: true },
});
tl.from('.line', { yPercent: 100, autoAlpha: 0, stagger: 0.15 })
.to('.image', { scale: 1.15 }, '<');
}, { scope: root });
return <section ref={root}>…</section>;
}
Modèles de base (détails + matchMedia réactif, traitement par lots, FOUC, liste de contrôle dans references/gsap.md) :
- Timelines pour tout ce qui a >1 élément ;
ScrollTrigger.batch()pour les cartes répétées. scrubpour le mouvement lié au défilement (avec Lenis,scrub: trueest déjà fluide ;scrub: 1ajoute un décalage supplémentaire).pin: truefonctionne avec Lenis sur le défilement natif — pas de bidouillespinTypenécessaires lorsque Lenis utiliseroot.- Section à défilement horizontal : épinglez le wrapper, animez le
xdu rail vers-(track.scrollWidth - innerWidth),scrub: true,invalidateOnRefresh: true. En RTL, inversez la direction (voirreferences/rtl-arabic.md§6). - Enveloppez les blocs décoratifs dans
gsap.matchMedia()afin que les utilisateurs en mouvement réduit obtiennent le substitut (references/accessibility-motion.md). - SplitText est disponible dans GSAP (
gsap.SplitText) — utilisez-le pour les animations de titre. - TextPlugin est également disponible (
gsap.TextPlugin) — écrivez/devinette. Pour les compteurs :{ textContent: '...' }et un plugin de stabilisation si le nombre change de manière répétée.
6. Formulaires et états
Consultez references/forms-and-states.md pour :
- Les 5 états de formulaire (vide → frappe → validation → soumis → réponse).
- Messages d'étiquette, d'erreur et d'aide pour l'accessibilité.
- Backend — choisissez le service dans
references/free-services.mdet branchez-le.
7. Raccourcis de réutilisation
assets/vanilla-setup.js— câblage Lenis + GSAP pour les projets non-React. Importez-le et distribuezlenislà où c'est nécessaire.assets/pinned-scroll.js— sections épinglées ScrollTrigger prêtes à être déployées avec une timeline personnalisable.assets/horizontal-scroll.js— section à défilement horizontal tout-en-un (wrapper, rail, déclencheur ; nom de la classe d'élément de carte configurable).assets/scrollToTop.jsx— utiliselenis.scrollTo(0, { immediate: false })pour gérer le défilement vers le haut sur les changements de route (Next.js App Router).assets/scale-animation.js— animation introductive par mise à l'échelle avec Lenis. Utile pour les chargements de page.assets/text-reveal-animation.js— révélations de texte au défilement utilisant des wrappers d'élément. Personnalisable (délai, easing, direction).assets/rtl-lenis-smoothscroll.jsx— version deSmoothScroll.jsxavecdir="rtl"sur l'enveloppe Lenis. Remplacez<SmoothScroll>dans la mise en page pour les sites RTL.assets/cursor.jsx— curseur personnalisé React Bits + suivi de défilement Lenis. Utilisez-le comme un curseur par défaut prêt à l'emploi.assets/App.jsx— Application de référence Vite + React avec Lenis + GSAP. Inclut la 404 et la configuration de base.
Pour utiliser un module vanilla :
import { lenis } from './assets/vanilla-setup.js';
Chaque ressource a une brève note de documentation en haut de son fichier décrivant son objectif et comment elle se connecte. Consultez ces notes avant de modifier un module.
8. Livraison et vérification finale
Avant de soumettre le site :
- Dernière vérification de la barre de qualité (
references/quality-bar.md) — supprimez les artefacts génériques de l'agent IA. - Test de défilement fluide : Lenis + GSAP est-il actif sur toute la page ? Le
useGSAPavecscopes'applique-t-il correctement ? - Test d'accessibilité : navigation au clavier, état du focus (
:focus-visible),prefers-reduced-motionrespecté. - Test de mouvement réduit (GSAP
matchMedia+ Lenis stop + React Bits composants de pause). - Pages 404 : esthétique du site (pas de modèle Next.js par défaut, pas de lien vers la documentation de l'agent IA).
- Formulaire de contact : testez 5 états, le backend doit réellement livrer (Web3Forms, Formspree, etc.).
- Analytics : installé et vérifié (sans objet si absent).
- Tests sur mobile et tablette : défilement, boutons, formulaires, espacement.
- Politiques de Cookies/Confidentialité (si le site a des formulaires, un suivi ou est public ;