- Widgets interactivos escritos en la página como componentes de React.
- Videos del producto, o de una sesión de un agente, grabados con un script de navegador.
- Capturas de pantalla en marcos, con versiones clara y oscura.
- 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.
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.
Usa un stepper cuando un proceso tiene un orden claro. Cada paso indica quién actúa y qué ocurre.
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.
Usa un gráfico con un selector cuando los lectores alternan entre unas pocas series relacionadas. Limita cada gráfico a una sola pregunta.
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
- Haz que cada color funcione en modo claro y oscuro. Usa
currentColoroinheritpara el texto y las líneas, grises translúcidos comorgba(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,sessionStorageo 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 conaria-pressedoaria-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.
record.mjs
- 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.
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.
Pon las capturas en un <Frame> con un pie que indique qué mirar. Recorta la parte de la pantalla que importa.
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.
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.
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
- Abre la página con
mint devo 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.