How to Configure Trace and Finite Motion Animations in Archify

To configure trace and finite motion animations in Archify, set meta.animation: "trace" in your diagram's metadata; the CLI renderer injects a data-animation="trace" attribute that triggers CSS keyframes for edges and nodes, while the --step CSS variable ensures deterministic, finite timing.

Archify’s rendering engine supports opt-in animations that bring static diagrams to life without sacrificing performance or accessibility. By manipulating the meta.animation field in your diagram source, you control whether the output remains static or flows through a finite, reader-controlled trace sequence. This guide explains the implementation details found in the tt-a1i/archify repository, including the specific source files that handle attribute injection and timing calculations.

Enabling Trace Animation in Diagram Metadata

Animation is disabled by default in Archify. To activate the trace effect, add an animation key to the meta block of your diagram definition and set its value to "trace".

{
  "meta": {
    "animation": "trace",
    "viewBox": [880, 900],
    "preset": "classic"
  },
  "nodes": [...],
  "edges": [...]
}

When the CLI renderer processes this file, it checks meta.animation and conditionally adds the data-animation="trace" attribute to the root <svg> element. As implemented in archify/renderers/shared/cli.mjs at line 145, the logic evaluates:

const animation = meta.animation === 'trace' ? ' data-animation="trace"' : '';

If the field is omitted or set to any value other than "trace", the diagram renders as static HTML/SVG. The gallery builder script at scripts/build-gallery.mjs#L274 enforces this fallback explicitly:

animation: source.meta.animation || 'static',

How Finite Motion Timing Works

Archify implements finite motion through CSS variables that map to the logical ordering of diagram elements. The animation system assigns each edge and node a step index, then calculates a deterministic start delay using the --step variable.

The default timing applies a 160 ms stagger between elements:

animation-delay: calc(var(--step, 0) * 160ms);

This ensures that the first edge starts immediately, the second after 160 ms, the third after 320 ms, and so on. Because the delays are calculated from CSS variables rather than JavaScript, the motion is deterministic and reproducible—ideal for screen recordings or printed frames captured during animation.

The runtime reference at archify/references/viewer-runtime.md#L25 describes this behavior as a "finite reader-controlled Live/Still trace," distinguishing it from infinite looping animations.

Rendering Pipeline and Attribute Injection

The animation configuration flows through two primary components:

• CLI Renderer (archify/renderers/shared/cli.mjs): Injects the data-animation attribute based on the meta.animation value. When "trace" is detected, it adds data-animation="trace" to the SVG root.
• Gallery Builder (scripts/build-gallery.mjs): Handles batch rendering and defaults to 'static' when no animation metadata is present.

Once the attribute is present in the DOM, the shared stylesheet targets specific elements:

• Edges flagged with data-animate="edge" receive the archify-edge-flow keyframe animation.
• Nodes flagged with data-animate="node" receive the archify-node-pulse keyframe animation.

These animations run only when the root element carries data-animation="trace", ensuring that unanimated diagrams carry no unnecessary CSS overhead.

Respecting User Motion Preferences

Archify’s animation system respects accessibility standards. The viewer runtime checks the prefers-reduced-motion media query and suppresses animations for users who have enabled reduced motion settings. Additionally, the renderer automatically disables animations in print contexts or when the page is hidden.

This opt-in approach, documented in CHANGELOG.md#L140, ensures that motion-sensitive contexts receive static output unless the author explicitly enables trace animation and the viewer’s device supports it.

Customizing Animation Timing

For advanced use cases, you can override the default 160 ms step delay by providing a custom CSS variable. After rendering your diagram, include a stylesheet that redefines the --step value:

svg[data-animation="trace"] {
  --step: 0.2s;  /* Each subsequent element delays by 200ms */
}

This customization applies globally to all elements within the trace-enabled SVG, allowing you to speed up or slow down the finite motion without regenerating the diagram source.

Summary

• Opt-in activation: Set meta.animation: "trace" to enable animations; any other value (or omission) results in static output.
• Finite timing: The --step CSS variable creates deterministic delays (default 160 ms) based on element ordering.
• Source locations: Attribute injection occurs in archify/renderers/shared/cli.mjs#L145, with static fallback logic in scripts/build-gallery.mjs#L274.
• Accessibility: The system respects prefers-reduced-motion and disables animations in print or reduced-motion contexts.
• Customization: Override --step in custom CSS to adjust animation speed without modifying the source JSON.

Frequently Asked Questions

How do I disable animations entirely in Archify?

To disable animations, either omit the animation field from the meta block or set it to any value other than "trace" (such as "none" or "static"). The renderer defaults to static output when meta.animation is undefined, as enforced by the fallback logic in scripts/build-gallery.mjs#L274.

What file controls the trace animation attribute injection?

The CLI renderer at archify/renderers/shared/cli.mjs controls attribute injection. At line 145, the code checks if meta.animation === 'trace' and conditionally adds the data-animation="trace" string to the SVG root element.

Can I change the speed of the trace animation?

Yes. While the default delay uses calc(var(--step, 0) * 160ms), you can override the --step CSS variable in a custom stylesheet. For example, setting --step: 0.1s halves the delay between animated elements, creating a faster trace effect.

Does Archify support infinite looping animations?

No. Archify implements finite motion only. The animation timing is derived from the diagram's logical ordering and CSS variables, producing a deterministic sequence that completes rather than looping indefinitely. This design choice ensures predictable behavior for documentation and accessibility purposes.

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