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

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). The same enum appears in [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:

{
  "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):

{
  "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):

{
  "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)	Defines animation enum for architecture diagrams
[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)	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)	Workflow example with trace enabled
[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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}