Compile interactive system maps with ak:diagram

Use ak:diagram when you need a validated interactive system map or an editorial diagram. The Skill compiles typed JSON IR for architecture, workflow, sequence, dataflow, and lifecycle maps, and still renders Mermaid, legacy editorial templates, and prepared HTML.

Choose ak:diagram by the artifact

Use ak:diagram when

• You need an interactive architecture, sequence, workflow, dataflow, or lifecycle map from typed JSON.
• You need SVG, self-contained HTML, PNG, or a short video from Mermaid or editorial input.
• You need local, deterministic compilation without a CDN.

Choose another workflow when

• You want reviewable Mermaid source without editorial framing. Use ak:mermaidjs-v11.
• You need an editable canvas or codebase auto-map. Use ak:excalidraw.
• You need large-graph exploration and analytics. Use ak:graphify.
• You are deciding whether a visual explanation is useful at all. Start with ak:preview.

Invoke the Skill

Complete Onboarding, and confirm Engineer Kit is installed for your runtime and scope. Provide the input file, intended artifact, and whether browser rendering, video capture, or dependency installation is allowed.

/ak:diagram "Compile architecture.json to interactive HTML in ./build. Use preset classic and theme dark. Do not install dependencies."

/ak:diagram "Compile architecture.json to interactive HTML in ./build. Use preset classic and theme dark. Do not install dependencies."

$ak:diagram "Compile architecture.json to interactive HTML in ./build. Use preset classic and theme dark. Do not install dependencies."

These are Skill invocation flags:

Bundled render.py / record.py helpers still accept --input, --title, --caption, --no-png, --no-svg, --dry-run, --snapshot-profile, --duration, --fps, --gif, and --keep-frames. Those helper controls are not Skill invocation flags.

Choose an input tier

Typed IR is the preferred path for system maps. Interactive HTML is deterministic and respects prefers-reduced-motion: reduce.

Separate static rendering from video recording

The static rendering helper always writes <basename>.html and, by default, also writes:

• <basename>.png — a 2× screenshot with animations frozen at their final frame;
• <basename>.svg — only when an SVG exists in the rendered page and can be extracted.

Its --no-png and --no-svg controls suppress those outputs. --dry-run writes HTML without launching the browser. HTML is the animated surface; PNG is a frozen static frame. SVG extraction serializes the first SVG found in the rendered DOM; it does not promise that every input contains an SVG or that page-level CSS, fonts, assets, or animation context remain standalone. Inspect the extracted static artifact.

Video is a separate recording step over an HTML input. MP4 is the default; the recording helper's --gif selects a palette-generated GIF. It pauses browser animations, advances currentTime frame by frame at the requested --duration and --fps, captures temporary PNG frames, and asks ffmpeg to assemble the result. Mermaid has no native animation primitives in this workflow: animated Mermaid connectors require post-processing, while prepared HTML can use the eight bundled CSS connector effects. Those effects freeze when prefers-reduced-motion: reduce is active.

Probe dependencies without installing them

Ask the Skill to run its bundled dependency probe before rendering. The probe reports readiness and never installs anything. It checks:

HTML-only composition can avoid the browser with the helper's --dry-run. Browser-rendered PNG or SVG needs Playwright and Chromium. Video additionally needs ffmpeg. Treat installation of any missing dependency as a separate approved action.

Understand determinism and visible effects

Pinned Mermaid, frozen animations, fixed browser settings, and frame stepping support reproducible output with a fixed Chromium, font, and ffmpeg toolchain. A snapshot comparison refuses the wrong browser or font profile rather than reporting misleading hash drift. Outside that profile, browser or ffmpeg versions, font substitution, label wrapping, and Mermaid auto-layout can change pixels, encoding, or hashes. Animated HTML remains dynamic; the PNG is one frozen state, and MP4 or GIF is an explicit frame sequence. Record the actual tool versions used.

Bundled Mermaid, templates, styles, and effects are local and require no CDN. However, user-supplied HTML can contact the network when it references remote scripts, fonts, images, or other assets. The Skill does not publish, upload, commit, or push generated artifacts unless a separate workflow is explicitly authorized.

A complete result reports the input tier, selected type and variant, exact outputs, dependencies actually used, static or video boundary, visual review, network activity, overwritten files, and any unverified renderer or font-profile condition.