Can Archify Diagrams Include Animations? Enabling Trace Effects in JSON Architecture Diagrams

Yes, Archify supports opt-in trace animations controlled by setting meta.animation: "trace" in the JSON source, which injects CSS key-frame animations into the viewer while respecting prefers-reduced-motion accessibility settings and excluding motion from static exports.

Archify is an open-source diagramming tool from the tt-a1i/archify repository that generates architecture visualizations from JSON definitions. While the default output is static SVG, the rendering pipeline includes a presentation layer capable of finite "trace" animations that visualize data flow through nodes and edges.

How Animations Work in Archify

The animation system is opt-in by design. When the JSON source includes meta.animation: "trace", the CLI renderer injects the data-animation="trace" attribute into the HTML/SVG output. The accompanying CSS defines key-frame animations that create a flowing trace effect along edges and a pulse effect on nodes.

According to the source code in archify/renderers/shared/cli.mjs (lines 150‑170), the CLI checks the meta.animation field during the rendering phase:

// From archify/renderers/shared/cli.mjs
if (config.meta?.animation === 'trace') {
  svgRoot.setAttribute('data-animation', 'trace');
}

The viewer runtime then applies the CSS animations only when this attribute is present, as documented in archify/references/viewer-runtime.md (line 25).

Enabling Trace Animations in Your JSON Source

To activate motion, define the animation property within the meta object of your diagram definition. The archify/SKILL.md file specifies this as the canonical way to enable viewer-only motion.

{
  "$schema": "archify/schemas/architecture.schema.json",
  "meta": {
    "animation": "trace",
    "visual_preset": "signal-flow"
  },
  "nodes": [
    { "id": "web", "type": "frontend", "label": "Web App" },
    { "id": "api", "type": "backend", "label": "API Server" },
    { "id": "db", "type": "database", "label": "Postgres" }
  ],
  "edges": [
    { "source": "web", "target": "api", "label": "HTTP request" },
    { "source": "api", "target": "db", "label": "SQL query" }
  ]
}

When this JSON is processed, the generated HTML contains animated edges that trace the path of the HTTP request and SQL query, creating a visual signal-flow effect.

Rendering Animated Diagrams via CLI

Generate the animated version using the Archify CLI. The animation attribute is injected during the deliver command execution:

node archify/bin/archify.mjs deliver architecture diagram.json out.html --quality showcase --json

Opening out.html in a browser renders the trace animation where request arrows pulse along their paths. This behavior is strictly runtime-dependent; the underlying SVG geometry remains static, with motion applied via the viewer's CSS layer.

Accessibility and Static Export Behavior

Archify respects user preferences and export contexts. The animation system automatically disables under three conditions:

• Reduced motion preferences: The CSS queries prefers-reduced-motion and disables key-frames when users have requested minimal animation.
• Print media: Stylesheets exclude animations when the diagram is printed.
• Static exports: When exporting to PNG, SVG (static), or WebM-still formats, the export process strips the runtime-only CSS animation classes.

As noted in README.md (lines 78‑84), using the Export menu to download a PNG or SVG yields a static snapshot regardless of the meta.animation setting.

Disabling Animations

To ensure a static output, explicitly set the animation field to "none" or omit the animation key entirely (default behavior):

{
  "meta": {
    "animation": "none"
  }
}

Re-running the CLI command with this configuration produces HTML containing only static SVG elements without data-animate attributes or CSS key-frame definitions.

Summary

• Archify supports opt-in trace animations via meta.animation: "trace" in JSON diagram sources.
• The CLI injects the data-animation="trace" attribute in archify/renderers/shared/cli.mjs (lines 150‑170) based on the meta field.
• Animations are viewer-only and respect prefers-reduced-motion accessibility settings.
• Static exports (PNG, SVG) automatically strip animation CSS, ensuring still images remain static.
• Default behavior produces static diagrams; motion must be explicitly enabled by the diagram author.

Frequently Asked Questions

How do I disable animations in Archify diagrams?

Set "meta": { "animation": "none" } in your JSON source, or omit the animation field entirely. By default, Archify outputs static diagrams without motion, so disabling requires only removing the "trace" value or regenerating without the animation flag.

Do Archify animations work in exported PNG files?

No. The export process documented in README.md (lines 78‑84) intentionally strips runtime CSS animations from PNG and static SVG exports. Even when meta.animation: "trace" is set in the source, exported images capture a single static frame without motion.

What triggers the trace animation effect?

The trace effect triggers when the JSON source contains meta.animation: "trace". This value causes the CLI to add data-animation="trace" to the SVG root element, which the viewer runtime interprets as a signal to apply CSS key-frame animations to edges and nodes bearing the data-animate attribute.

Does Archify respect accessibility settings for motion?

Yes. The viewer runtime checks for prefers-reduced-motion media queries and disables CSS key-frame animations automatically when users have indicated a preference for reduced motion. This ensures Archify diagrams remain accessible to users with vestibular disorders or motion sensitivity.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}