| 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
指令冲突时按此顺序处理：
- 用户的显式内容与风格要求
references/color-semantics.md 和 references/geometry-contract.md 的冻结契约- 所选模式的结构规则与
references/connector-routing.md 的路由规则
- 所选风格文件的视觉 token
- 示例与通用默认值
风格只覆盖颜色、字体、圆角、箭头头形和装饰处理。语义含义、连接方向、节点外轮廓枚举和几何门禁保持稳定。
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>
<defs></defs>
</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
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 或动图时读取
