# How to Use Animation Modes in Archify: Enabling Trace Motion for Dynamic Diagrams

> Learn to use Archify animation modes for trace motion. Animate edges with flowing dashes and pulse nodes to visualize data flow in your diagrams.

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

---

**Set `"animation": "trace"` in your diagram's `meta` object to enable trace motion, which animates edges with flowing dashes and pulses nodes to show data flow across your diagram.**

Archify's renderer supports animated diagram elements that visualize the flow of data or control-flow through a system. This **trace motion** feature is controlled through a single JSON property, making it easy to add professional animations to workflow, architecture, and other diagram types. This guide explains how to enable animation modes in Archify using the trace effect, based on the `tt-a1i/archify` source code.

## Understanding the Animation Schema

Archify defines animation options at the schema level. In [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), the `meta.animation` property is defined as an enumeration with two values:

```json
"animation": {
  "enum": ["trace", "none"]
}

```

- **trace** – Activates trace motion. Edges display moving dashes (`archify-edge-flow`) and nodes pulse (`archify-node-pulse`).
- **none** – Default behavior. Renders a static SVG with no animation.

The schema validation ensures only these values are accepted, preventing invalid animation configurations.

## How the Renderer Implements Trace Motion

When you enable trace animation, three components work together to produce the visual effect.

### 1. SVG Root Attribute Injection

In `archify/renderers/shared/cli.mjs`, the `svgRootAttrs` function checks `meta.animation` and injects `data-animation="trace"` on the root `<svg>` element when the flag is set:

```javascript
// cli.mjs L45-L46
if (meta.animation === 'trace') {
  attrs['data-animation'] = 'trace';
}

```

### 2. Per-Element Animation Attributes

The same file uses `animateAttr` to add `data-animate` attributes with step offsets to individual elements:

```javascript
// cli.mjs L64-L71
const animateAttr = (type, step) => {
  return meta.animation === 'trace' 
    ? { 'data-animate': type, 'data-step': step }
    : {};
};

```

This staggers animations so edges and nodes animate in sequence rather than simultaneously.

### 3. CSS Keyframes and Styling

The bundled template at [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) contains the actual animation definitions:

- `@keyframes archify-edge-flow` – Creates the moving dashed line effect on edges
- `@keyframes archify-node-pulse` – Produces the pulsating highlight on nodes

These keyframes are scoped to `[data-animation="trace"]` selectors, so animations only run when explicitly enabled.

## Enabling Trace Animation in Your Diagram

Add the `animation` property to your diagram's `meta` object:

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": {
    "title": "Data Processing Pipeline",
    "animation": "trace",
    "visual_preset": "classic"
  },
  "nodes": [
    { "id": "input", "type": "start" },
    { "id": "process", "type": "task" },
    { "id": "output", "type": "end" }
  ],
  "edges": [
    { "from": "input", "to": "process" },
    { "from": "process", "to": "output" }
  ]
}

```

The example [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json) demonstrates this pattern in practice, with animation enabled in lines 5-8.

## Rendering Animated Diagrams

Use the CLI renderer to generate HTML with embedded animations:

```bash
node render-workflow.mjs path/to/your-diagram.json

```

The `loadDiagram` function in `cli.mjs` (lines 14-22) handles the full pipeline: reading JSON, validating against the schema, and passing the `meta` object to the renderer. Output is a self-contained HTML file with the animated SVG.

## Disabling Animation

To produce static output, either omit the `animation` property or set it explicitly:

```json
{
  "meta": {
    "title": "Static Architecture Diagram",
    "animation": "none"
  }
}

```

This prevents the `data-animation` attribute from appearing on the SVG, and no keyframe animations are applied.

## Accessibility: Reduced Motion Support

Archify respects `prefers-reduced-motion` settings. In [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) (lines 998-1005), the "Motion Governor" block forces animations to `none` when users disable motion:

```css
@media (prefers-reduced-motion: reduce) {
  [data-animation="trace"] * {
    animation: none !important;
  }
}

```

This ensures diagrams remain accessible without requiring JSON changes.

## Summary

- **Set `"animation": "trace"`** in `meta` to enable edge and node animations
- **The renderer** in `cli.mjs` adds `data-animation` and `data-animate` attributes to SVG elements
- **CSS keyframes** in [`template.html`](https://github.com/tt-a1i/archify/blob/main/template.html) drive the visual effects when the flag is present
- **Reduced motion preferences** automatically disable animations for accessibility
- **Schema validation** in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) restricts values to `"trace"` or `"none"`

## Frequently Asked Questions

### What diagram types support trace animation?

All diagram types that include the `meta.animation` schema field support trace motion. This includes workflow and architecture diagrams as defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). Check your specific diagram type's schema to confirm the field is available.

### Can I customize the animation speed or colors?

The current `tt-a1i/archify` implementation uses fixed CSS keyframes in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html). The animation timing and colors are determined by the `archify-edge-flow` and `archify-node-pulse` keyframes. To customize, you would need to modify the template or override the CSS after generation.

### Does trace animation work in exported PNG or PDF files?

No. Trace animation requires the CSS keyframes and JavaScript runtime present in the HTML output. Static exports like PNG or PDF capture only the initial frame. For animated documentation, use the HTML format or embed the SVG with its accompanying styles.

### How do I test that animation is correctly enabled?

The repository includes `archify/test/animation.test.mjs`, which validates that `data-animation="trace"` appears only when `meta.animation` is set to `"trace"`. You can run this test suite or inspect the generated HTML source to verify the attribute is present on the root `<svg>` element.