How to Configure the Animation Trace Option for Presentations in Archify

Set meta.animation: "trace" in your diagram schema to enable trace animation for Archify presentations.

The trace animation in Archify adds lightweight SVG/CSS effects to diagrams, making it ideal for demos and presentations where you want to illustrate flow or sequence visually. This feature is fully opt-in and respects user motion preferences.

Overview of Trace Animation

Archify renders diagrams to static SVG by default. When you need to present a diagram interactively—such as walking through a user flow or system architecture—you can enable trace animation. This adds subtle CSS-driven effects that "trace" the path of edges and highlight nodes sequentially.

The animation system consists of three components:

• Schema configuration – the meta.animation property in your diagram file
• Renderer injection – cli.mjs adds data-animation="trace" to the output
• CSS activation – template.html contains keyframe animations triggered by the data attribute

Enabling Trace Animation in Your Diagram Schema

To activate trace animation, add animation: "trace" to the metadata section of your diagram:

{
  "schema_version": "1.0",
  "diagram_type": "workflow",
  "meta": {
    "title": "User Registration Flow",
    "animation": "trace"
  },
  "edges": [
    { "source": "start", "target": "process", "meta": { "animate": true } }
  ]
}

Only the value "trace" triggers the animation system. Any other value or omitted property results in static rendering.

How the Renderer Processes the Animation Flag

In archify/renderers/shared/cli.mjs, the renderer checks meta.animation and conditionally injects the data attribute:

// archify/renderers/shared/cli.mjs
const animation = meta.animation === 'trace' ? ' data-animation="trace"' : '';

The renderer also includes a guard clause that skips animation processing entirely when the flag isn't set:

if (meta.animation !== 'trace') return '';

This ensures zero overhead for static diagrams.

CSS Animation Activation

The bundled HTML template at archify/assets/template.html contains CSS keyframes that activate when data-animation="trace" is present on the SVG element. The template defines two primary animation types:

• archify-edge-flow – draws edges progressively to simulate a trace effect
• archify-node-pulse – highlights nodes as the trace reaches them

These animations target elements marked with data-animate="edge" and data-animate="node" respectively.

Respecting User Motion Preferences

The CSS implementation includes a prefers-reduced-motion media query. Users who have enabled reduced motion in their system settings will see a static diagram regardless of the meta.animation setting. This aligns with accessibility best practices and requires no additional configuration.

Rendering Animated Diagrams

Trace animation only applies to HTML output. Use the --format=html flag when rendering:

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

Opening the resulting file in a browser displays the animated trace. For static exports (PNG, SVG, or plain text), the animation flag is ignored and standard rendering applies.

Complete Working Example

Below is a full workflow diagram with trace animation enabled for a presentation:

{
  "schema_version": "1.0",
  "diagram_type": "sequence",
  "meta": {
    "title": "Payment Processing Flow",
    "description": "End-to-end payment flow for demo",
    "animation": "trace"
  },
  "lanes": [
    { "id": "user", "label": "User" },
    { "id": "api", "label": "API Gateway" },
    { "id": "service", "label": "Payment Service" }
  ],
  "nodes": [
    { "id": "submit", "lane": "user", "label": "Submit Payment" },
    { "id": "validate", "lane": "api", "label": "Validate Token" },
    { "id": "process", "lane": "service", "label": "Process Charge" }
  ],
  "edges": [
    { "source": "submit", "target": "validate", "label": "POST /pay", "meta": { "animate": true } },
    { "source": "validate", "target": "process", "label": "forward", "meta": { "animate": true } }
  ]
}

Render and view:

archify render payment.json --format=html -o payment.html
open payment.html

Source Files Reference

File	Purpose	GitHub Link
archify/renderers/shared/cli.mjs	Injects data-animation="trace" based on schema	https://github.com/tt-a1i/archify/blob/main/archify/renderers/shared/cli.mjs
archify/assets/template.html	CSS keyframes and animation triggers	https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html
archify/SKILL.md	Documentation for meta.animation option	https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md
CHANGELOG.md	Feature introduction history	https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md

Summary

• Enable trace animation by setting meta.animation: "trace" in your diagram schema
• The CLI renderer in cli.mjs checks this flag and injects data-animation="trace"
• CSS animations in template.html activate only when the data attribute is present
• Animation only applies to HTML output; other formats render statically
• Accessibility compliance is automatic via prefers-reduced-motion support

Frequently Asked Questions

What happens if I set meta.animation to a value other than "trace"?

Any value except "trace" is treated as disabled. The renderer skips animation injection and outputs a static diagram. This design prevents accidental activation through typos or unsupported animation types.

Can I use trace animation with PNG or SVG exports?

No. Trace animation requires the CSS and JavaScript bundled in HTML output. PNG exports are raster images with no animation capability, and standalone SVG exports omit the animation stylesheet to ensure compatibility with external tools.

Does trace animation affect diagram generation performance?

Minimal impact. The renderer checks meta.animation once during output generation. When disabled, the guard clause returns early with no additional processing. When enabled, the only overhead is a single data attribute and lightweight CSS keyframes that run client-side.

How do I preview trace animation without writing a file?

Use the --format=html flag and pipe to a temporary file, then open in your browser. Some Archify workflows support direct browser launch via --browse or similar flags—check your installed version's CLI help with archify render --help.

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