docs-diagrams

文档图表

参考文档中已发布的图表。它们都采用浅色网格背景、带边框和柔和阴影的面板、灰色骨架 UI、灰色箭头，以及一小组含义固定的强调色。本技能通过代码复现这种视觉语言。

文件

任务	阅读
颜色、尺寸、字体、各颜色的含义和形状结构	style-tokens.md
交付前检查渲染结果	review-checklist.md
基础图元：画布、面板、树形行、窗口、孔洞、徽章	scripts/lib.mjs
为每个图表模块生成 SVG + HTML	scripts/gen.mjs
以 2x 分辨率截图，生成浅色 + 深色 PNG	scripts/render.sh
根据图形内容测量渲染结果的边距	scripts/measure.py

工作流

1. 阅读 mdx

<Image> 块中包含文件名（srcLight="/docs/light/<name>.png"）、页面预留的 width 和 height，以及作为简要说明的 alt 文本。

图片前的段落通常会用文字说明颜色图例（例如“灰色表示静态输出，蓝色表示可在请求时渲染的内容”）。如果有这类说明，图表必须与之完全一致。如果没有，请根据 alt 文本中提到的状态（Suspense 回退内容、请求时内容），参照 style-tokens.md 中的“颜色含义”进行映射，并在交付时建议在 mdx 中添加图例说明。

只绘制简要说明中提到的内容。alt 文本和周围的段落决定要呈现哪些值、行和标签。对于简要说明中未明确的术语，请使用 alt 文本中的标签以及 docs/01-app/04-glossary.mdx。

2. 从文档中获取参考图

图片不在此仓库中；它们由文档 blob 存储提供。绘制前，先列出已有图片，并获取两三张主题相近的图片作为参考，同时查看浅色和深色版本：

grep -rhoE 'srcLight="[^"]+"' docs | sort -u
curl -sL -o ref.png "https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/light/nested-layouts.png"

使用完整的 srcLight 路径：大多数图片位于 /docs/ 下，部分位于 /learn/ 下。深色版本可将 light 替换为 dark。如果要绘制的页面已有图片，应优先参考这些图片。多看几张：它们的结构一致，因此应关注共通部分，而不是某张图片的独特细节。已发布文件的分辨率有 1x 和 2x 两种；这是历史遗留，不是目标。始终生成 2x 图片。

3. 编写图表模块

将 scripts/ 复制到仓库外的临时文件夹，并添加 diagrams/<name>.mjs：

export default {
  name: 'my-diagram', // must equal the mdx srcLight basename
  width: 1600, // what the mdx declares
  height: 700,
  draw(t, lib, { width, height }) {
    const k = width / 1600
    const s = []
    // compose lib primitives here, laid out from a few named constants
    return s.join('\n')
  },
}

lib.mjs 中包含文档图表所用的形状：

• 面板和行：panel、treePanel、urlPill、urlStack、codePanel。
• 箭头和说明文字：arrow、bracketArrow、bracketCaption、callout。
• 浏览器窗口：使用 browserWindow(t, x, y, w, h, url, body = '') 绘制边框，使用 pageLayout 绘制窗口内的页面，使用 postCard 和 commentRows 绘制内容，使用 skel.* 绘制单个占位元素。将 URL 和正文作为位置参数传入。
• 状态和对比：hole（尚未渲染）、card（已渲染或高亮显示）、grid（用于条形图的列和跨列设置）。
• 徽标和图例：badge、statusBadge、legendRow、swatchLegend。
• 文本：label、code、用于确定标签周围区块尺寸的 textWidth，以及 icons。

使用 pageLayout 构建窗口页面，而不是手动放置骨架占位元素。它包含让占位元素看起来像页面的间距，并会返回 regions.post 和 regions.comments，方便按常见方式拆分内容列。

当需求描述了多个时刻或阶段（例如之前和之后、Shell → Prefetch → Navigation）时，文档会将浏览器窗口排成一行，并在窗口之间用箭头连接；每个窗口都显示对应时刻的页面。某个时刻已渲染的内容，在之后的每个时刻都应保持渲染状态和相同样式。当需要对比各时刻的值或 API 时，应在窗口下方放置条形行，并在窗口间的间隙处拆分。grid 用于布局这些条形；其列标题放在窗口下方，同时也作为窗口说明文字（grid 中的注释说明了如何对齐两者）。如果窗口没有额外作用，则单独使用 grid。

使用具名常量布局图表区块，并将其置于画布中央。如果图表需要 lib 中没有的形状，请使用现有设计令牌，按相同风格将其添加到 lib.mjs，以便后续图表也能使用。切勿在形状内硬编码颜色或一次性的偏移值。

一个模块可以导出多个共用同一张图的图表组成的数组。没有默认导出的辅助模块会被跳过。

4. 渲染

在临时文件夹内运行 ./render.sh。它会运行 node gen.mjs，并使用无头 Chrome，以 --force-device-scale-factor=2 截取每个 <name>-<theme>.html 的屏幕截图。输出会保存到 light/<name>.png 和 dark/<name>.png，这正是 mdx 所需的文件名。迭代时可运行 node gen.mjs <name> 来重新生成单个图表。

脚本默认使用 macOS 上的 Google Chrome 路径。在 Linux、Windows 或 Chrome 安装在其他位置的设备上，请将 CHROME 设置为浏览器可执行文件的路径：

CHROME=/path/to/chrome ./render.sh

5. 检查

以原尺寸查看两张 PNG，并对照 review-checklist.md 及第 2 步的参考图。运行 python3 scripts/measure.py light/<name>.png 检查边距。在常量中修正后重新渲染。切勿交付未经查看的 PNG。

6. 交付

交付 PNG，并注明其像素尺寸以及对应的 mdx 路径。上传到 blob 存储是文档维护者手动完成的步骤，因此交付物是 PNG，而不是提交记录。检查 mdx 的 srcLight 基本文件名与 PNG 文件名是否一致，包括单数和复数形式。如果在 lib.mjs 中添加了基本图形，请将其提交回此技能；如果无法提交，则交付差异文件。

文档通常绘制的内容

已发布的示意图由几种基本形状组合而成。以下是常见类型，每种都附有可查看示例的页面。还有其他类型，也可能需要为新概念设计新的组合。

• 文件树 → URL：文件树面板（包含文件夹、文件、布局和路由图标；当前页面对应的行以粗体显示，并带有蓝点；省略的子项显示为灰色 ... 行），通过灰色箭头连接到 URL 标签（地球图标 + 路径；路径不可路由时填充灰色）；文件树旁的括号箭头表示哪个布局包裹哪些路由；以及等宽字体状态徽标（Routable、Not Routable）。请参阅布局和页面和项目结构。
• 文件 → 组件层级：文件列表通过箭头指向代码面板（栏中有 React 标志和标题，嵌套的 JSX 使用文档中的语法配色）。请参阅项目结构。
• 带骨架 UI 的浏览器窗口：窗口包含交通灯图标和 URL 标签，页面则由灰色骨架形状构成（头像、条形、侧边栏、图像占位符）。尚未渲染的内容以虚线空洞表示；已到达或当前重点关注的内容则以实色强调卡片表示，有时会浮在窗口外，并带有蓝色箭头。多个窗口通过箭头连接成一排，表示一个序列；下方的括号说明用于标注各组。请参阅获取数据和缓存。
• 带徽标的区域地图：窗口中的区域按类别描边并着色，每个区域都标有字母徽标；引线末端有注释，并配有图例。相同的徽标也用于标记树中的行和代码面板中的行，以便在不同视图间交叉参照。请参阅并行路由。
• 分区图：带虚线的彩色方框，角落处有标签，框内有等宽字体的路由标签；框之间以灰色箭头连接，箭头上标有等宽字体标签（SOFT NAV、HARD NAV）。请参阅多区域。

部分文档图片是产品截图（DevTools 面板、打包分析器、操作系统对话框）。请从实际 UI 中截取；此技能不会绘制这些内容。

约定

画布。 文档画布宽 1600 CSS px，页面会将其缩放到栏宽，因此令牌中的尺寸均以 1600 为准。绘制新图时，声明宽度为 1600，并让高度随内容调整。如果页面已声明较窄的宽度，请保持该宽度，并按 k = width / 1600 缩放元素尺寸，否则页面缩放后，图片会比相邻图片更大。grid、swatchLegend、arrow、pageLayout、postCard 和 commentRows 会接收或推导出 k，并按其缩放默认值；对于 skel.*、hole 和 card，请自行传入乘以 k 后的尺寸。

边距。 mdx 的 height 优先：让内容适应声明的框。顶部和底部必须相等，左侧和右侧也必须相等，误差不超过 4px；两组边距彼此不必相等。使用 scripts/measure.py 从墨迹边缘测量，而不是从你传入的坐标测量：使用 dominant-baseline="central" 绘制的文本，其视觉顶部约在 y 上方 0.35 × size 处；textWidth 是一种启发式估算，因此测量后可能需要微调几 px。

颜色。 在同一张图中，某种颜色在条形图和图例中只能表示一种含义；如果图例说明蓝色代表“请求时内容”，其他内容就不能用蓝色。在窗口中，渲染后的 UI 始终使用灰色骨架，无论条形图中灰色表示什么；这是文档的约定。窗口中的蓝色标记图片所关注的状态（未包含在静态输出中，或新近渲染的状态），与条形图中蓝色表示的状态相同。请参阅 style-tokens.md 中的“颜色含义”。

对齐。 边距相等、边缘对齐、文本在框内居中，箭头和分割线在整张图中垂直对齐。这是评审标准。

字体。 代码和路由使用 Geist Mono，其他内容使用 Inter。必须在本地安装 Geist Mono；回退字体为 ui-monospace。

相关技能

• $write-guide 和 $write-api-reference 用于生成引用这些图片的 mdx。
• $update-docs 用于查找代码更改会影响哪些文档页面。