draw-tech-svg

name

draw-tech-svg

description

Generate static or animated technical diagrams (flowchart, architecture, sequence, comparison, hierarchy) as hand-written SVG files with 4 switchable visual styles sharing a unified brand-blue palette — Notion Clean (default), Dark Terminal, Cloud Fabric, Hand Sketch — and optionally export a validated generated SVG as GIF. Use whenever the user wants to turn text or process descriptions into a visual. Trigger on "draw a diagram", "create a flowchart", "visualize this process", "画流程图", "画架构图", "画时序图", "画个图", "帮我画", "画个会动的图", "生成动态 SVG", "生成 GIF", "把这张图动起来", "手绘风格画图", "暗色风格画图", or any request for a technical diagram as static SVG, animated SVG, or GIF.

Draw-Tech-SVG

手写 SVG 技术图生成：统一品牌蓝主题色体系，4 种可切换风格，语义化配色与可校验的连线路由。

Workflow

用户描述 → 模式与风格 → DiagramSpec → 布局与路由 → 生成静态 SVG → validate → 视觉复查 → 交付静态图 → 按需转动画 SVG 或 GIF

Runtime path

运行脚本或读取参考文件前，把当前 SKILL.md 所在目录解析为 SKILL_ROOT。Claude Code 可使用 CLAUDE_SKILL_DIR；Codex 使用已加载 skill 元数据中的绝对目录。每个命令块独立设置变量：

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-loaded-skill}"

在 Codex 中运行命令前，用已加载 skill 的真实绝对目录替换占位路径。不要假定当前工作目录等于 skill 目录。

Step 1: 确定主张与图形模式

先读取 references/pattern-library.md，确定 main_claim、唯一主模式、可选次模式和阅读方向。再按主模式只读取一个详细分支：

主模式	读取
Linear Workflow / Feedback Loop / Branch Workflow / Parallel Fan-out	references/patterns-workflow.md
Sequence Diagram	references/patterns-sequence.md
Grouped Architecture / Layered Stack / Hub-and-Spoke	references/patterns-structure.md
Split Comparison / Venn / Callout Annotation	references/patterns-composition.md

完成标准：用一句话写清主张；主模式只有一个；阅读方向与该模式一致；对应分支文件已读取。

Step 2: 选择风格

#	Name	画布	Best For
1	Notion Clean（默认）	#ffffff 纯白	文档配图、README、评审材料
2	Dark Terminal	#111520 深灰蓝	GitHub README、暗色博客、代码向分享
3	Cloud Fabric	#f0f7ff 云蓝网格	部署拓扑、多区域、容灾、网络归属图
4	Hand Sketch	#fffdf7 纸白	白板草图、头脑风暴、轻松示意图

读取所选 references/style-N-*.md 获取全部视觉 token、节点模板、marker 定义和 SVG 骨架；同时读取 references/color-semantics.md 获取跨风格语义契约。

默认使用 Style 1。仅在用户明确给出风格词时切换：暗色/深色/黑底/终端风/dark → 2；云部署/部署拓扑/多区域/容灾/网络拓扑/deployment → 3；手绘/白板/草图/涂鸦/hand-drawn/sketch → 4。命中多个风格时使用用户最后一个明确要求；仍然含混时使用 Style 1。

完成标准：选定一个风格；该风格文件和 color-semantics.md 已读取。

Rule precedence

指令冲突时按此顺序处理：

1. 用户的显式内容与风格要求
2. references/color-semantics.md 和 references/geometry-contract.md 的冻结契约
3. 所选模式的结构规则与 references/connector-routing.md 的路由规则
4. 所选风格文件的视觉 token
5. 示例与通用默认值

风格只覆盖颜色、字体、圆角、箭头头形和装饰处理。语义含义、连接方向、节点外轮廓枚举和几何门禁保持稳定。

Step 3: 写出 DiagramSpec

写 SVG 前先输出文本计划：

DiagramSpec:
  main_claim: 一句话主张
  style: 1-notion-clean | 2-dark-terminal | 3-cloud-fabric | 4-hand-sketch
  pattern: 主模式
  secondary_pattern: 次模式或 none
  reading_direction: left-to-right | top-to-bottom | chronological
  title: 图表标题
  canvas_size: width x height

  nodes:
    - id: n1
      label: 短标签
      semantic_type: primary | secondary | tertiary | start | end | warning | decision | ai_llm | inactive | error |   
           
       [, ]
       [, ]
          

  
      
       
       
                 
                 
                 
               
       
               

  
      
       
           
       [, , , ]
       [, ]

Sequence Diagram 使用 participants、messages 和 frames 替代 nodes、connections 和 groups，字段定义取自 references/patterns-sequence.md。

DiagramSpec 和 SVG 文本跟随用户语言。完成标准：id 唯一；引用的节点、参与者和容器均存在；枚举值全部合法；每条连接或消息都有明确方向。

Step 4: 完成布局与路由

读取 references/geometry-contract.md，先放置画布、容器、节点或参与者，再预留标题、图例、跨容器连线和反馈回路的走廊。节点、容器和自然走廊锚点对齐基础网格；端口 slot、走廊 lane、跨桥和 Hand Sketch 笔迹属于派生坐标，按契约计算。

非时序图在画连接前读取 references/connector-routing.md。先分配每条边的端口 side 与 slot，再路由主流程和次要连接。Sequence Diagram 按 references/patterns-sequence.md 的生命线与消息规则布局。

完成标准：节点与容器互不压盖；边到无关节点保持安全距离；每条边已有唯一端口 slot 和完整路径；标题、标签、图例都有保留区域。

Step 5: 生成 SVG

