diagram-design 图表导出实战从 HTML 到 PNG / SVG 的完整管线与尺寸控制【免费下载链接】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-designdiagram-design 仓库提供了一套从生成到交付的完整图表工作流先产出带内联 SVG 与 CSS 的自包含 HTML再按需导出为可移植的.svg与.png。本篇技术指南围绕 skills/diagram-design/references/export.md 展开完整讲解该导出参考文档中规定的 SVG/PNG 导出流程、像素尺寸控制策略、边界情况处理与永远不做的约束清单并结合仓库中的命令封装commands/export-diagram.md、Playwright 渲染脚本scripts/render-canonical-screenshots.py与产物清单docs/screenshots/manifest.json做源码级佐证。读完后你将能够手动把任意一张生成好的图表 HTML 稳定地变成可用于 Figma、幻灯片、社交卡片或博客配图的 PNG / SVG并精确控制输出像素尺寸。导出是什么交付物是图表本身不是整页export.md对导出的范围做了严格界定两种格式都只导出svg节点本身diagram-only。生成 HTML 时附带在-full变体里的编辑部包装editorial wrapper——页头、摘要卡片、页脚——会被有意丢弃。原因是导出交付物的定位就是图表本身适合直接放进 Figma、幻灯片、社交卡片或博客配图。这里有两个容易被忽略的细节SVG 导出会保留图表的title与desc连同它们带前缀的 ID。export.md明确指出正是每个图表、每个变体各有前缀 ID例如architecture-title/architecture-desc见 skills/diagram-design/assets/example-architecture.html 的真实写法才让多个导出的 SVG 可以安全内联到同一页面而不至于一个图表的可访问名称解析到另一个图表。如果用户要的是包含卡片的整页截图那是另一类请求——应回退到用户操作系统或浏览器自带的整页截图功能而不是改导出流程去迁就。触发方式斜杠命令与自然语言双入口export.md的触发条件有两类且两个入口走的是同一套流程斜杠命令用户调用/diagram-design:export-diagram html-file。该命令在仓库根目录的 commands/export-diagram.md 中定义export.md称其为薄包装thin wrapper——它不重新实现逻辑而是把 skills/diagram-design/references/export.md 当作唯一事实来源source of truth。自然语言用户用自然语言表达导出、保存、栅格化、转换或下载.svg/.png图表的意图典型措辞包括 export this as PNG、save as SVG、give me a PNG of that diagram、rasterize it、convert to png and svg。命令层的参数约定在 commands/export-diagram.md 中定义得很完整参数含义默认值 / 约束html-file要导出的源文件必填缺省时询问用户不得猜测--svg-only只产出 SVG跳过 Playwright完全不依赖浏览器--png-only只产出 PNG与--svg-only互斥同时给出则拒绝--scaleN覆盖 PNG 设备缩放因子仅接受 1、2、3默认 2范围外直接拒绝--outputpath覆盖输出基础路径自动追加格式扩展名同时产出两种格式时对两者均生效prompts/export-diagram.md 还额外要求PNG 请求但 Playwright 未安装时原样展示参考文档中的安装指引并停止产出后必须把输出文件的路径和大小回报给用户。SVG 导出流程五步把svg变成严格 XMLexport.md规定的 SVG 导出是纯文本操作不依赖浏览器共五步读取源 HTML 文件。提取第一个svg ....../svg块。用锚定在svg与/svg上的多行正则完成。绝大多数生成的图表只有一个 SVG若有多个第一个就是图表本体画廊文件assets/index.html是例外见下文边界情况。使其成为独立standaloneSVG确保开标签带xmlnshttp://www.w3.org/2000/svg缺失则补上确保存在viewBox技能模板总是自带缺失时警告用户而不是猜测原样保留roleimg、aria-labelledby以及作为第一个子节点的title/desc注入 Google Fonts 的import让 SVG 在浏览器中按正确排版渲染。这里有一个关键陷阱独立.svg按严格 XML 解析裸会被当作实体引用起始符导致整文件解析失败因此必须把 URL 中的转义为amp;不能照抄 HTMLlink 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保证文件是良构well-formedXML。写到源文件旁的同名.svg例如example-architecture.html→example-architecture.svg。若用户给了显式输出路径则尊重该路径。需要向用户提示的注意点不拉取远程字体的工具离线 Illustrator、部分 Figma 导入路径、旧版 SVG 查看器在导入时会替换排版。SVG 在任何现代浏览器中渲染都是正确的若要像素级可移植建议走 PNG 导出。PNG 导出流程渲染 HTML、只截 SVG 包围盒与直觉相反PNG 导出不是渲染提取出的 SVG而是渲染原始 HTML、只对svg元素的包围盒截图。export.md给出的理由是这样字体加载更可靠源 HTML 里已经接好字体同时满足只出图表的规则。PNG 的硬性要求永远透明背景omit_backgroundTrue这样放到任何颜色的幻灯片或文档上都不会出现白色色块。对支持动效的 HTML先追加?motionstatic等待document.fonts.ready并断言动效根节点处于data-framestatic状态后再截图绝不按任意墙钟延迟wall-clock delay抓图。这与 skills/diagram-design/references/animation.md 中最终状态捕获契约是同步的约定一致——?motionstatic会暴露全部语义节点、隐藏控件与装饰层且同一 URL、视口、字体、缩放因子下的两次捕获必须像素一致。前置检测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.栅格化脚本将以下片段写入临时文件并以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_factor2保证清晰输出第三个 CLI 参数传1紧凑素材或3印刷 / retina 大图覆盖。page.locator(svg).first.screenshot(...)即只截第一个 SVG 包围盒 透明背景的实现。仓库中 scripts/render-canonical-screenshots.py 是同一管线的规模化版本它用 1440×1000 视口、device_scale_factor2打开每个规范示例等document.fonts.ready后对svg首元素做omit_backgroundTrue截图并把渲染器参数固化写进 docs/screenshots/manifest.jsonengine: playwright-chromium、scale: 2.0、capture: first-svg、font_gate: document.fonts.ready。而 scripts/verify-screenshot-freshness.py 则校验 manifest 中的渲染器参数必须与此完全一致——任何偏离都会报 screenshot manifest must use the canonical 1440x1000, 2x SVG renderer——可见首 SVG 2x 字体就绪后再截就是本仓库的权威捕获约定与export.md的 PNG 流程完全同构。输出命名example-architecture.html→example-architecture.png写在源文件旁同样尊重用户显式提供的路径。尺寸控制像素 viewBox × 缩放因子PNG 的像素尺寸等于 SVGviewBox×device_scale_factor。因此尺寸决策早在画图时就定下了——skills/diagram-design/references/output-spec.md 的 §2 规定了全部预设如doc-wide/slide-16x9的 viewBox 是0 0 1280 720doc-inline是0 0 960 600social-og是0 0 1200 632每个值都按 4 整除以贴合 4px 网格导出只负责选倍数目的地缩放1280×720 viewBox 的结果Docs、README、wiki22560×1440幻灯片投影22560×1440印刷 / PDF 讲义33840×2160内联缩略图、邮件11280×720命中精确像素尺寸当用户需要精确尺寸如 OG 卡片恰好 1200×630、幻灯片图 1920×1080时应计算缩放因子而不是靠猜——Playwright 接受小数值scale target_width / viewBox_width960 宽的 viewBox 配 1200px 目标就是scale1.25。有两条硬性规则为命中小目标绝不低于 1 缩放——那会让字体变糊应改用更小的预设重画。绝不超过 4——超过 4 意味着在放大一个为更小画布设计的布局应改用slide-16x9或印刷预设重画。若目标宽高比与viewBox宽高比不一致要明说并提议按匹配的预设重画。把画完的图裁剪或加内边距去硬塞进一个画框不是导出操作——那会破坏 40px 安全边距。边界情况什么该拒绝什么该提示export.md用一整节列出必须处理的边界情况核心原则是宁可拒绝不要瞎猜源是assets/index.html画廊单文件多 SVG拒绝导出问用户具体要哪个图表文件。找不到svg块源不是图表文件告诉用户什么都不写。用户需要周围的 HTML卡片、页头入图告知本技能只导出图表建议用浏览器整页截图或单独打印 PDF。运行时缺字体Playwright 会替换字体、截图走样。应检查源 HTML 的head里是否有fonts.googleapis.com的link标签没有说明文件不是当前模板产物——修源头而不是在导出侧打补丁。命令层在 commands/export-diagram.md 中把其中四条固化为强制行为无源路径 → 询问源为assets/index.html→ 拒绝并询问具体文件源无svg→ 拒绝且不产出任何东西PNG 请求但未装 Playwright → 原样展示安装指引并停止、不自动安装--scale超出 {1,2,3} → 拒绝。导出命令永远不会做的事export.md以永不never清单收尾这组约束保证了导出是纯旁路操作绝不污染源产物不修改源 HTML。不添加导出按钮或script标签。静态图表始终无脚本已启用动效的源可以保留 skills/diagram-design/references/animation.md 中规定的作用域控制器但导出绝不注入第二个控制器。不随 HTML 生成自动产出.svg/.png——每次调用都是手动的。不通过foreignObject把 HTML 包装卡片、页头嵌进 SVG——跨渲染器太脆弱。这与 skills/diagram-design/SKILL.md §12 的导出声明一致导出是 manual 操作生成图表时绝不擅自产出导出文件skills/diagram-design/references/output-spec.md 也强调先产出 HTMLsvg与png都经由 skills/diagram-design/references/export.md 从它派生绝不手写 SVG 文件——HTML 是唯一事实来源也是品味门禁SKILL.md §9唯一面向的产物。实战建议小结把整套导出心智模型浓缩成几条可执行准则手动触发双向入口斜杠命令export-diagram html-file与自然语言措辞都汇入同一条参考流程按 commands/export-diagram.md 的参数约定控制--svg-only/--png-only/--scale/--output。SVG 走纯文本管线提取首个svg→ 补xmlns/ 保viewBox→ 合并字体import并转义→ 加 XML 声明 → 同名输出。PNG 走浏览器管线渲染原 HTML、截首 SVG 包围盒、omit_backgroundTrue动效源先?motionstatic并断言data-framestaticPlaywright 缺失时只展示安装指引、绝不自动装。尺寸在画图时定导出只选倍数像素 viewBox× scalescale 限定 1–4非整数倍数用于精确命中目标尺寸宽高比不匹配就重画而不是裁剪。边界情况一律先问画廊文件、无 SVG 源、要整页内容、缺字体——分别对应拒绝、告知、回退、修源头四种处理。【免费下载链接】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），仅供参考