diagram-design 图解导出实战从自包含 HTML 到 SVG / PNG 的完整流程与源码级原理【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design本文以 prompts/export-diagram.md 为核心骨架并以其权威细则 references/export.md 及仓库源码为佐证系统讲解 diagram-design 的导出链路。导读本篇技术指南围绕 diagram-design 项目一套面向 Claude Code、Codex、Pi 等 AI 编程助手的图解设计技能包的导出Export链路展开聚焦如何将生成的单文件、自包含 HTML 图解转换为可移植的.svg与.png用于 Figma、Slides、博客、社交卡片等场景。读完本文你将掌握diagram-design 的导出命令语法与全部命令行参数、SVG 与 PNG 两条导出路径的完整操作步骤、导出尺寸的计算规则与预设、以及项目源码层面如何保证导出产物可访问性、字体、静态帧的质量。整篇文章以 prompts/export-diagram.md 和 commands/export-diagram.md 为命令入口以 skills/diagram-design/references/export.md 为权威操作细则并辅以 skills/diagram-design/SKILL.md 与相关脚本作为实现证据。一、导出功能在 diagram-design 中的定位1.1 从生成到交付导出是链路末端的关键一环diagram-design 的完整工作流是选择图解类型 → 生成自包含 HTML → 通过 taste gate 自检 → 按需导出为 SVG / PNG。SKILL.md 的「输出」一节明确要求每个图解都必须产出单个自包含的.html文件——内嵌 CSS除 Google Fonts 外无外部资源、内联 SVG无外部图片、默认静态、仅在显式需要动画时使用极少量内联 JavaScript。导出的两种格式.svg、.png均由该 HTML 文件派生而来output-spec.md中明确写道Always generate the HTML first —svgandpngare producedfromit viaexport.md. Never hand-author an SVG file directly; the HTML is the source of truth and the only artifact the taste gate (SKILL.md §9) is written against.即先有 HTML、再导出 SVG/PNG绝不手写 SVG。HTML 是唯一的事实来源source of truth也是 SKILL.md §9 品味闸门唯一检查的产物。这意味着导出环节的设计哲学是一次生成、多格式复用。1.2 命令的三种入口Slash 命令、Prompt 与自然语言导出命令在仓库中以三个层次存在但其底层执行逻辑完全一致commands/export-diagram.md——插件级的 Slash 命令定义/diagram-design:export-diagram带有allowed-tools声明Read、Write、Edit、Bash、Glob直接委托给references/export.md。prompts/export-diagram.md——面向 Agent 的 Prompt 形式命令其 frontmatter 中声明了argument-hint参数提示与description。它要求 Agent 通过 SKILL.md 的路径定位技能目录将references/export.md视为唯一权威source of truth不要自行重新实现导出逻辑。自然语言触发——当用户以export this as PNG、save as SVG、rasterize it、convert to png and svg等表达提出需求时Agent 会加载export.md并执行同一套流程。值得注意的约束导出是手动操作绝不自动触发。export.md开篇即强调 Manual only — never run unprompted.仅手动——未经提示绝不运行。这意味着html生成后Agent 不会自动附带产出.svg/.png文件必须由用户显式提出导出请求。二、命令语法与参数详解2.1 完整参数签名根据 prompts/export-diagram.md 与 commands/export-diagram.md 的 frontmatter命令的完整签名如下/diagram-design:export-diagram html-file [--svg-only|--png-only] [--scaleN] [--outputpath]其中html-file是必选的位置参数$1其余均为可选参数$ARGUMENTS传入完整参数串。2.2 默认行为Defaults默认项值说明输出格式.svg.png两者例如diagram.html→diagram.svgdiagram.png输出到源文件旁PNG 渲染倍率device_scale_factor2默认 2 倍保证清晰度即不带任何标志时命令会同时产出 SVG 与 PNG 两种格式PNG 以 2 倍设备像素比渲染。2.3 可选标志Flags标志取值作用--svg-only无值只输出 SVG完全跳过 Playwright不启动浏览器--png-only无值只输出 PNG--scaleN1/2/3覆盖 PNG 的设备像素比device scale factor默认2--outputpath路径覆盖输出基础路径命令会自动追加格式扩展名两种格式同时产出时该路径同时作用于两者2.4 强制行为Required behavior两条命令规范共同规定了 6 条必须遵守的行为约束任何违反都意味着导出失败未提供源路径→ 询问用户要导出哪个.html文件绝不猜测。源文件是assets/index.html图库页面一个文件包含多个 SVG→ 拒绝导出询问用户具体要哪个图解文件对应export.md的 Edge cases 一节。源文件没有svg块→ 拒绝并告知用户什么都不写。请求 PNG 但未安装 Playwright→ 原样展示参考文档中的安装指引并停止不自动安装The user asked for one feature, not a system change.。--scale超出 {1,2,3}→ 拒绝合法值为 1、2、3。同时给出--svg-only和--png-only→ 拒绝二者互斥仅 prompts 版明确列出此项commands 版则将其并入参数合法性检查。导出完成后命令要求向用户汇报输出文件的路径与大小。关于第 4 条export.md给出的安装指引原文如下必须原样展示给用户且不得代为执行pip install playwright playwright install chromium然后让用户再次发起导出请求。这一约束体现了项目最小化系统变更的设计原则。三、两种导出格式的语义差异在进入操作步骤前必须先理解 SVG 与 PNG 在项目语义上的根本区别。根据export.md的 Scope 一节Both formats arediagram-only— just thesvgnode. Editorial wrappers (header, summary cards, footer in-fullvariants) are intentionally dropped.两种格式都只导出图解本身即svg节点编辑性外壳header、summary card、footer主要存在于-full变体会被有意剔除。导出的交付物就是图解本体适用于 Figma、幻灯片、社交卡片或博客配图。维度SVGPNG本质矢量文本节点 字体浏览器实际渲染的像素保留svg节点、矢量文本、title/desc与浏览器渲染完全一致的像素丢失离线工具中字体可能被替换矢量可编辑性适用Figma / Illustrator 二次编辑幻灯片、博客、社交卡片、打印背景透明无背景 rect 时透明背景omit_backgroundTrue此外SVG 导出有一个重要的可访问性保证SVG 保留源文件的title和desc。由于每个图解及其变体的 ID 都带前缀如loop-title、loop-dark-title多个导出的 SVG 可以安全地内联到同一页面而不会出现一个图形的可访问名称被另一个图形解析的问题。如果用户明确要求包含卡片在内的整页截图那是另一类请求——export.md规定回退到用户操作系统或浏览器的普通整页截图导出命令本身不做这件事。四、SVG 导出完整流程--svg-only或默认路径SVG 导出不需要浏览器其流程在 references/export.md 中有 5 个明确步骤读取源 HTML 文件。提取第一个svg ....../svg块——使用锚定在svg和/svg上的多行正则。绝大多数生成的图解只有一个 SVG若有多个第一个即图解本体图库文件除外见 Edge cases。使其成为独立standaloneSVG确保开标签带有xmlnshttp://www.w3.org/2000/svg缺失则补上确保存在viewBox技能模板总会自带一个若缺失则警告用户而非擅自猜测原样保留roleimg、aria-labelledby以及作为首个子元素的title/desc注入 Google Fontsimport以保证浏览器中文字渲染正确。关键细节必须将分隔符转义为amp;——独立.svg按严格 XML 解析裸会被视为实体引用起始符导致整个文件解析失败。不能直接从 HTML 的link href复制原始 URL那种带裸的形式只在 HTML 中合法。官方给出的注入样式如下defs styleimport url(https://fonts.googleapis.com/css2?familyInstrumentSerif:ital0;1amp;familyGeist:wght400;500;600amp;familyGeistMono:wght400;500;600amp;displayswap);/style /defs如果 SVG 已有defs块则将style合并进去而不是追加第二个defs。前置?xml version1.0 encodingUTF-8?\n保证文件是格式良好的 XML。写入basename.svg到源文件旁如example-architecture.html→example-architecture.svg若用户提供了显式输出路径则优先遵循。4.1 必须向用户说明的注意事项Caveat不支持在导入时抓取远程字体的工具离线 Illustrator、部分 Figma 导入路径、旧版 SVG 查看器会替换字体。SVG 在任何现代浏览器中渲染正确若要像素级可移植性建议改用 PNG 导出。4.2 为什么字体注入如此关键风格体系依赖从源码角度看diagram-design 的排版体系完全建立在 Google Fonts 之上。SKILL.md §5 的排版规范给出了 HTML 中的字体引用link hrefhttps://fonts.googleapis.com/css2?familyInstrumentSerif:ital0;1familyGeist:wght400;500;600familyGeistMono:wght400;500;600displayswap relstylesheetInstrument Serif—— 标题H1用衬线Geistsans—— 节点名称等人类可读标签Geist Mono—— 端口、URL、字段类型等技术子标签与箭头标签。而 skills/diagram-design/scripts/self_check.py 中对单文件安全的检查is_approved_google_fonts_stylesheet只放行https://fonts.googleapis.com/css2这一个远程样式表——这从质量闸门层面印证了字体是体系的一部分也是导出时必须在 SVG 中保留/注入字体引用的根本原因。若源 HTML 缺少head中的fonts.googleapis.comlinkexport.md判定该文件并非来自当前模板应修复源文件而不是在导出端绕开。五、PNG 导出完整流程需 Playwright5.1 渲染策略渲染原 HTML只截取 SVG 包围盒与提取 SVG 再渲染的直觉相反PNG 导出的官方流程是Renderthe original HTML(not the extracted SVG) and screenshot only thesvgelements bounding box.即渲染原始 HTML而非提取出的 SVG仅对svg元素的包围盒截图。这样做的好处是字体加载可靠源 HTML 已接好字体同时满足只导出图解的规则。三个关键约束透明背景——截图时使用omit_backgroundTruePNG 永远是透明背景可放到任意颜色幻灯片、文档上而不会出现白色光晕。动画源文件需静态化——对启用 motion 的 HTML须追加?motionstatic查询参数等待document.fonts.ready并在截图前断言 motion 根节点处于data-framestatic状态绝不可以在任意墙钟延迟后截图。字体就绪门控——截图前必须等待document.fonts.ready否则字体尚未加载完成截图会出现字体替换的偏差。5.2 Playwright 可用性检测开始任何操作前先验证 Playwright 是否安装python -c import playwright 2NUL || python -c import playwright若导入失败将下述指引原样展示给用户并停止不自动安装Playwright isnt installed. To enable PNG export, run:pip install playwright playwright install chromiumThen ask me to export again.5.3 官方栅格化脚本export.md给出了可写入临时文件并以python tmp.py src.html out.png运行的完整参考脚本from playwright.sync_api import sync_playwright import sys, pathlib src, out sys.argv[1], sys.argv[2] scale int(sys.argv[3]) if len(sys.argv) 3 else 2 with sync_playwright() as p: browser p.chromium.launch() page browser.new_page(device_scale_factorscale) page.goto(ffile://{pathlib.Path(src).resolve()}) page.wait_for_load_state(networkidle) page.locator(svg).first.screenshot(pathout, omit_backgroundTrue) browser.close()要点解读device_scale_factorscale控制输出分辨率默认 2file://协议 resolve()保证本地文件正确加载wait_for_load_state(networkidle)等待网络空闲字体加载的兜底page.locator(svg).first.screenshot(...)只截第一个 SVG 元素即图解本体omit_backgroundTrue产出透明背景。5.4 输出命名example-architecture.html→example-architecture.png写入源文件旁若用户提供显式路径则优先遵循。5.5 仓库中的同构实现canonical 截图管线值得指出的是仓库的截图管线与export.md的 PNG 流程是同一套技术scripts/render-canonical-screenshots.py 用 Playwright 以device_scale_factor2、viewport{width: 1440, height: 1000}打开每个 canonical 示例等待page.evaluate(() document.fonts.ready)后对page.locator(svg).first调用svg.screenshot(pathstr(output), omit_backgroundTrue)为 39 个图解类型渲染官方截图并记录 SHA-256 摘要到 docs/screenshots/manifest.json。这与export.md中渲染原 HTML 截取首个 SVG 透明背景 字体就绪门控的约定一一对应可以作为导出正确性的一种参照实现。相应的 scripts/verify-screenshot-freshness.py 会校验源文件与截图的摘要是否漂移。六、尺寸决策viewBox 与缩放系数6.1 导出只选乘数不决定尺寸export.md的 Sizing the export 一节给出核心公式The PNGs pixel dimensions are the SVGsviewBox×device_scale_factor. So the size decision was already made when the diagram was drawn — seeoutput-spec.md§2 for the presets. Export only picks the multiplier.PNG 的像素尺寸 SVG 的viewBox× 设备像素比。尺寸决策在绘图时就已定下由 output-spec.md §2 的预设决定导出环节只负责选择倍率。6.2 目的地 × 倍率速查表以一个 1280×720 的viewBox为例来自export.md目的地Scale结果尺寸1280×720 viewBoxDocs、README、wiki22560×1440幻灯片投影22560×1440打印 / PDF 讲义33840×2160内联缩略图、邮件11280×720对应到命令层--scale2适合文档与幻灯片--scale3适合打印/PDF/Retina hero--scale1适合紧凑资源。6.3 尺寸预设如何决定 viewBoxoutput-spec 对照若需要精确匹配某个尺寸预设可对照 output-spec.md §2 的预设表以下为部分关键行预设viewBox宽高比PNG 2用途doc-inline默认0 0 960 6008:51920×1200文章/README 正文宽度图解doc-wide0 0 1280 72016:92560×1440全宽文档、wiki 页slide-16x90 0 1280 72016:92560×1440幻灯片、投影slide-4x30 0 1024 7684:32048×1536旧版模板social-og0 0 1200 632~1.9:12400×1264链接预览卡片social-square0 0 1080 10801:12160×2160信息流帖/轮播print-a4-landscape0 0 1120 792~1.41:13 → 3360×2376A4 横向打印print-letter-landscape0 0 1056 816~1.29:13 → 3168×2448US Letter 横向打印fit由内容推导任意2矢量交付无固定画框6.4 命中精确像素尺寸计算而非猜测当用户需要精确尺寸如 OG 卡片恰为 1200×630、幻灯片图像 1920×1080时应计算缩放系数而不是猜——Playwright 接受小数倍率scale target_width / viewBox_width例如 960 宽的viewBox要 1200px 目标宽度则scale1.25。但有两条铁律绝不为命中小目标把倍率降到 1 以下——那会让文字变模糊soft-focus。应改用一个更小的预设重新绘制。绝不超过 4——超过 4 相当于把为更小画布设计的布局强行放大应改用slide-16x9或打印预设重绘。此外若目标宽高比与viewBox宽高比不匹配应告知用户并提供重绘为匹配预设的方案。给已完成的图解加 padding 或裁剪来适配画框不属于导出操作——那会破坏 40px 安全边距SKILL.md §6 / output-spec 的安全区约定。七、Edge cases边界情况与防御式处理export.md明确列出四类边界情况命令层也对应实现了防御逻辑源是assets/index.html图库单文件多 SVG→ 拒绝导出询问用户具体想要哪个图解文件不猜测。找不到svg块→ 源文件不是图解文件告知用户什么都不写。用户在意周边 HTML卡片/页头→ 告知用户本技能只导出图解本体建议改用浏览器整页截图或单独 PDF 打印。运行时字体缺失→ Playwright 会替换字体、截图效果异常。检查源 HTML 的head是否含fonts.googleapis.com的link缺失说明文件并非来自当前模板——修复源文件而不是在导出端绕开。这些边界情况在命令层prompts/export-diagram.md 第 3 条与 commands/export-diagram.md 第 2、3 条被直接引用为强制行为形成了命令 → 参考文档的双层防御。八、导出命令永远不做的事设计边界export.md最后以显式清单划定了命令的行为边界不修改源 HTML不添加导出按钮或script标签——静态图解保持无脚本已启用 motion 的源可保留其作用域控制器来自 animation.md但导出绝不注入另一个控制器不在生成 HTML 时自动附带.svg/.png——每次调用都是手动触发不通过foreignObject将 HTML 外壳卡片、页头嵌入 SVG——跨渲染器太脆弱。这些不做的事共同维护了自包含 HTML 的静态性与可移植性也解释了为什么导出的 SVG 必须走字体 import XML 转义而不是把整个页面塞进 SVG的路线。九、动画图解的导出正确性静态帧契约对启用了 motion 的图解导出并非简单截图而是遵循一套严格的最终静态帧契约。依据 animation.mdThe final-state capture contract is synchronous:?motionstatic,html contenteditable="false">【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考