使用所选风格文件的完整样式与 marker 定义，按以下层级写 SVG：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {width} {height}" width="{width}" height="{height}">
  <style><!-- 所选风格的完整 style block --></style>
  <defs><!-- 所选风格的 6 个 marker 和风格 defs --></defs>
  <!-- 背景 → 标题 → 容器/frames → 连线/lifelines/messages → 节点/participants → 标签/图例 -->
</svg>

viewBox 的宽高与数值型 width、height 一致。背景、字体、节点视觉、marker、连线视觉和容器样式全部取自所选风格文件。

SVG <text> 不自动换行。短标签直接写入；长标签使用多个 <tspan> 垂直排列，并同步增加节点高度。

默认源 SVG 必须是静态图，不写入 CSS animation、SMIL 或脚本。每条业务连接或时序消息添加 data-connection="true" 和从 0 开始递增的 data-motion-order；对应标签添加相同序号的 data-motion-for；图例中的示例箭头添加 data-motion="exclude"。这些元数据不改变静态渲染，只为按需动图转换提供稳定选择器。

完成标准：DiagramSpec 中的每个可视对象都已生成；绘制层级正确；语义角色和 marker 与冻结契约一致；SVG 在任意时刻都是完整静态图；业务连接的 motion 元数据完整且顺序唯一。

Step 6: 校验与视觉复查

先运行确定性校验：

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-loaded-skill}"
bash "$SKILL_ROOT/scripts/validate-svg.sh" <file>.svg

校验失败时按错误逐项修复并重跑；全部检查通过后才能继续。依赖检查只检测环境，不安装软件：

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-loaded-skill}"
bash "$SKILL_ROOT/scripts/check-deps.sh"

有渲染器时导出 PNG 并回读，检查节点、连接、标签、图例和画布边界：

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-loaded-skill}"
bash "$SKILL_ROOT/scripts/svg2png.sh" <file>.svg

PNG 使用 CairoSVG 兜底时，脚本检测可见文本中的中文字符，通过运行环境的字体发现机制选择覆盖完整的中文字体，并执行不同中文字形的 CairoSVG 像素探针。字体仅注入内存中的渲染副本。未找到覆盖字体或探针退化为同形方框时必须失败，禁止交付方框字产物。

发现视觉问题后进行最多两轮聚焦修正。两轮后仍有问题时报告具体未通过项，不宣称完成。无渲染器或运行环境不能回读图片时报告 visual_review: skipped。

Step 7: 按需转换动图

仅在用户明确要求 让这张图动起来、生成动态 SVG、生成 GIF 或同义表达时读取 references/motion.md。先完成并验证静态 SVG，再执行转换；不接受 PNG、JPEG 等栅格输入。未指定格式时输出动画 SVG；仅在明确要求 GIF 时选择 GIF：

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-loaded-skill}"
bash "$SKILL_ROOT/scripts/svg2motion.sh" <file>.svg
bash "$SKILL_ROOT/scripts/svg2motion.sh" <file>.svg --format gif

两种格式共享连接顺序、分段显隐、流动方向、末尾渐隐和无限循环规则。默认生成 <file>-animated.svg 与同名 .motion.json，使用 CSS keyframes，不含脚本或 SMIL。GIF 保持 960px 宽、5.75 秒、20fps、115 帧；包含中文时解析覆盖全部中文字符且通过 CairoSVG 字形探针的运行环境字体，并把实际选择记录到 motion report。两种转换都保持源 SVG 字节不变。

Step 8: 写盘与交付

完整 SVG 写入用户指定位置；未指定时写入当前工作目录。文件名使用小写连字符；非默认风格追加 -dark、-cloud 或 -sketch。仅在用户要求打开文件时调用系统打开命令。

交付时报告静态 SVG 路径、可选 PNG 路径、校验结果和 visual_review 状态。请求动图时另报动画 SVG 或 GIF 路径及 motion report 路径。

Quality checklist

• DiagramSpec 的引用、枚举和方向完整
• 已满足 geometry-contract.md 的布局 token 与完成条件
• 非时序图已满足 connector-routing.md 的端口、走廊、跨桥和进出方向规则
• 所选模式的结构、密度和阅读方向正确
• 12 个语义角色与 6 个 marker 保持冻结含义
• 连线类型达到两种时有图例
• 样式、字体和依赖全部内嵌
• 默认 SVG 不包含 CSS animation、SMIL 或脚本
• 业务连接带唯一 data-motion-order，连接标签带对应 data-motion-for，图例连接已排除
• 用户要求动图时从已验证静态 SVG 转换；未指定格式时输出动画 SVG，明确要求时输出 GIF
• 动画 SVG 使用 CSS keyframes，未写入脚本或 SMIL，源文件未修改
• 中文 PNG/GIF 已解析覆盖字体并记录实际选择；无字体时已阻断交付
• validate-svg.sh 全部通过
• 已报告 visual_review: passed | skipped | failed

Reference files

• references/pattern-library.md：每次生成前读取，用于模式选择和通用构图约束
• references/patterns-workflow.md：工作流、回路、分支、并行模式选中时读取
• references/patterns-sequence.md：时序图选中时读取
• references/patterns-structure.md：架构、层级、中心辐射模式选中时读取
• references/patterns-composition.md：对比、交集、注释模式选中时读取
• references/geometry-contract.md：每次生成前读取，是所有几何数值的单一事实源
• references/connector-routing.md：非时序图画连接前读取
• references/color-semantics.md：每次生成前读取，是语义枚举和含义的单一事实源
• references/style-1-notion-clean.md：默认风格；选择 Style 1 时读取
• references/style-2-dark-terminal.md：选择 Style 2 时读取
• references/style-3-cloud-fabric.md：选择 Style 3 时读取
• references/style-4-hand-sketch.md：选择 Style 4 时读取
• references/motion.md：仅在用户明确要求动画 SVG、GIF 或动图时读取