How to Configure Optional Animation Settings in Archify JSON Meta

Set the "animation" property inside the meta object to "trace" for a brief line-drawing animation, "none" to explicitly disable motion, or omit the field entirely for a completely static diagram.

Archify renders architecture diagrams from typed JSON definitions, where the top-level meta object controls presentation behavior. Configuring optional animation settings in Archify JSON meta involves adding a standard enum field that determines whether the renderer produces a dynamic trace effect or a static image. According to the tt-a1i/archify source code, this setting applies across all diagram types including architecture, workflow, sequence, dataflow, and lifecycle.

Understanding the Meta Animation Schema

The animation configuration is defined in archify/schemas/architecture.schema.json at lines 19–20, where meta.animation is typed as a strict enum.

Valid values include:

• "trace" – Enables a finite line-drawing animation that plays once when the diagram loads
• "none" – Explicitly disables all motion while keeping the field present in the schema

If you omit the animation key entirely, the renderer defaults to a truly static output with no motion whatsoever. The README documentation at lines 24–27 confirms this behavior, noting that absence of the field results in static generation suitable for CI pipelines and PDF exports.

Animation Options Explained

Trace Animation ("trace")

Setting "animation": "trace" enables a short, non-intrusive line-drawing effect that traces connections between components. This finite animation respects users' prefers-reduced-motion accessibility settings and is ideal for presentations, demos, or interactive documentation where you want to draw attention to data flow without overwhelming the viewer.

Static Output ("none" or Omitted)

To generate a pure static diagram, either omit the animation field completely or explicitly set "animation": "none". The explicit "none" value documents your intent to disable motion, while omission achieves the same result through schema defaults. This approach is recommended for static documentation, print exports, version-controlled assets, and automated build pipelines where deterministic output is required.

Practical Configuration Examples

Static Diagram (Default Behavior)

Omitting the animation key produces a static diagram suitable for documentation:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Static Production Architecture",
    "visual_preset": "classic"
  },
  "components": [
    {
      "id": "api-gateway",
      "type": "service",
      "label": "API Gateway"
    }
  ]
}

Animated Diagram with Trace Effect

Enable the trace animation for presentation contexts:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Animated System Overview",
    "visual_preset": "signal-flow",
    "animation": "trace"
  },
  "components": [
    {
      "id": "load-balancer",
      "type": "infrastructure",
      "label": "Load Balancer"
    }
  ]
}

Explicitly Disabled Animation

Use the explicit "none" value to document that animation is intentionally disabled:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "CI Pipeline Diagram",
    "visual_preset": "blueprint",
    "animation": "none"
  },
  "components": [
    {
      "id": "build-server",
      "type": "compute",
      "label": "Build Server"
    }
  ]
}

Use Cases and Accessibility Considerations

The production-deployment.architecture.json example in the repository demonstrates production usage of "animation": "trace" for interactive environments. However, consider your deployment context when configuring this setting:

• Use "trace" for web presentations, interactive demos, or live documentation where motion adds explanatory value
• Use "none" or omission for automated documentation generation, PDF exports, printed runbooks, or environments where motion could distract or cause accessibility issues

The Archify renderer automatically detects prefers-reduced-motion user preferences, ensuring that trace animations do not violate accessibility standards even when enabled in the configuration.

Summary

• The animation setting resides in the meta.animation field of any Archify JSON diagram definition
• Valid enum values are "trace" for finite line-drawing animation and "none" for explicit static output
• Omitting the field entirely produces a truly static diagram, which is the default behavior
• Configure "trace" for presentations and "none" (or omission) for CI pipelines, PDFs, and static documentation
• Schema validation occurs in archify/schemas/architecture.schema.json

Frequently Asked Questions

What are the valid values for the animation field in Archify JSON?

The meta.animation field accepts only two string values according to the schema defined in archify/schemas/architecture.schema.json: "trace" for a finite line-drawing animation and "none" for explicitly disabled motion. Any other value will fail schema validation.

Does Archify respect system reduced motion preferences?

Yes. When you configure "animation": "trace", the renderer automatically checks for the user's prefers-reduced-motion setting. If the user has indicated they prefer reduced motion, the animation will not play even though it is enabled in the configuration.

What happens if I completely omit the animation field from the meta object?

Omitting the animation field produces a completely static diagram with no motion. According to the README documentation at lines 24–27, this is the recommended approach for generating assets where motion is undesirable, such as in CI/CD pipelines or static documentation sites.

Where can I find production examples of animated Archify configurations?

The repository includes archify/examples/production-deployment.architecture.json, which demonstrates the practical use of "animation": "trace" in a real-world diagram definition. This file serves as the reference implementation for enabling presentation-friendly animations while maintaining schema compliance.

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