Sistema de diseño para la documentación de Recurly

1. Resumen rp-overview

   Entre dos y cuatro frases sobre el contenido de la página.

2. Etiqueta de plan rp-plan

   Quién puede usar la función, con una redacción fija por plan para que la disponibilidad se exprese igual en todas partes.

3. Callout rp-callout

   Cuatro variantes (nota, consejo, importante y advertencia), cada una con icono y color propios.

4. Enlaces de sección rp-toc

   Enlaces numerados a cada sección principal, generados a partir de los encabezados.

5. Lista de requisitos rp-list

   Bajo un encabezado Prerequisites o Limitations.

6. Definición rp-definition

   Una explicación en lenguaje claro de qué es y para qué existe, distinta del resumen.

7. Beneficios clave rp-benefits

   Tres o cinco elementos se ajustan automáticamente; si hay cuatro, pasan a una cuadrícula 2 × 2.

Los lectores encuentran el mismo ritmo en cada página: qué es, quién puede usarlo, cómo saltar a una sección y, después, los detalles. Los escritores técnicos cuentan con patrones reutilizables para cada parte de la guía. Los mismos tokens también dan estilo a la navegación, las pestañas de código y el API playground de ReadMe.

El portal global dirige a los lectores a la documentación de cada producto desde un solo bloque HTML con estilos propios y acotados. Cada inicio de producto usa el mismo vocabulario visual, adaptado a la forma en que sus lectores navegan.

• Tarjeta destacada para lanzamientos

  Un espacio de ancho completo para el producto más reciente: columna de contenido, panel con el logo y una etiqueta “New” cuyo pulso se desactiva con prefers-reduced-motion.

• Cuadrícula de productos 2 × 2

  Tarjetas uniformes con franja visual, etiqueta, título, descripción y fila de CTA. Al pasar el cursor, la tarjeta se eleva, el borde cambia de tono y la flecha avanza.

• Diseño adaptable desde el origen

  Breakpoints en 768, 480 y 375 px. La tarjeta destacada se apila, la cuadrícula pasa a una columna y el tamaño tipográfico baja por etapas.

• Defensas frente a la plataforma

  Protección contra desbordamientos, min-width: 0 en elementos flex y resets explícitos para impedir que el tema de ReadMe filtre subrayados o anchos al diseño.

• Búsqueda nativa tras una interfaz propia

  La barra de búsqueda del hero abre la búsqueda nativa de ReadMe. El acceso conserva la marca sin reemplazar el comportamiento de la plataforma.

• Un vocabulario para cada inicio de producto

  Cada portal reutiliza el mismo bloque de eyebrow, título y descripción, con navegación rápida y tarjetas orientadas a las tareas propias de sus lectores.

ReadMe renderiza con React y cambia las páginas del lado del cliente; por eso, un script que corre una sola vez deja de funcionar al siguiente clic. Los módulos se vuelven a enlazar tras cada cambio de página y evitan duplicar handlers cuando se inicializan otra vez.

// 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));

• Reemplazo de la navegación del changelog

  Apunta la pestaña Changelog de cada portal a una página personalizada y mantiene correcto el estado activo en cualquier ruta: navegación SPA, recargas, atrás/adelante y menú móvil.

• Etiqueta “Link copied” en encabezados

  Un clic en cualquier encabezado copia su enlace profundo. Una etiqueta sube y se desvanece —con doble requestAnimationFrame para asegurar la transición— y se enlaza de nuevo después de cada cambio de página.

• Carrusel en bucle

  Usa dos clones a cada lado, un estado de tarjeta activa, soporte para teclas de flecha, posicionamiento que responde al tamaño y reinicialización tras navegar.

• Búsqueda del hero y zoom de imágenes

  La búsqueda del hero abre la búsqueda nativa de ReadMe mediante sondeos acotados hasta que aparece el elemento. Un zoom ligero sigue el cursor en capturas grandes.

• Solo hooks estables

  Apunta a las clases rm- y etiquetas ARIA de ReadMe, nunca a nombres con hash de módulos CSS que cambian en cada despliegue.

• Idempotencia desde el diseño

  Una clave global con destroy() desmonta la instancia anterior si el script se carga dos veces.

• Respeto por la intención del usuario

  Los clics con Cmd/Ctrl/Shift y el botón central mantienen el comportamiento nativo, con la URL corregida ya en su lugar.

Conecté Claude a ReadMe para leer, reestructurar y actualizar páginas existentes por lotes. El ciclo conservó el slug y la posición de cada página en la barra lateral; revisé el resultado renderizado e incorporé las correcciones al skill.

1. Leer

   Traer la página publicada

   Claude lee el contenido actual desde ReadMe a través del conector.

2. Transformar

   Ejecutar el skill

   La página se reconstruye con el sistema rp-* y la voz y estructura editoriales.

3. Escribir

   Actualizar en ReadMe

   El nuevo MDX vuelve a la misma página y conserva su slug y su lugar en la barra lateral.

4. Revisar

   Control humano

   Reviso la página renderizada, corrijo lo que el renderer interpreta distinto y llevo lo aprendido de vuelta al skill.

• Consistencia a escala

  Cada página recibe el mismo bloque de encabezado, orden de secciones y componentes, algo difícil de sostener a mano en cientos de páginas.

• Un skill que mejora con cada revisión

  Cada error del renderer detectado en la revisión se convirtió en una regla del skill para que el siguiente lote no lo repitiera.

• Los escritores técnicos conservan el control

  La automatización propone; una persona aprueba. Nada se publica sin revisar el resultado renderizado.

<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>

• Sin líneas en blanco dentro de un div

  El parser de MDX de ReadMe sale del contexto HTML cuando encuentra una línea en blanco y muestra el resto como código sin procesar.

• Los placeholders {curly} pasan a ALL_CAPS

  Un solo {site_id} se evalúa como JSX y bloquea toda la página.

• CodeTabs, no Tabs, para código

  Los bloques consecutivos sin una línea en blanco se renderizan como un único bloque multilenguaje.

• Nunca inventar ni alterar código

  El código sospechoso recibe un TODO para revisión del equipo de desarrollo, no una corrección silenciosa.