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

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 (lines 83-88). The built-in stylesheet includes a media query that detects when the user has requested reduced motion:

@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 (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:

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:

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

This generates an SVG with the trace attributes:

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

@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, 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 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 (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.

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