# How to Enable Animation in Archify Diagrams: A Technical Guide

> Easily enable animation in Archify diagrams by setting meta animation to trace or appending ?play=1 to the embed URL. Visualize workflow traces with CSS keyframe animations.

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

---

**You enable animation in Archify diagrams by setting the `meta.animation` property to `"trace"` in your architecture JSON, or by appending `?play=1` to the embed URL, which activates CSS keyframe animations for workflow traces while respecting accessibility preferences.**

Archify renders static and animated visualizations of system architectures through its diagram viewer. To enable animation in Archify diagrams, you configure metadata properties that control the viewer's rendering behavior, allowing workflow traces to animate using built-in CSS keyframes defined in the source repository.

## Enable Animation via Metadata Configuration

The primary method to enable animation involves modifying the diagram's JSON definition to include animation metadata. According to the `tt-a1i/archify` source code, the viewer checks for the `meta.animation` field when initializing the render.

### Setting the meta.animation Property

In [`benchmarks/ordinary-model-floor/results/2026-07-26-pi-three-models-quality-first.json`](https://github.com/tt-a1i/archify/blob/main/benchmarks/ordinary-model-floor/results/2026-07-26-pi-three-models-quality-first.json) at line 4917, the benchmark example demonstrates the exact pattern used to enable trace animations. You must add the `animation` key inside the `meta` object and set its value to `"trace"`.

```json
{
  "title": "User Login Flow",
  "nodes": [],
  "edges": [],
  "meta": {
    "animation": "trace",
    "viewBox": [800, 600]
  }
}

```

When this property is present, the viewer automatically applies the appropriate CSS animation classes to nodes and edges upon rendering.

## Trigger Animation via URL Parameters

For embedded diagrams or shared links, you can force animation startup without modifying the underlying JSON file. Appending `?play=1` (or `&play=1` if other parameters exist) to the embed URL instructs the viewer to begin the trace animation immediately when the page loads.

```html
<iframe
  src="https://archify.example.com/diagrams/login-flow.svg?play=1"
  width="800"
  height="600"
  frameborder="0">
</iframe>

```

This approach is particularly useful when integrating Archify diagrams into documentation or presentation contexts where you want the animation to start automatically.

## How the Animation System Works

The Archify viewer uses CSS keyframe animations to create the trace effect. When `meta.animation` is set to `"trace"`, the renderer injects specific animation declarations that create flowing edges and pulsing nodes.

### CSS Keyframe Implementation

According to [`docs/research-visual-evolution-round-41.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-41.md) at lines 73-74, the viewer applies the following animation patterns:

- **Edges**: `animation: archify-edge-flow 2.4s linear infinite;`
- **Nodes**: `animation: archify-node-pulse 3.6s ease-in-out infinite;`

These keyframes create the visual trace effect that follows the workflow path through the diagram. The animation system is built into the core rendering logic and activates automatically when the metadata flag or URL parameter is detected.

### Accessibility and Reduced Motion Support

Archify respects the `prefers-reduced-motion` media query to ensure accessibility. As documented in [`docs/research-visual-evolution-round-41.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-41.md) at lines 18-22, if a user has enabled reduced motion in their system preferences, the viewer automatically suppresses the CSS animations while maintaining the full semantic information of the diagram. The content remains visible and navigable without the motion effects.

## Programmatic Control with JavaScript

You can also control animation behavior programmatically when initializing the viewer via JavaScript. The `ArchifyViewer` class accepts configuration options that mirror the metadata and URL parameter behaviors.

```javascript
const viewer = new ArchifyViewer('#viewer');
viewer.loadDiagram('login-flow.json', {
  animation: 'trace',
  play: true
});

```

This method provides dynamic control over both the animation type and the autoplay behavior, allowing you to enable or disable motion based on runtime conditions or user preferences.

## Summary

- **Set `meta.animation: "trace"`** in your diagram JSON to enable built-in trace animations.
- **Append `?play=1`** to embed URLs for automatic playback without modifying source files.
- **CSS keyframes** power the visual effects, with specific timing for edges (`2.4s`) and nodes (`3.6s`).
- **Accessibility compliance** is automatic through `prefers-reduced-motion` detection in the viewer.
- **JavaScript API** provides runtime control via the `animation` and `play` configuration options.

## Frequently Asked Questions

### What animation types does Archify support?

Currently, Archify supports the `"trace"` animation type, which creates a flowing visualization of workflow paths through the diagram. This is the value used in the benchmark files and recognized by the viewer implementation.

### How do I disable animation for users with motion sensitivity?

You do not need to implement custom logic. The Archify viewer automatically checks for `prefers-reduced-motion` settings as documented in [`docs/research-visual-evolution-round-41.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-41.md) (lines 18-22) and disables CSS animations when users have indicated they prefer reduced motion, while keeping the diagram fully functional and readable.

### Can I control animation speed?

The animation timing is controlled through CSS keyframes defined in the viewer styles (specifically `2.4s` for edge flow and `3.6s` for node pulse). To modify these durations, you would need to override the CSS classes `archify-edge-flow` and `archify-node-pulse` in your custom stylesheet or fork the viewer implementation.

### Where is the animation configuration stored?

While the `meta.animation` property resides in your diagram JSON files, the actual animation definitions and reduced-motion handling logic are located in [`docs/research-visual-evolution-round-41.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-41.md) within the repository, which documents the visual evolution of the animation system and its accessibility features.