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.

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. 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 and icons only for the relevant type or symbols.

Generate and check

Reuse the user's current brief and artifact; an extra planning document is optional. 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.

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 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.
• 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 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.

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.

English | 中文

Release history · Changelog

fireworks-tech-graph

Stop drawing diagrams by hand. Describe your system in English or Chinese — get geometry-safe SVG, PNG, focused SVG-to-GIF motion, and offline interactive technical diagrams.

Output quality

The current checkout adds complete-text reporting and stronger supporting text across the default themes. Add "text_policy": "strict" to reject visible truncation before output is written; reports preserve the full source label and explain how to recover. Chinese descriptions use the available second line. See visual quality for theme-specific guidance and measurement limits.

python3 "$SKILL_ROOT/scripts/fireworks.py" version
python3 "$SKILL_ROOT/scripts/fireworks.py" export-png diagram.svg diagram.png --width 1920

version reports the package, actual Skill root and Git state when available. doctor distinguishes SVG/HTML support from optional PNG/GIF dependencies. PNG export checks the root canvas, bounds image size, writes atomically and reads the resulting pixel dimensions back. The browser PNG exporter remains available for Chromium fidelity. The showcase GIFs below are the published 1.2.0 references; this unreleased upgrade preserves their motion contracts.

Overview

fireworks-tech-graph is one Agent Skill that works unchanged in Codex and Claude Code. It turns natural language descriptions into polished, geometry-checked SVG diagrams, high-resolution PNGs, validated SVG-to-GIF semantic motion, and offline interactive HTML. The focused animation path accepts a generated semantic SVG and emits one compact, probed GIF. It ships with 11 generator-backed styles and 1 AI-authored style (Dark Luxury). Four engineering-first styles add executable contracts for C4 reviews, cloud deployments, event streams, and reliability investigations, alongside deep AI/Agent domain patterns and all 14 UML diagram types.

User: "Generate a Mem0 memory architecture diagram, dark style"
  → Skill classifies: Memory Architecture Diagram, Style 2
  → Generates SVG with swim lanes, cylinders, semantic arrows
  → Exports 1920px PNG
  → Reports: mem0-architecture.svg / mem0-architecture.png

Sponsors

Interested in becoming a sponsor? Contact: ccc7574@gmail.com

Work With the Builder

This project is also a proof surface for a broader capability: turning vague AI/devtool workflows into constrained, reusable systems with validation, documentation, export paths, and product-facing polish.

If you are building agent infrastructure, AI IDEs, internal copilots, developer tools, technical documentation systems, or applied AI workflow products, I am open to scoped paid sprints, design-partner work, and founding engineer conversations.

• Founder-facing profile: https://bradzhang.dev/en
• Commercial case study: https://bradzhang.dev/en/case-studies/fireworks-tech-graph
• Work with me: https://bradzhang.dev/en/work-with-me

Showcase

The animated previews use the user-approved 5.75-second settled-flow timeline: routes draw in first, then the final topology keeps live data moving for two additional seconds. Each full-size GIF is 960px wide at 20fps / 115 frames; the 3×4 overview is an optimized 1200px preview. Lossless 1920px PNGs remain in assets/samples/ as static regression baselines.

The v1.2.0 overview above and every full-size animated sample below come from the approved regression set. Each style keeps a distinct scenario while sharing the same geometry, text-fit, wire-routing, and semantic-motion quality gates.

Style 1 — Flat Icon (default)

Mem0 Memory Architecture — personal-memory extraction, conflict resolution, storage, and retrieval

Style 2 — Dark Terminal

Tool Call Flow — dark terminal execution, source grounding, retrieval, and answer synthesis

Style 3 — Blueprint

Microservices Architecture — engineering grid, domain services, data stores, events, and telemetry

Style 4 — Notion Clean

Agent Memory Types — minimal hierarchy from sensory and working context to durable memory

Style 5 — Glassmorphism

Multi-Agent Collaboration — coordinator, specialists, shared state, review, and synthesis

Style 6 — Claude Official

System Architecture — warm interface, runtime, safety, memory, tools, and operations layers

Style 7 — OpenAI Official

API Integration Flow — clean SDK, prompt, model, tool, delivery, and release stages

Style 8 — Dark Luxury (AI-authored)

Agent Runtime Architecture — control plane, execution and state layers, champagne-gold structure, semantic color buckets

Style 9 — C4 Review Canvas

Checkout Container Review — one abstraction level, explicit responsibilities, technologies, and protocols

Style 10 — Cloud Fabric

Active–Active Checkout Deployment — global ingress, regions, VPC ownership, and cross-region replication

Style 11 — Event Transit

Checkout Event Line — topics as rails, processors as stations, a declared junction, DLQ, and state projection

Style 12 — Ops Pulse

Checkout Reliability Pulse — golden signals, one critical path, OTel export, and a correlated trace

Stable Prompt Recipe

The public showcase keeps a distinct domain scene for every style. They remain comparable because every fixture passes the same executable composition contract. A same-topology regression set remains internal under fixtures/quality-baseline/.

Draw the scenario assigned to style N:
1 Mem0 Memory Architecture; 2 Tool Call Flow; 3 Microservices Architecture;
4 Agent Memory Types; 5 Multi-Agent Collaboration; 6 System Architecture;
7 API Integration Flow; 8 Agent Runtime Architecture; 9 C4 Checkout Review;
10 Active–Active Cloud Deployment; 11 Checkout Event Line; 12 Checkout Reliability Pulse.
Preserve the scenario-specific nodes, sections, and reading direction.
Apply the showcase composition contract: zero crossings, zero bridge jumps, at most two bends per edge,
at most eight bends overall, at least 40px between nodes, at least 20px container gutter,
short orthogonal segments, and labels kept clear of nodes, routes, and section headers.
Preserve the selected style's typography, palette, card material, and brand details.

For the four engineering-first styles, use one of these prompt fingerprints so the router selects the domain contract as well as the visual theme:

Style 9 · C4 review board: show one C4 level, responsibilities, technologies, review state, and relationship protocols.
Style 10 · Multi-region deployment map: show global ingress, Region/VPC ownership, neutral cloud glyphs, deployment mode, and named boundary mechanisms.
Style 11 · Event metro map: show thin topic rails, numbered processor stations, declared junctions, consumer groups, DLQ, and state projections.
Style 12 · Reliability pulse: show one observation window, four golden signals per service, numbered critical hops, telemetry export, and one correlated trace.

Replace N with 1–12. Style 8 remains AI-authored and loads references/style-8-dark-luxury.md; Styles 9–12 also enforce their engineering semantic contract. All styles load references/composition-quality-contract.md.

Features

• 12 visual styles — 11 generator-backed profiles + 1 AI-authored style (Dark Luxury)
• **Engineeri