---
name: fireworks-tech-graph
description: >-
  Create precise SVG technical diagrams, export PNG or offline HTML, and animate
  supported semantic SVGs to GIF. Use for architecture, UML, agent, cloud or
  workflow diagrams; not photos, raster art or statistical charts.
---

# Fireworks Tech Graph

One portable Agent Skill for Codex and Claude Code. SVG is the canonical artifact;
PNG, offline HTML and supported GIF motion are output routes. Preserve requested
labels, topology and meaning; a successful command is not a visual quality verdict.

## Locate and select

Resolve the directory containing this file as `SKILL_ROOT`. Use
`${CLAUDE_SKILL_DIR}` in Claude Code or the absolute directory in Codex's loaded
skill metadata. Do not assume cwd or a previous shell variable persists.

Use the installed version for the task. Run `version` for source/version questions
and `doctor` when diagnosing a missing renderer, font or dependency; do not make
installation, updates or a complete test suite prerequisites for every diagram.

```bash
SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
python3 "$SKILL_ROOT/scripts/fireworks.py" version
```

- Honor the user's diagram type, content and style; choose sensible reversible
  details from the brief. Ask only for a material missing engineering fact or
  a choice the user explicitly reserved. A request to draw includes local rendering.
- Styles 1–7 and 9–12 have JSON generators. Style 8 (Dark Luxury) remains
  AI-authored SVG: use its style reference, then the same validation/export gates.
- Default to Style 1 Flat Icon when no user/workspace preference applies. Load the
  actual matching file from [the style matrix](references/style-diagram-matrix.md).
  Read other styles only for a requested comparison.
- Styles 9–12 default to C4, cloud, event and observability semantic contracts.
  Validate facts before layout; do not invent responsibilities, protocols or metrics.
- Adapt an existing valid SVG directly when appropriate. JSON generation is not
  required for every edit. Use [diagram/layout guidance](references/diagram-layout-reference.md)
  and [icons](references/icons.md) only for the relevant type or symbols.

## Generate and check

Reuse the user's current brief and artifact; an extra planning document is optional.

**Work layout-first, in two stages (2026-10-05, cuts render rework).** For any
non-trivial layout: (1) draft the pure geometry first — node x/y, port pairs,
which edges become straight by a shared axis, where each label will sit — and
confirm it (self-check or user) before rendering; (2) only then render, check and
screenshot. A bend or label conflict caught on paper costs a fraction of a
render+PNG cycle. Before drawing, load the
[renderer behavior playbook](references/renderer-behavior-playbook.md): it records
the empirically-confirmed port-anchor, edge-label and swimlane rules (and the
30-second pre-render checklist) that otherwise cost rework every diagram.

For JSON work, select `text_policy: "strict"` when all labels must be visible exactly.
The compatible `report` default preserves full labels in SVG metadata and reports
any visible truncation. Resolve that warning before claiming complete exact text.
For polished work apply the [composition contract](references/composition-quality-contract.md).

```bash
SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
python3 "$SKILL_ROOT/scripts/fireworks.py" validate architecture input.json
python3 "$SKILL_ROOT/scripts/fireworks.py" render architecture input.json diagram.svg --report layout.json
python3 "$SKILL_ROOT/scripts/fireworks.py" check diagram.svg
python3 "$SKILL_ROOT/scripts/fireworks.py" export-png diagram.svg diagram.png --width 1920
```

`check` validates SVG identity, marker references, generic collisions, semantic
geometry and composition. Inspect the report's typography and palette scope;
heuristic text widths do not replace inspecting the actual rendered font.
Use [visual quality guidance](references/visual-quality.md) for readability and
style-specific refinements. Keep one semantic connector per business edge.

## Additional outputs

- **PNG:** prefer `export-png`, which reads root canvas dimensions, limits output
  size, writes atomically and reads the PNG dimensions back. Alternate renderer
  details are in [PNG export](references/png-export.md).
- **HTML:** `fireworks.py export-html diagram.svg diagram.html`. One sanitized
  offline file provides pan/zoom, source copy and static image downloads.
