# How to Configure the Animation Trace Option for Presentations in Archify

> Easily configure Archify presentations with the animation trace option. Simply set meta.animation: "trace" in your diagram schema for dynamic visuals. Learn more now.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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:

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

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

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

```

This ensures zero overhead for static diagrams.

## CSS Animation Activation

The bundled HTML template at [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/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:

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

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) | CSS keyframes and animation triggers | https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Documentation for `meta.animation` option | https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md |
| [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`.