how-to-guide

How to Control Animation Trace and Motion Settings in Archify: A Complete Guide

August 15, 2026 tt-a1i/archify ↗

Archify provides two independent controls for animation: trace effects configured per-diagram via JSON metadata, and global motion toggles via HTML data attributes.

Controlling animation trace and motion settings in Archify lets you decide whether diagrams flow dynamically or stay frozen for accessibility, screenshots, or performance. The tt-a1i/archify repository implements this through a split configuration model—diagram-level JSON settings for trace effects, and document-level HTML attributes for ambient motion.

Trace Animation: Enabling the Flowing Edge Effect

Trace animation draws edges and nodes with a flowing "draw-on" effect rather than rendering them statically. This is controlled in each diagram's source definition.

Setting Trace Animation in JSON

Open your diagram's JSON source (for example, examples/archify-repo.architecture.json). Locate or create the meta object and set the animation key:

{
  "meta": {
    "title": "My Architecture Diagram",
    "visual_preset": "classic",
    "animation": "trace"
  },
  "components": [...],
  "connections": [...]
}

"trace" — enables the flowing trace effect
"static" — renders diagrams without animation (default when omitted)

The scripts/build-gallery.mjs script propagates this setting during the build process. Reading source.meta.animation || 'static', it injects data-animation="trace" into the generated SVG element's markup.

Build-Time Propagation

When you run npm run build-gallery or execute scripts/build-gallery.mjs directly, the builder:

Parses each diagram's meta.animation value
Records it in the gallery manifest
Adds data-animation="trace" or data-animation="static" to output SVG elements

Source: scripts/build-gallery.mjs — the extraction and manifest insertion logic.

Global Motion Control: Pausing All Animations

Archify respects system-level motion preferences through HTML data attributes on the root <html> element. This controls whether CSS keyframe animations execute at all—useful for accessibility, reduced-motion preferences, or capturing static screenshots.

HTML Data Attributes for Motion

Attribute	Values	Purpose
`data-ambient-motion`	`"running"` (default) or `"still"`	Master switch for all ambient animations
`data-motion-capable`	`"true"` or `"false"`	Declares whether the environment supports animation

Static Mode for Screenshots or Accessibility

To freeze all animations regardless of individual diagram settings:

<!DOCTYPE html>
<html data-ambient-motion="still" data-motion-capable="true">
  <head>...</head>
  <body>
    <svg data-animation="trace">...</svg>
  </body>
</html>

When data-ambient-motion="still" is present, Archify's runtime CSS applies animation: none !important; to all animated elements. The experiments/visual-evolution/prototype.html file implements these conditional styles.

Runtime JavaScript Control

Toggle motion without page reload:

// Enable animations
document.documentElement.dataset.ambientMotion = 'running';

// Disable animations (freeze frame)
document.documentElement.dataset.ambientMotion = 'still';

The experiments/mco-showcase/mco-runtime.html example demonstrates toggling with data-motion-capable="false" combined with data-ambient-motion="still".

Complete Configuration Example

Here's a workflow combining both trace animation and global motion control:

// diagrams/api-gateway.architecture.json
{
  "meta": {
    "title": "API Gateway Flow",
    "visual_preset": "classic",
    "animation": "trace"
  },
  "components": [...],
  "connections": [...]
}

<!-- gallery output with global override -->
<html data-ambient-motion="still">
  <iframe src="gallery/artifacts/api-gateway.html"></iframe>
</html>

Result: The diagram was built with trace animation enabled, but renders statically because the parent page forces data-ambient-motion="still".

Key Implementation Files

examples/archify-repo.architecture.json — reference for meta.animation syntax
scripts/build-gallery.mjs — build-time propagation of animation settings
experiments/visual-evolution/prototype.html — CSS implementation of trace and motion controls
experiments/mco-showcase/mco-runtime.html — runtime motion toggling example

Summary

Trace animation is defined per-diagram in JSON via meta.animation: "trace" or "static"
The gallery builder at scripts/build-gallery.mjs converts JSON settings to SVG data-animation attributes
Global motion is controlled through <html data-ambient-motion="running|still">
Motion capability can be declared with data-motion-capable="true|false"
Static mode applies animation: none !important for accessibility and screenshots
These two controls operate independently—trace configures what animates, ambient motion configures whether animation runs

Frequently Asked Questions

How do I disable all animations in Archify for accessibility compliance?

Set data-ambient-motion="still" on your HTML root element. This overrides all CSS animations site-wide without modifying individual diagram files. Archify follows the CSS media query pattern; setting this attribute applies animation: none !important to all generated SVG content.

What's the difference between `animation: "static"` in JSON and `data-ambient-motion="still"`?

meta.animation: "static" prevents trace effects from being built into the diagram at all—edges render instantly without flowing paths. data-ambient-motion="still" keeps the trace markup present but freezes CSS animations. Use the former for smaller files, the latter for runtime control.

Can I animate some diagrams while keeping others static?

Yes. Set meta.animation: "trace" in the JSON files you want animated, "static" in others. Then render them together—each SVG carries its own data-animation attribute. Global data-ambient-motion overrides all, but when set to "running", individual diagram settings take effect.

Where does Archify check for the motion preference attributes?

The runtime checks document.documentElement.dataset.ambientMotion and document.documentElement.dataset.motionCapable. These are read by CSS selectors in prototype.html and by JavaScript initialization code. The library does not use prefers-reduced-motion media queries directly—you must map system preferences to these data attributes yourself.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how tt-a1i/archify works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →