docs-diagrams 是用于 Strands 文档站的图表设计技能，目标是产出清晰、编辑风格、符合 Strands 品牌规范的说明性图示。
用途
当某个文档页面需要配图，或需要为文档内容绘制示意图时使用该技能。图表以主题自适应的 SVG 形式呈现，并通过 <Diagram> 组件渲染到页面中。
主要能力
- 按页面正文绘制：图表需与所在段落的术语、阶段名称和顺序保持一致，并对照术语参考文件核对用词。
- 先规划后绘制：在写 SVG 之前，先向用户说明图表要传达的一句话核心信息、选用的图表类型及其理由、计划从原始素材中删减的内容，以及获得强调的一到两个焦点元素。
- 类型选择：支持循环、扇出、时序、流程图、状态机等常见结构，并说明类型与叙事目标的匹配原因。
- 克制表达：如果表格或段落能更好地完成任务，应建议不绘图。
- 规范的 SVG 编写：从参考模板出发，先在纸上布局，按文本宽度估算计算框宽并保持坐标落在 4px 网格；按“区域→连线→标签→节点”的绘制顺序写入文件，仅使用 class，不在 SVG 中写颜色或样式。
- 主题检查：通过截图脚本在明暗两种主题下查看渲染结果，检查标签是否存在（缺少字体时框体可能为空）、重叠、文字裁切、标签压线、连线交叉以及暗色模式下的可读性，并迭代直到通过参考中的检查清单。
- Markdown 孪生检查：确认图表位置在 Markdown 输出中显示为 > Diagram: <alt>。
使用方式
- 阅读图表将要插入的 .mdx 页面，理解上下文。
- 说明图表的叙事、类型、删减内容和焦点。
- 在 site/src/assets/diagrams/ 下创建 <concept-name>.svg，并从参考模板开始。
- 在页面中引入组件：
import Diagram from '@components/Diagram.astro'
<Diagram name="concept-name" alt="Full prose description of the diagram." />
导入语句放在 frontmatter 之后，与页面其他导入放在一起。 5. 启动本地开发服务器并运行截图脚本查看两种主题下的效果：
npm install && (cd site && npm ci) (cd site && npm run dev > /tmp/site-dev.log 2>&1 &) node .agents/skills/docs-diagrams/screenshot.mjs /docs/<page-path>/
脚本最多等待 90 秒开发服务器启动，也会捕获未激活语言标签页中的图表，并等待 Mermaid 渲染完成。若 Chromium 未安装，可运行 npx playwright install chromium；可用 PLAYWRIGHT_CHROMIUM_EXECUTABLE 指定浏览器二进制文件。 6. 打开脚本输出的每张 PNG 检查，并验证 Markdown 孪生输出：
curl -s http://localhost:4321/docs/<page-path>/index.md | grep -A1 'Diagram:'
- 向用户报告新增或替换的图表及其类型、删减内容及原因、截图路径，以及参考规则中不适用的条目（建议修改参考而非默默违反）。
适用场景
适用于为 Strands 文档页面补充结构化的说明性图示，尤其是需要与正文术语严格对齐、需要在明暗主题下都保持可读性的文档配图任务。
限制与注意事项
- 不得并行编辑同一文件，避免相互覆盖；应顺序编辑并重新读取。
- 不得硬编码十六进制颜色、字体或 style 属性；若缺少角色样式，应在 site/src/styles/diagrams.css 中添加类。
- 不得添加页面未描述的节点或组件。
- 不得通过缩小字号来适配内容，应删减内容或将图表拆分为两个。
- 截图检查不可省略：未在两种主题下查看渲染结果即视为未完成。