- Des widgets interactifs écrits dans la page sous forme de composants React.
- Des vidéos du produit, ou d’une session d’agent, enregistrées avec un script de navigateur.
- Des captures d’écran dans des cadres, en versions claire et sombre.
- Des tableaux pour les statuts, les limites et les comparaisons.
Les produits, les chiffres et les étapes des exemples de ce guide sont des données d’exemple.
Un widget est un composant React déclaré dans la page avec
export const, puis placé avec une balise comme <RxJourney />. Placez les définitions des composants à la fin du fichier pour que le contenu se lise de haut en bas. Consultez Composants React pour savoir ce que prend en charge l’environnement MDX.
Utilisez un stepper lorsqu’un processus suit un ordre clair. Chaque étape indique qui agit et ce qui se passe.
Utilisez une calculatrice lorsque la réponse dépend des valeurs saisies par le lecteur. Affichez la formule dans le résultat pour que les lecteurs puissent la vérifier.
Utilisez un graphique avec un sélecteur lorsque les lecteurs basculent entre quelques séries liées. Limitez chaque graphique à une seule question.
Voici le code source complet de la calculatrice. Les boutons de forfait, les curseurs et le résultat lisent tous l’état, et le total est calculé au rendu.
usage.mdx
- Faites fonctionner chaque couleur en mode clair et en mode sombre. Utilisez
currentColorouinheritpour le texte et les traits, des gris translucides commergba(127,127,127,.25)pour les bordures et les remplissages, et une seule couleur d’accent. Évitez le noir ou le blanc fixes. - Ajoutez
className="not-prose"à l’élément extérieur pour que les styles typographiques de la page ne modifient pas l’espacement dans le widget. - Écrivez les données dans le composant sous forme de constantes. Ne récupérez pas de données et n’utilisez pas
localStorage,sessionStorageni les cookies, car ils échouent ou ne font rien dans l’éditeur. - Écrivez du JavaScript simple. Une annotation TypeScript casse toute la page sur votre site publié.
- Placez les liens dans le texte autour d’un widget. Les liens à l’intérieur d’un widget ne fonctionnent pas dans l’éditeur.
- Donnez aux composants de chaque page un préfixe court commun, comme
Rx, pour que leurs noms n’entrent pas en conflit avec les composants intégrés ni entre eux. - Donnez aux boutons et aux champs des libellés visibles ou un
aria-label, et indiquez l’option sélectionnée avecaria-pressedouaria-current. - Limitez chaque page à quelques widgets. L’éditeur exécute au maximum 10 widgets à la fois et met les autres en pause jusqu’à ce qu’ils apparaissent à l’écran.
- Pour utiliser un widget sur plusieurs pages, déplacez-le dans un fichier sous
/snippets/et importez-le. Consultez Extraits réutilisables.
record.mjs
- Faites une pause d’environ une seconde après chaque action, pour que les lecteurs puissent suivre le changement.
- Saisissez le texte avec un délai au lieu de remplir les champs instantanément.
- Gardez les vidéos sous 30 secondes. Découpez les flux plus longs en plusieurs vidéos placées à côté des étapes qu’elles montrent.
- Utilisez des comptes et des données d’exemple, jamais des données de production.
claude -p "<task>" --output-format stream-json --verbose > session.jsonl. Affichez les messages et les appels d’outils dans une page HTML simple de style terminal, puis enregistrez cette page avec le script Playwright. Une rediffusion montre les vraies commandes et l’ordre dans lequel l’agent les a exécutées, sans exposer de terminal en direct.
Placez les captures d’écran dans un <Frame> avec une légende qui indique quoi regarder. Recadrez sur la partie de l’écran qui compte.
page.screenshot({ path: "images/settings-light.png" }) et relancez-le lorsque l’interface change. Pour la version sombre, créez le contexte avec colorScheme: "dark". Consultez Images et intégrations pour les options de taille et de zoom.
Les tableaux contiennent les détails que les lecteurs viennent rechercher : statuts, limites, prix et prise en charge selon les options. Commencez par le tableau et gardez le texte autour concis.
Pour une page composée principalement de tableaux, définissez
mode: "wide" dans le frontmatter pour leur donner toute la largeur. Consultez Mode de page.
Les agents de code écrivent bien les widgets et les scripts d’enregistrement lorsque vous leur donnez le modèle et les données. Indiquez ce guide à l’agent, puis décrivez ce que vous voulez que le lecteur comprenne.
Widget
Video
- Ouvrez la page avec
mint devou dans l’éditeur, en mode clair et en mode sombre. - Vérifiez que chaque widget s’affiche et réagit aux clics et au clavier.
- Réduisez le navigateur à la largeur d’un téléphone et vérifiez que rien ne déborde.
- Lisez chaque vidéo et ouvrez chaque image.