Saltar al contenido principal
Agrega páginas interactivas para que tus lectores recorran un flujo, usen widgets o vean tu producto en funcionamiento. Esta guía cubre cuatro elementos para esas páginas:
  1. Widgets interactivos escritos en la página como componentes de React.
  2. Videos del producto, o de una sesión de un agente, grabados con un script de navegador.
  3. Capturas de pantalla en marcos, con versiones clara y oscura.
  4. Tablas para estados, límites y comparaciones.
Los productos, las cifras y los pasos de los ejemplos de esta guía son datos de muestra.

Elige un elemento

Widgets interactivos

Un widget es un componente de React declarado en la página con export const y colocado luego con una etiqueta como <RxJourney />. Pon las definiciones de los componentes al final del archivo para que el contenido se lea de arriba abajo. Consulta Componentes de React para ver lo que admite el entorno MDX.

Recorre un flujo

Usa un stepper cuando un proceso tiene un orden claro. Cada paso indica quién actúa y qué ocurre.

Prueba tus propias cifras

Usa una calculadora cuando la respuesta depende de los datos del lector. Muestra la fórmula en el resultado para que los lectores puedan comprobarla.

Muestra una tendencia

Usa un gráfico con un selector cuando los lectores alternan entre unas pocas series relacionadas. Limita cada gráfico a una sola pregunta.

Cómo funciona la calculadora

Este es el código fuente completo de la calculadora. Los botones de plan, los controles deslizantes y el resultado leen del estado, y el total se calcula durante el renderizado.
usage.mdx

Pautas para widgets

  • Haz que cada color funcione en modo claro y oscuro. Usa currentColor o inherit para el texto y las líneas, grises translúcidos como rgba(127,127,127,.25) para bordes y rellenos, y un único color de acento. Evita el negro o el blanco fijos.
  • Agrega className="not-prose" al elemento externo para que los estilos tipográficos de la página no cambien el espaciado dentro del widget.
  • Escribe los datos en el componente como constantes. No obtengas datos ni uses localStorage, sessionStorage o cookies, porque fallan o no hacen nada en el editor.
  • Escribe JavaScript simple. Una anotación de TypeScript rompe toda la página en tu sitio publicado.
  • Pon los enlaces en la prosa alrededor del widget. Los enlaces dentro de un widget no navegan en el editor.
  • Da a los componentes de cada página un prefijo corto compartido, como Rx, para que sus nombres no choquen con los componentes integrados ni entre sí.
  • Da a los botones y campos etiquetas visibles o un aria-label, y marca la opción seleccionada con aria-pressed o aria-current.
  • Limita cada página a unos pocos widgets. El editor ejecuta como máximo 10 widgets a la vez y pausa el resto hasta que aparecen al desplazarse.
  • Para usar un widget en más de una página, muévelo a un archivo en /snippets/ e impórtalo. Consulta Fragmentos reutilizables.

Videos

Graba un video corto cuando los lectores necesitan ver algo en movimiento: un recorrido por una interfaz, un despliegue que termina o un agente trabajando en una tarea. Los videos silenciados que se repiten funcionan como capturas animadas. Mantén los clips autoalojados cortos y ligeros, y aloja los videos más largos en una plataforma como YouTube. Consulta Medios para saber cuándo usar video y cómo reducir el tamaño de los archivos.

Graba el producto con un script

Un script de navegador te da el mismo video cada vez, así que puedes volver a grabarlo cuando cambie la interfaz. Este script de Playwright graba un archivo WebM mientras recorre un flujo:
record.mjs
Consejos para grabaciones legibles:
  • Haz una pausa de aproximadamente un segundo después de cada acción para que los lectores puedan seguir el cambio.
  • Escribe con retraso en lugar de rellenar los campos al instante.
  • Mantén los videos por debajo de 30 segundos. Divide los flujos más largos en varios videos junto a los pasos que muestran.
  • Usa cuentas y datos de muestra, nunca datos de producción.

Reproduce una sesión de un agente

Para mostrar lo que hizo un agente, graba su sesión y reprodúcela como video. Claude Code y Codex pueden escribir la sesión como líneas JSON, por ejemplo claude -p "<task>" --output-format stream-json --verbose > session.jsonl. Renderiza los mensajes y las llamadas a herramientas en una página HTML sencilla con estilo de terminal y graba esa página con el script de Playwright. Una reproducción muestra los comandos reales y el orden en que el agente los ejecutó, sin exponer una terminal en vivo.

Capturas de pantalla

Pon las capturas en un <Frame> con un pie que indique qué mirar. Recorta la parte de la pantalla que importa.
Para mantener las capturas actualizadas, tómalas con un script. Usa la misma configuración de Playwright que el script de video, llama a page.screenshot({ path: "images/settings-light.png" }) y vuelve a ejecutarlo cuando cambie la interfaz. Para la versión oscura, crea el contexto con colorScheme: "dark". Consulta Imágenes e insertos para ver las opciones de tamaño y zoom.

Tablas

Las tablas contienen los detalles a los que los lectores vuelven: estados, límites, precios y compatibilidad entre opciones. Empieza con la tabla y mantén breve la prosa a su alrededor. Para una página compuesta principalmente por tablas, establece mode: "wide" en el frontmatter para darles todo el ancho. Consulta Modo de página.

Crea estas páginas con un agente

Los agentes de programación escriben bien widgets y scripts de grabación cuando les das el patrón y los datos. Indica al agente esta guía y luego describe lo que quieres que entienda el lector.
Widget
Video
Antes de publicar:
  • Abre la página con mint dev o en el editor, en modo claro y oscuro.
  • Comprueba que cada widget se renderiza y responde a los clics y al teclado.
  • Reduce el navegador al ancho de un teléfono y comprueba que nada se desborda.
  • Reproduce cada video y abre cada imagen.