# How Archify Trace Animation Supports prefers-reduced-motion: CSS Implementation Guide

> Discover how Archify trace animation supports prefers reduced motion with a simple CSS media query. Learn how to disable animations effortlessly without JavaScript.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: implementation-guide
- Published: 2026-07-14

---

**Archify automatically disables trace animations when users enable prefers-reduced-motion by using a CSS media query that overrides animation properties with `animation: none !important`, requiring zero JavaScript configuration.**

Archify is an open-source diagramming tool that generates SVG visualizations with optional trace animations when the `meta.animation` field is set to `"trace"`. These animations guide viewers through system architecture by drawing edges and pulsing nodes, but the implementation prioritizes accessibility by respecting the user's motion preferences. According to the source code in `tt-a1i/archify`, the trace animation system automatically disables all motion effects when `prefers-reduced-motion: reduce` is detected, ensuring diagrams remain accessible without requiring manual configuration.

## How Trace Animation Works in Archify

### Opt-In Activation via Metadata

In `archify/renderers/shared/cli.mjs` (lines 33-38), the renderer checks the diagram's **meta** configuration for the `animation` key. Only when `meta.animation` equals `"trace"` does the system emit animation-specific attributes. This opt-in approach ensures that static diagrams remain lightweight unless the author explicitly requests animated behavior.

### Generated SVG Attributes

When trace animation is enabled (lines 40-44 of `cli.mjs`), the renderer injects specific data attributes into the SVG output:

- `data-animation="trace"` on the root `<svg>` element
- `data-animate="edge"` or `data-animate="node"` on individual diagram elements
- Inline CSS custom property `--step` for coordinating animation timing

## prefers-reduced-motion Implementation

The accessibility logic resides entirely within [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) (lines 83-88). The built-in stylesheet includes a media query that detects when the user has requested reduced motion:

```css
@media (prefers-reduced-motion: reduce) {
  svg[data-animation="trace"] [data-animate] {
    animation: none !important;
    stroke-dashoffset: 0;
  }
}

```

This rule specifically targets elements within SVGs that have trace animation enabled, forcing `animation: none !important` to override any keyframe animations and resetting `stroke-dashoffset` to 0. This ensures edges appear fully drawn rather than partially animated, maintaining diagram readability while eliminating motion.

## Animation Definitions in CSS

The actual trace animations are defined in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) (lines 59-72):

- **Edge animation**: Uses `stroke-dasharray` and `stroke-dashoffset` with the `archify-edge-flow` keyframe animation (lines 61-66)
- **Node animation**: Applies `archify-node-pulse` with transform origin adjustments (lines 67-72)

Because these animations are CSS-driven rather than SMIL or JavaScript-based, the media query override works reliably across all modern browsers without requiring runtime detection logic.

## Verification and Testing

The test suite in `archify/test/animation.test.mjs` validates both animation emission and accessibility compliance:

- Lines 38-42 verify that omitting the animation meta field produces SVGs without `data-animation` or `data-animate` attributes
- Lines 45-50 confirm that setting `animation: "trace"` correctly injects the required attributes for the trace effect

Run the tests with:

```bash
node archify/test/animation.test.mjs

```

## Practical Examples

### Enabling Trace Animation in Your Diagram

To activate the trace animation, include the animation flag in your diagram's metadata:

```json
{
  "meta": {
    "title": "System Architecture",
    "animation": "trace"
  },
  "lanes": [...],
  "nodes": [...],
  "edges": [...]
}

```

This generates an SVG with the trace attributes:

```html
<svg data-animation="trace" ...>
  <line ... data-animate="edge" style="--step:0"></line>
  <rect ... data-animate="node" style="--step:0"></rect>
</svg>

```

### Automatic Accessibility Compliance

No additional code is required to support `prefers-reduced-motion`. The CSS in the HTML template automatically handles the preference:

```css
@media (prefers-reduced-motion: reduce) {
  svg[data-animation="trace"] [data-animate] {
    animation: none !important;
    stroke-dashoffset: 0;
  }
}

```

When a user's operating system or browser is configured to reduce motion, this media query activates immediately, disabling the `archify-edge-flow` and `archify-node-pulse` animations while maintaining the full integrity of the diagram's visual structure.

## Summary

- **Archify trace animation** is opt-in via the `meta.animation: "trace"` field in diagram definitions
- The implementation in `cli.mjs` generates `data-animation` and `data-animate` attributes only when explicitly requested
- Animation logic resides in CSS within [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html), using standard keyframe animations for edges and nodes
- **prefers-reduced-motion support** is handled entirely through a CSS media query (lines 83-88) that sets `animation: none !important` and resets dash offsets
- No JavaScript is required for accessibility compliance; the browser's native media query handling manages the behavior automatically
- The test suite validates both the presence of animation attributes when enabled and their absence when disabled

## Frequently Asked Questions

### Does Archify require JavaScript to detect prefers-reduced-motion?

No. Archify relies entirely on CSS media queries to handle `prefers-reduced-motion`. The `@media (prefers-reduced-motion: reduce)` block in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) automatically disables animations when the system preference is set, without executing any JavaScript detection code. This approach ensures compatibility with browser settings and assistive technologies that expose this preference at the OS level.

### What happens to the diagram when animations are disabled via prefers-reduced-motion?

When `prefers-reduced-motion: reduce` is active, the diagram remains fully visible and functional. The CSS resets `stroke-dashoffset` to 0 and removes animations via `animation: none !important`, ensuring edges appear completely drawn and nodes remain static rather than pulsing. The visual structure and all diagram information remain intact, only the motion effects are suppressed.

### Can I customize the trace animation speed while maintaining accessibility support?

Yes. The animation timing is controlled through CSS custom properties and keyframe definitions in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) (lines 59-72). However, any customizations should maintain the existing `prefers-reduced-motion` media query structure to ensure accessibility compliance is preserved. The override in lines 83-88 uses the `!important` flag to ensure it takes precedence over any custom timing changes.

### Are animations enabled by default in Archify diagrams?

No. Trace animations are strictly opt-in. According to the source code in `archify/renderers/shared/cli.mjs` (lines 33-38), the renderer only emits animation attributes when the diagram metadata explicitly contains `animation: "trace"`. Without this flag, the output SVG contains no animation-related attributes, ensuring static output by default and avoiding unnecessary motion for users who prefer reduced movement.