# How to Configure Trace and Finite Motion Animations in Archify

> Learn to configure trace and finite motion animations in Archify by setting meta animation in your diagram. Control CSS keyframes and animation timing for dynamic visuals.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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"`.

```json
{
  "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:

```javascript
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:

```javascript
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:

```css
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:

```css
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.