- **GIF:** “Generate a GIF”, “Animate this diagram”, “生成 GIF”, “制作 GIF” and
  “让这张图动起来” select the existing semantic SVG's motion route. Styles 1–12 are enabled
  for the documented scene contracts; arbitrary same-style topologies are not
  promised. Load [motion effects](references/motion-effects.md) and run
  `fireworks.py animate diagram.svg diagram.gif`. Default is 960px, 20fps, 5.75s
  with the `+2s-settled-flow` preset and a `.motion.json` report. Historical
  `user-approved` fields describe maintainer-reviewed presets, not authorization
  from the current user to publish, spend or send data.

## Verify the requested outcome

Inspect the final PNG at intended reading size when image viewing is available:
check text completeness, contrast, font substitution, hierarchy, spacing, clipping,
arrow direction, crossings and labels. Preserve style palette and material while
fixing defects. Reuse an unchanged reviewed render; do not keep adding tests or
polish after acceptance passes. If viewing is unavailable, explicitly mark the
visual check skipped and do not claim visual correctness.

After a failed check, use its element IDs and geometry to make a focused repair;
change the approach after two unchanged failures. Widen/split an overfull diagram
instead of hiding required copy or endlessly shrinking type. Do not silently
weaken semantic or composition constraints to obtain a pass.

**Layout principle (2026-10-05 user mandate, permanent): 画布可以更长更高，线条尽量用直线.**
Prefer a taller/wider canvas over bent or crowded connectors. Before accepting a
bend, first try lengthening vertically (+200~600px), widening (+200~400px), or
nudging node coordinates so connected ports share an axis and the router emits a
straight line (`data-bends="0"`). For header + row-cell "table" nodes, port choice
decides straightness: horizontal edges attach to the header's `left`/`right` port
(anchored at header center = `top+18`), so align the two headers' tops; vertical
edges attach to the **last row's** `bottom` port or the **header's** `top` port —
a header's `bottom` port has its own rows beneath it and forces a 3-bend detour
around the side. Never mask a bend by hiding a label or downgrading
`quality_profile`. See [layout best practices](references/svg-layout-best-practices.md).

Complete every requested local output and its applicable checks, then report file
paths, dimensions, visual review and residual limitations. A first SVG does not
complete a requested PNG/GIF/HTML package. Publication or remote delivery requires
its own scope-matching authorization; existing authorization is not requested twice.

## 画图工具组合策略（本机约定，2026-09-28 用户拍板）

按图种选引擎，不要用本 skill 硬画一切：

| 图种 | 首选工具 | 理由 |
|---|---|---|
| 业务流程图 / 泳道图 / 架构图 / 字段级 ER | **fireworks-tech-graph（本 skill）** | 几何校验零交叉、中文零截断、SVG 可 git diff、离线部署；泳道图必须用它（Mermaid 泳道交叉不可控，已在 PUL-FMS 项目否决） |
| 时序图 / 顺序图 | **Mermaid sequence** | 生命线纵向布局无交叉问题，手写源码最快；可选 [WH-2099/mermaid-skill](https://github.com/WH-2099/mermaid-skill)（23 种图触发）或 [claude-mermaid MCP](https://github.com/veelenga/claude-mermaid)（浏览器实时预览） |
| ER 图一次性美化 | **[DrawDB](https://github.com/drawdb-io/drawdb)**（粘 DDL 反向出图；**必须 MySQL 方言 + 列/表 `COMMENT` 子句写中文注释**——SQLite 方言和 `--` 行注释 DrawDB 不导入，图上零中文；自动布局是网格平铺，清晰靠手动拖拽） | mock 数据项目无真库可连——ChartDB / Azimutt / Liam 等「连库逆向」型工具均不适用；把 JS 种子数据结构导出成 DDL 喂 DrawDB 即可 |
| 代码 → 图逆向提取 | [design-doc-mermaid](https://github.com/SpillwaveSolutions/design-doc-mermaid) | 从现有代码反推时序/架构图 |

组合原则：
- fireworks 管「评审级图纸」（要过 geometry check、长期维护、进图纸库的）
- Mermaid 管「时序图与轻量草图」（源码可 git diff、渲染快、不求零交叉的场景）
- 注意区分：「Mermaid 被否」只针对泳道/流程图的线条交叉，不针对时序图
- 输出共存：Mermaid 出的 SVG 与 fireworks SVG 放同一图纸库目录，走同一部署链