How to Enable Trace Animation in Archify Diagrams

Set meta.animation: "trace" in your diagram schema to enable SVG trace animations for HTML renders.

Archify is an open-source diagramming tool that supports lightweight trace animations for presentations and demos. By configuring a single metadata property, you can add CSS-driven flow effects to your diagrams without affecting static exports.

Understanding Trace Animation in Archify

Trace animation creates a visual flow effect along edges and nodes using CSS keyframes. This feature is opt-in and implemented entirely within the HTML rendering pipeline.

Core Implementation Files

The animation system spans two critical files in the tt-a1i/archify repository:

• archify/renderers/shared/cli.mjs – Detects the animation flag and injects the data-animation attribute
• archify/assets/template.html – Provides the CSS keyframes (archify-edge-flow, archify-node-pulse) that drive the visual effect

Configuring Trace Animation in Diagram Schemas

To activate trace animation, add the animation property to your diagram's meta object.

Step 1 – Set the Animation Metadata

In your JSON or YAML schema, specify meta.animation as "trace":

{
  "schema_version": "1.0",
  "diagram_type": "workflow",
  "meta": {
    "title": "User Registration Flow",
    "animation": "trace"
  },
  "lanes": [{ "id": "frontend", "label": "Frontend" }],
  "nodes": [
    { "id": "login", "lane": "frontend", "label": "Login Page" },
    { "id": "signup", "lane": "frontend", "label": "Signup Page" }
  ],
  "edges": [
    { "source": "login", "target": "signup", "label": "click", "meta": { "animate": true } }
  ]
}

Step 2 – Render to HTML Format

Use the CLI to generate the animated HTML output:

archify render registration.json --format=html > registration.html

Opening the resulting file in a browser displays the trace animation.

How the Renderer Handles Animation Flags

According to the source code in archify/renderers/shared/cli.mjs, the renderer checks for meta.animation === 'trace' before injecting animation attributes:

// archify/renderers/shared/cli.mjs
const animation = meta.animation === 'trace' ? ' data-animation="trace"' : '';
// ...
if (meta.animation !== 'trace') return '';

When the condition is met, the renderer adds data-animation="trace" to the root <svg> element. The bundled template (archify/assets/template.html) then activates CSS animations for elements carrying data-animate="edge" or data-animate="node" attributes.

Accessibility and Output Format Limitations

Trace animation only applies to HTML renders. When exporting to PNG or static SVG, the animation flags are ignored and you receive a static diagram.

The CSS implementation respects prefers-reduced-motion media queries. Users with reduced motion preferences enabled in their operating system will see a static diagram even when trace animation is configured.

Summary

• Set meta.animation: "trace" in your diagram schema to enable the feature
• Render with --format=html to generate animated output
• The renderer in archify/renderers/shared/cli.mjs injects data-animation="trace" when the flag is detected
• CSS keyframes in archify/assets/template.html drive the visual flow effect
• Respects accessibility: Honors prefers-reduced-motion settings automatically
• HTML-only: Does not affect PNG, static SVG, or CLI text output

Frequently Asked Questions

What file controls the trace animation logic in Archify?

The detection and injection logic resides in archify/renderers/shared/cli.mjs. This file checks if meta.animation equals "trace" and conditionally adds the data-animation attribute to the generated SVG markup.

Does trace animation work in static image exports?

No. Trace animation only activates when rendering to HTML format. PNG exports and static SVG files ignore the meta.animation property and render without motion effects.

How can I respect user preferences for reduced motion?

Archify's CSS implementation in archify/assets/template.html includes prefers-reduced-motion media queries. When users have reduced motion enabled in their system settings, the browser automatically suppresses the trace animation and displays a static diagram.

Can I animate specific edges or nodes while leaving others static?

Yes. Individual edges and nodes support an animate property within their meta objects. When set to true, the renderer adds data-animate="edge" or data-animate="node" attributes, allowing selective animation while the global meta.animation: "trace" setting enables the overall animation system.

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