本指南示例中的产品、数字和步骤均为示例数据。
交互式组件是在页面中使用
export const 声明、再通过 <RxJourney /> 这样的标签放置的 React 组件。将组件定义放在文件末尾,让内容可以从上到下顺畅阅读。请参阅 React 组件了解 MDX 环境支持的内容。
当流程有明确的先后顺序时,使用步骤器。每一步都说明由谁操作以及会发生什么。
当答案取决于读者的输入时,使用计算器。在结果中展示公式,方便读者核对。
当读者需要在几个相关数据系列之间切换时,使用带切换按钮的图表。每个图表只回答一个问题。
以下是计算器的完整源代码。套餐按钮、滑块和结果都读取状态,总额在渲染时计算。
usage.mdx
- 确保每种颜色在浅色和深色模式下都适用。文字和线条使用
currentColor或inherit,边框和填充使用rgba(127,127,127,.25)这样的半透明灰色,并只使用一种强调色。避免使用固定的黑色或白色。 - 为最外层元素添加
className="not-prose",避免页面的排版样式改变组件内部的间距。 - 将数据以常量形式写入组件。不要获取数据,也不要使用
localStorage、sessionStorage或 cookie,因为它们在编辑器中会失败或不起作用。 - 编写普通 JavaScript。TypeScript 类型注解会导致已发布站点上的整个页面出错。
- 将链接放在组件周围的正文中。组件内部的链接在编辑器中无法跳转。
- 为每个页面的组件使用一个简短的共享前缀,例如
Rx,避免与内置组件或彼此之间发生命名冲突。 - 为按钮和输入框提供可见标签或
aria-label,并使用aria-pressed或aria-current标记所选选项。 - 每个页面只放少量组件。编辑器一次最多运行 10 个组件,其余组件会暂停,直到滚动到可见区域。
- 要在多个页面中使用同一个组件,请将其移动到
/snippets/中的文件并导入。请参阅可复用片段。
record.mjs
- 每次操作后暂停约一秒,方便读者跟上变化。
- 以带延迟的方式输入文字,而不是瞬间填充字段。
- 视频时长控制在 30 秒以内。将较长的流程拆分为多个视频,并放在对应步骤旁边。
- 使用示例账户和数据,切勿使用生产数据。
claude -p "<task>" --output-format stream-json --verbose > session.jsonl。将消息和工具调用渲染为一个简单的终端风格 HTML 页面,然后用 Playwright 脚本录制该页面。回放会展示真实的命令以及智能体运行它们的顺序,而无需暴露实时终端。
将截图放在 <Frame> 中,并添加说明读者应关注什么的标题。裁剪到屏幕中重要的部分。
page.screenshot({ path: "images/settings-light.png" }),并在界面变化时重新运行。要生成深色版本,请使用 colorScheme: "dark" 创建上下文。请参阅图片和嵌入内容了解尺寸和缩放选项。
表格承载读者会反复查看的细节:状态、限制、价格以及各选项的支持情况。先展示表格,并让周围的正文保持简短。
对于主要由表格组成的页面,请在 frontmatter 中设置
mode: "wide",让表格占满整个宽度。请参阅页面模式。
只要提供模式和数据,编码智能体就能很好地编写组件和录制脚本。让智能体参考本指南,然后描述你希望读者理解的内容。
Widget
Video
- 使用
mint dev或在编辑器中打开页面,分别检查浅色和深色模式。 - 检查每个组件都能正常渲染,并能响应点击和键盘操作。
- 将浏览器缩小到手机宽度,检查没有内容溢出。
- 播放每个视频并打开每张图片。