Système de design pour la documentation de Recurly

1. Aperçu rp-overview

   Deux à quatre phrases sur le contenu de la page.

2. Forfait rp-plan

   Qui peut utiliser la fonctionnalité, avec un libellé fixe par forfait afin d’exprimer la disponibilité de façon uniforme.

3. Callout rp-callout

   Quatre variantes — note, conseil, important et avertissement — avec leur propre icône et leur propre couleur.

4. Liens de section rp-toc

   Des liens numérotés vers chaque section de premier niveau, générés à partir des titres.

5. Liste de prérequis rp-list

   Sous un titre Prerequisites ou Limitations.

6. Définition rp-definition

   Une explication simple de ce dont il s’agit et de sa raison d’être, distincte de l’aperçu.

7. Bénéfices clés rp-benefits

   Trois ou cinq éléments s’ajustent automatiquement ; exactement quatre passent dans une grille 2 × 2.

Le lecteur retrouve le même rythme sur chaque page : de quoi il s’agit, qui peut l’utiliser, où accéder directement, puis les détails. Les rédacteurs disposent de modèles réutilisables pour chaque partie du guide. Les mêmes tokens restylent aussi la navigation, les onglets de code et l’API playground de ReadMe.

Le portail global dirige les lecteurs vers la documentation de chaque produit à partir d’un seul bloc HTML et d’une feuille de style limitée à celui-ci. Chaque accueil produit emploie le même vocabulaire visuel, adapté aux parcours de ses lecteurs.

• Carte de lancement à la une

  Un espace pleine largeur pour le produit le plus récent : colonne de contenu, panneau du logo et badge « New » dont le battement s’arrête lorsque prefers-reduced-motion est activé.

• Grille de produits 2 × 2

  Des cartes uniformes avec bandeau visuel, étiquette, titre, description et rangée d’appel à l’action. Au survol, la carte monte, la bordure se teinte et la flèche avance.

• Adaptatif dès la conception

  Breakpoints à 768, 480 et 375 px. La carte mise en avant s’empile, la grille passe à une colonne et la taille des caractères diminue par étapes.

• Robuste face à la plateforme hôte

  Protection contre les débordements, min-width: 0 sur les enfants flex et resets explicites pour éviter que le thème ReadMe injecte ses soulignements ou ses largeurs.

• Recherche native derrière une interface sur mesure

  La barre de recherche du hero ouvre la recherche native de ReadMe. Ce point d’entrée aux couleurs de la marque conserve le comportement existant de la plateforme.

• Un vocabulaire par accueil produit

  Chaque accueil réutilise le même bloc de surtitre, titre et description, avec une navigation rapide et des cartes adaptées aux tâches des lecteurs de ce produit.

ReadMe effectue le rendu avec React et remplace les pages côté client : un script exécuté une seule fois au chargement cesse donc de fonctionner au clic suivant. Les modules se rattachent après chaque changement de page et évitent de créer des handlers en double lorsqu’ils se réinitialisent.

// Capture phase: runs before ReadMe's
// own React click handlers
window.addEventListener("click", handleClick, true);

// Child-list changes only, so this script's
// own class/href writes can't loop back
state.observer = new MutationObserver(handleRouteCheck);
state.observer.observe(document.body, {
  childList: true, subtree: true,
});

// ReadMe updates URL, article, and active
// classes in separate render passes
[50, 150, 400, 900].forEach((ms) =>
  setTimeout(queueApply, ms));

• Redirection de la navigation Changelog

  Fait pointer l’onglet Changelog natif de chaque portail vers une page personnalisée et maintient l’onglet actif sur toutes les routes : navigation SPA, rechargements, précédent/suivant et menu mobile.

• Pastille « Link copied » sur les titres

  Un clic sur un titre copie son lien profond. Une pastille monte puis disparaît — avec un double requestAnimationFrame pour garantir la transition — et se rattache après chaque changement de page.

• Carrousel en boucle

  Utilise deux clones de chaque côté, un état actif, les touches fléchées, un positionnement adapté au redimensionnement et une réinitialisation après navigation.

• Recherche du hero et zoom d’image

  La barre du hero ouvre la recherche native de ReadMe avec des sondages bornés jusqu’à ce que la cible existe. Un zoom léger suit le curseur sur les grandes captures.

• Uniquement des hooks stables

  Cible les classes rm- et les libellés ARIA de ReadMe, jamais les noms hachés de modules CSS qui changent à chaque déploiement.

• Idempotent par construction

  Une clé globale munie de destroy() démonte l’instance précédente si le script est chargé deux fois.

• Respect de l’intention du lecteur

  Les clics avec Cmd/Ctrl/Shift et le bouton central gardent leur comportement natif, l’URL corrigée étant déjà en place.

J’ai connecté Claude à ReadMe pour lire, restructurer et mettre à jour les pages existantes par lots. La boucle a conservé le slug et la position de chaque page dans la barre latérale ; j’ai vérifié le rendu et réintégré les corrections dans le skill.

1. Lire

   Récupérer la page en ligne

   Claude lit le contenu actuel dans ReadMe par l’intermédiaire du connecteur.

2. Transformer

   Exécuter le skill

   La page est reconstruite avec le système rp-* ainsi que la voix et la structure éditoriales.

3. Écrire

   Mettre à jour dans ReadMe

   Le nouveau MDX revient sur la même page, qui conserve son slug et sa place dans la barre latérale.

4. Réviser

   Contrôle humain

   Je vérifie le rendu, corrige ce que le renderer interprète différemment et réintègre les enseignements dans le skill.

• Cohérence à grande échelle

  Chaque page reçoit le même bloc d’en-tête, le même ordre de sections et les mêmes composants, une cohérence difficile à maintenir manuellement sur des centaines de pages.

• Un skill qui progresse à chaque révision

  Chaque erreur de rendu relevée pendant la vérification devient une règle du skill, afin que le lot suivant ne la répète pas.

• Les rédacteurs gardent la main

  L’automatisation propose ; une personne approuve. Rien n’est publié sans vérification du rendu.

<div class="rp-page">
  <div class="rp-overview">Recurly Engage supports a variety of
    proven engagement patterns ...</div>
  <div class="rp-plan"><i class="fa-solid fa-key" aria-hidden="true"></i>
    Available to all customers on any Recurly Engage subscription plan</div>
  <div class="rp-toc">
    <a class="rp-toc-pill" href="#definition"><span class="rp-toc-num">1</span>Definition</a>
    <a class="rp-toc-pill" href="#key-benefits"><span class="rp-toc-num">2</span>Key benefits</a>
  </div>
</div>

### Prerequisites

<ul class="rp-list">
  <li>You must have <strong>Company</strong>, <strong>App Administrator</strong>,
  or <strong>App Member</strong> permissions in Recurly Engage.</li>
</ul>

• Aucune ligne vide dans un div

  Le parser MDX de ReadMe quitte le contexte HTML lorsqu’il rencontre une ligne vide et affiche la suite comme du code brut.

• Les placeholders {curly} deviennent ALL_CAPS

  Un seul {site_id} est évalué comme JSX et bloque toute la page.

• CodeTabs, pas Tabs, pour le code

  Des blocs consécutifs sans ligne vide sont rendus comme un seul bloc multilingue.

• Ne jamais inventer ni modifier le code

  Le code douteux reçoit un TODO pour révision par les développeurs, plutôt qu’une correction silencieuse.