Archify Animation Modes and Accessibility: A Complete Guide to Motion Control in Diagrams

Archify supports two animation modes—"trace" for animated flow visualization and "none" for static rendering—with automatic fallback to static diagrams when users have prefers-reduced-motion enabled.

Archify's diagram engine gives developers explicit control over animation behavior through a simple JSON configuration, while simultaneously respecting end-user accessibility preferences. The system combines schema-level animation declarations with runtime media query detection to ensure motion-sensitive users always receive a safe, static experience unless explicitly overridden.

Animation Control in the Data Model

All diagram-type schemas in Archify—architecture, workflow, sequence, lifecycle, and dataflow—share a common JSON Schema definition that includes the animation property.

The animation Enum

In archify/schemas/common.schema.json (lines 13-15), the animation field is defined as:

{
  "animation": {
    "type": "string",
    "enum": ["trace", "none"]
  }
}

• "trace" — Triggers a finite, deterministic animation that illustrates data or control flow through the diagram
• "none" — Renders the diagram statically with no motion

When meta.animation is set to "trace", the renderer initializes the trace animation subsystem. Setting it to "none" bypasses all animation logic and outputs a static SVG or canvas rendering.

Built-in Examples

Every shipped example in the Archify repository uses the animation field to demonstrate the feature. The pattern appears consistently in the meta object:

{
  "meta": {
    "animation": "trace",
    "locale": "en",
    "visual_preset": "signal-flow"
  },
  "nodes": [...],
  "edges": [...]
}

Notable examples include:

• archify/examples/agent-tool-call.workflow.json — AI agent workflow with trace animation enabled
• archify/examples/production-deployment.architecture.json — System architecture diagram with flow visualization

These files validate against the schema in common.schema.json and serve as reference implementations for animation opt-in.

Respecting prefers-reduced-motion

Archify implements defense-in-depth accessibility: even when a diagram author requests animation, the viewer checks the user's system preferences before executing any motion.

Client-Side Detection

In generated viewer files such as generated/maka-regenerated.workflow.html (line 7193), the detection logic follows this pattern:

var reducedMotion = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)');
if (reducedMotion && reducedMotion.matches) {
  // Disable animation; use static rendering
}

The shouldAnimate() helper function encapsulates this check:

function shouldAnimate() {
  const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
  return !(mq && mq.matches);
}

// Animation initialization
if (shouldAnimate() && diagramMeta.animation === 'trace') {
  startTraceAnimation();
} else {
  renderStaticSnapshot();
}

CSS Fallback

For transitions that might occur outside JavaScript control, the HTML template at scripts/start-template.html (line 174) includes a global CSS safeguard:

@media (prefers-reduced-motion: reduce) {
  * { transition: none !important; }
}

This ensures that even CSS-based hover states or loading animations are suppressed when reduced motion is preferred.

How Settings Flow Through the Pipeline

Archify's animation behavior is determined through three integrated stages:

1. Schema validation — The CLI validates meta.animation against the enum in common.schema.json before any processing begins. Invalid values trigger an early error.

2. Renderer configuration — During archify deliver execution, the system reads the validated meta.animation value. If the environment variable ARCHIFY_REDUCED_MOTION_DISABLED=1 is set, this check is bypassed; otherwise, the renderer forces animation: "none" when reduced motion is detected.

3. Client-side execution — The generated viewer's JavaScript performs a final runtime check of the media query. If reduced motion is active, animation timers are set to 0 or the animation loop is skipped entirely, displaying the static frame.

This pipeline guarantees that accessibility preferences take precedence over author intent unless the operator explicitly disables the safeguard.

Overriding Default Behavior

Advanced users and CI pipelines can force animation regardless of system settings by setting an environment variable:

ARCHIFY_REDUCED_MOTION_DISABLED=1 archify deliver diagram.workflow.json

This override is intended for testing, screenshot generation, or controlled environments where the operator confirms that motion is acceptable.

Complete Configuration Examples

Declaring Animation in Diagram JSON

{
  "meta": {
    "locale": "en",
    "animation": "trace",
    "visual_preset": "signal-flow"
  },
  "nodes": [
    { "id": "client", "label": "Web Client" },
    { "id": "api", "label": "API Gateway" }
  ],
  "edges": [
    { "from": "client", "to": "api", "label": "request" }
  ]
}

See the full implementation in archify/examples/agent-tool-call.workflow.json.

Disabling Animation for Accessibility

// Standard viewer inclusion pattern
function initializeDiagram(meta, container) {
  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
  const effectiveAnimation = prefersReducedMotion ? 'none' : meta.animation;
  
  if (effectiveAnimation === 'trace') {
    startTraceAnimation(container);
  } else {
    renderStatic(container);
  }
}

Reference: generated/maka-regenerated.workflow.html, line 7193.

Key Files for Animation Implementation

File	Purpose
archify/schemas/common.schema.json	Defines the animation enum for all diagram types
archify/examples/agent-tool-call.workflow.json	Production example with trace animation enabled
scripts/start-template.html	HTML template containing CSS reduced-motion fallback
generated/maka-regenerated.workflow.html	Generated viewer with runtime media query detection
archify/bin/archify.mjs	CLI entry point handling environment overrides

Summary

• Archify provides two animation modes—"trace" and "none"—controlled via the meta.animation JSON property
• The animation enum is centrally defined in archify/schemas/common.schema.json and enforced during schema validation
• Accessibility is automatic: the viewer checks prefers-reduced-motion and falls back to static rendering without user intervention
• The pipeline respects user preferences through validation, renderer configuration, and client-side execution layers
• Override capability exists via ARCHIFY_REDUCED_MOTION_DISABLED=1 for specialized use cases

Frequently Asked Questions

What happens if I set an invalid animation value in my diagram JSON?

Schema validation fails before rendering begins. The CLI reports an error referencing the enum constraint in common.schema.json, and no output is produced. Valid values are strictly "trace" or "none".

Can users with motion sensitivity still view animated diagrams?

Not by default. When prefers-reduced-motion: reduce is active at the OS or browser level, Archify automatically serves static diagrams regardless of the source file's animation setting. This behavior protects users without requiring them to find a settings panel.

How do I generate screenshots of the animated state for documentation?

Set ARCHIFY_REDUCED_MOTION_DISABLED=1 when running archify deliver. This bypasses the accessibility check and honors the animation: "trace" setting in your source file, allowing capture of the motion-enabled output.

Is the reduced-motion check performed once or continuously?

The check runs at viewer initialization. If a user changes their system preference while a diagram is open, they must reload the page for the new setting to take effect. The CSS fallback in start-template.html applies immediately to any CSS transitions triggered after the change.

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