# How to Configure Animation and Motion with `meta.animation: "trace"` in Archify

> Learn how to configure animation and motion with meta.animation: "trace" in Archify. Enable a finite edge-tracing animation that runs once on load.

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

---

**Set `"animation": "trace"` inside the top-level `meta` object of your diagram's JSON to enable a finite edge-tracing animation that runs once on load, then stops.**

Archify's declarative rendering engine supports optional motion effects through a single configuration field in the diagram's **meta** object. The `animation` property accepts two enum values defined across all diagram schemas: `"trace"` for a deterministic, single-run edge animation or `"none"` for fully static output. This guide explains how `meta.animation: "trace"` works, where to place it in your JSON structure, and how the viewer implements the effect according to the Archify source code.

## Where the animation Field Is Defined

The `animation` enum is formally specified in every diagram schema within the repository. For architecture diagrams, the definition lives in [[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). The same enum appears in [[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) for workflow diagrams.

Both schemas constrain the field to two string values:

- **`"trace"`** — Triggers the sequential edge-highlighting animation
- **`"none"`** — Disables all motion, producing static SVG output

## How the Trace Animation Works

When `meta.animation` is set to `"trace"`, the Archify viewer executes three behaviors on load:

1. **Sequential edge highlighting** — Each connection is emphasized in authoring order, with brief pauses at destination nodes to signal flow direction.

2. **CSS stroke-dashoffset transition** — The renderer applies a CSS transition to `stroke-dashoffset` on SVG path elements, creating a visual "drawing" effect as if the edge is being sketched in real time.

3. **Automatic termination** — The animation halts after the final edge completes, leaving the diagram in its terminal static state. This finiteness makes `"trace"` safe for **PNG export** and **WebM recording**, and ensures compatibility with `prefers-reduced-motion` accessibility settings.

## Minimal Configuration Example

The `animation` field sits alongside other visual controls like `visual_preset` and `quality_profile`. A complete minimal example for an architecture diagram:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Simple Service Map",
    "animation": "trace",
    "visual_preset": "signal-flow",
    "quality_profile": "showcase"
  },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "Web UI", "col": 0, "row": 0 },
    { "id": "api", "type": "backend", "label": "API Server", "col": 1, "row": 0 },
    { "id": "db", "type": "database", "label": "Postgres", "col": 2, "row": 0 }
  ],
  "connections": [
    { "from": "frontend", "to": "api", "variant": "http" },
    { "from": "api", "to": "db", "variant": "sql" }
  ]
}

```

## Production Examples in the Repository

The official Archify examples demonstrate `meta.animation: "trace"` in real-world contexts.

**Architecture diagram with trace animation** from [[`archify/examples/production-deployment.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/production-deployment.architecture.json)](https://github.com/tt-a1i/archify/blob/main/archify/examples/production-deployment.architecture.json):

```json
{
  "meta": {
    "title": "Production Deployment",
    "animation": "trace",
    "visual_preset": "signal-flow",
    "quality_profile": "showcase"
  }
}

```

**Workflow diagram with trace animation** from [[`archify/examples/release-delivery.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/release-delivery.workflow.json)](https://github.com/tt-a1i/archify/blob/main/archify/examples/release-delivery.workflow.json):

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": {
    "title": "Release Delivery",
    "animation": "trace",
    "visual_preset": "classic"
  }
}

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| [[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Defines `animation` enum for architecture diagrams |
| [[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | Defines `animation` enum for workflow diagrams |
| [[`archify/examples/production-deployment.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/production-deployment.architecture.json)](https://github.com/tt-a1i/archify/blob/main/archify/examples/production-deployment.architecture.json) | Production architecture example with trace enabled |
| [[`archify/examples/release-delivery.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/release-delivery.workflow.json)](https://github.com/tt-a1i/archify/blob/main/archify/examples/release-delivery.workflow.json) | Workflow example with trace enabled |
| [[`docs/gallery/manifest.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/manifest.json)](https://github.com/tt-a1i/archify/blob/main/docs/gallery/manifest.json) | Aggregates demo files using the `animation` field |

## Summary

- **`meta.animation: "trace"`** enables a finite, deterministic edge-tracing animation in Archify diagrams.
- The animation runs **once on load** using CSS `stroke-dashoffset` transitions, then stops automatically.
- This behavior is **export-safe** for PNG/WebM and **respects accessibility** preferences.
- Placement is mandatory inside the **top-level `meta` object**, sibling to `title`, `visual_preset`, and `quality_profile`.
- Toggle between `"trace"` and `"none"` to add or remove motion without changing any other diagram structure.

## Frequently Asked Questions

### What values does the `meta.animation` field accept?

The `animation` field accepts only two string values: `"trace"` or `"none"`. These are enforced by JSON Schema definitions in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) and [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json). Any other value will fail schema validation.

### Does the trace animation loop continuously?

No. The trace animation is **finite by design** — it executes once through all edges in authoring order, then terminates. This distinguishes Archify's approach from infinite looping animations and ensures deterministic output for documentation and export workflows.

### Can I use `meta.animation: "trace"` with all diagram types?

Yes. The `animation` field is defined consistently across Archify's diagram schemas. Both architecture diagrams and workflow diagrams support identical `meta.animation` configuration, as confirmed by the schema files and working examples in the repository.

### Will trace animation affect PNG or WebM exports?

No. Because the animation stops after completing its single run, the diagram reaches a stable final state suitable for capture. The deterministic, finite behavior ensures that exported frames match the intended static output without timing-dependent artifacts.