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

> Explore Archify's animation modes trace and none. Learn how Archify ensures accessibility with automatic reduced motion for diagrams.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) (lines 13-15), the `animation` field is defined as:

```json
{
  "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:

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

```

Notable examples include:

- [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json) — AI agent workflow with trace animation enabled
- [`archify/examples/production-deployment.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/production-deployment.architecture.json) — System architecture diagram with flow visualization

These files validate against the schema in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/generated/maka-regenerated.workflow.html) (line 7193), the detection logic follows this pattern:

```javascript
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:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) (line 174) includes a global CSS safeguard:

```css
@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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
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

```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`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json).

### Disabling Animation for Accessibility

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/generated/maka-regenerated.workflow.html), line 7193.

## Key Files for Animation Implementation

| File | Purpose |
|------|---------|
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Defines the `animation` enum for all diagram types |
| [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json) | Production example with trace animation enabled |
| [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) | HTML template containing CSS reduced-motion fallback |
| [`generated/maka-regenerated.workflow.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/start-template.html) applies immediately to any CSS transitions triggered after the change.