- Interactive widgets written into the page as React components.
- Videos of the product, or of an agent session, recorded with a browser script.
- Screenshots in frames, with light and dark versions.
- Tables for status, limits, and comparisons.
The products, numbers, and steps in the examples in this guide are sample data.
Choose a building block
Interactive widgets
A widget is a React component declared in the page withexport const, then placed with a tag like <RxJourney />. Put the component definitions at the end of the file so the content reads top to bottom. See React components for what the MDX environment supports.
Click through a flow
Use a stepper when a process has a clear order. Each step names who acts and what happens.Try your own numbers
Use a calculator when the answer depends on the reader’s inputs. Show the formula in the result, so readers can check it.Show a trend
Use a chart with a toggle when readers switch between a few related series. Keep it to one question per chart.How the calculator works
This is the complete source of the calculator. The plan buttons, sliders, and result all read from state, and the total is computed during render.usage.mdx
Widget guidelines
- Make every color work in light and dark mode. Use
currentColororinheritfor text and lines, translucent grays likergba(127,127,127,.25)for borders and fills, and one accent color. Avoid fixed black or white. - Add
className="not-prose"to the outer element so the page’s typography styles don’t change spacing inside the widget. - Write data into the component as constants. Don’t fetch data or use
localStorage,sessionStorage, or cookies, because those fail or do nothing in the editor. - Write plain JavaScript. A TypeScript annotation breaks the whole page on your published site.
- Put links in the prose around a widget. Links inside a widget don’t navigate in the editor.
- Give each page’s components a short shared prefix, like
Rx, so their names don’t collide with built-in components or with each other. - Give buttons and inputs visible labels or an
aria-label, and mark the selected option witharia-pressedoraria-current. - Keep a page to a handful of widgets. The editor runs at most 10 widgets at a time and pauses the rest until they scroll into view.
- To use a widget on more than one page, move it to a file in
/snippets/and import it. See Reusable snippets.
Videos
Record a short video when readers need to see something move: a walkthrough of a UI, a deployment finishing, or an agent working through a task. Muted videos that loop work like animated screenshots. Keep self-hosted clips short and small, and host longer videos on a platform like YouTube. See Media for when to use video and how to keep file sizes down.Record the product with a script
A browser script gives you the same video every time, so you can record it again after the UI changes. This Playwright script records a WebM file while it clicks through a flow:record.mjs
- Pause for about a second after each action, so readers can follow the change.
- Type with a delay instead of filling fields instantly.
- Keep videos under 30 seconds. Split longer flows into several videos next to the steps they show.
- Use sample accounts and data, never production data.
Replay an agent session
To show what an agent did, record its session and play it back as a video. Claude Code and Codex can write the session as JSON lines, for exampleclaude -p "<task>" --output-format stream-json --verbose > session.jsonl. Render the messages and tool calls into a simple terminal-style HTML page, then record that page with the Playwright script. A replay shows the real commands and the order the agent ran them in, without exposing a live terminal.
Screenshots
Put screenshots in a<Frame> with a caption that says what to look at. Crop to the part of the screen that matters.
page.screenshot({ path: "images/settings-light.png" }), and run it again when the UI changes. For the dark version, create the context with colorScheme: "dark". See Images and embeds for sizing and zoom options.
Tables
Tables hold the details readers come back for: status, limits, prices, and support across options. Lead with the table and keep prose around it short.
For a page that is mostly tables, set
mode: "wide" in the frontmatter to give them the full width. See Page mode.
Build these pages with an agent
Coding agents write widgets and recording scripts well when you give them the pattern and the data. Point the agent at this guide, then describe what you want the reader to understand.Widget
Video
- Open the page with
mint devor in the editor, in light and dark mode. - Check that every widget renders and responds to clicks and to the keyboard.
- Narrow the browser to phone width and check that nothing overflows.
- Play each video and open each image.