How to Configure Legend Mode in Archify: 3 Methods Explained

Archify's legend mode can be activated via the UI toggle, URL hash parameters, or programmatically using Archify.lens.select(), which manipulates the data‑legend‑preview‑active attribute to highlight specific diagram elements.

Archify's diagram viewer includes a powerful legend mode that enables interactive preview of semantic groups directly within SVG diagrams. This feature, part of the Semantic Lens component, allows users to isolate and highlight specific architecture components by activating legend entries. Whether you are building automated documentation workflows or creating interactive system architecture diagrams, understanding how to configure legend mode in Archify is essential for controlling the viewer experience.

Activating Legend Mode via the UI Button

The most straightforward way to configure legend mode is through the Legend toggle in the Lens panel. This interface, defined in viewer/template.source.html, provides visual controls for selecting and previewing legend entries.

To activate legend mode through the UI:

1. Click the Lens button in the diagram viewer toolbar.
2. Select the Legend tab to view available legend entries.
3. Click a specific legend entry to activate preview mode for that kind.

When activated, Archify adds the data‑legend‑preview‑active attribute to the SVG element and updates the button labels and ARIA attributes accordingly. The viewer/semantic-lens.js file implements this interaction, populating the legend entries and managing the state transition.

Using URL Hash Parameters for Direct Activation

For linking directly to a specific legend state, Archify supports URL hash parameters that activate legend entries on page load or when the hash changes.

Append #lens=<kind> to the URL, where <kind> corresponds to a data‑legend‑kind value present in the SVG:

https://example.com/diagram.html#lens=backend

This method is particularly useful for sharing specific diagram views or integrating Archify into documentation systems. The hash change listener in the viewer automatically triggers the same state updates as the UI button, setting the data‑legend‑preview‑active attribute without requiring manual JavaScript interaction.

Programmatic API Control

For custom tooling, automated testing, or advanced integrations, Archify exposes a JavaScript API to control legend mode directly.

Using Archify.lens.select()

The high-level API method provided by viewer/semantic-lens.js allows you to activate a specific legend entry by its kind identifier:

// Activate preview for the "backend" legend entry
Archify.lens.select('backend');

Direct DOM Manipulation

For low-level control, you can manipulate the SVG attributes directly. This approach bypasses the UI state management but triggers the same downstream effects in the Motion Governor:

// Directly set the preview attribute on the SVG
const svg = document.querySelector('.diagram-container svg');
svg.setAttribute('data-legend-preview-active', 'backend');

Both methods result in the Motion Governor detecting the legend owner and updating the motion button state accordingly.

Motion Governor and Accessibility Integration

When legend mode is active, the Motion Governor (viewer/motion-governor.js) detects the legend state by checking for the data‑legend‑preview‑active attribute:

// motion-governor.js – owner detection (line 50)
if (svg.hasAttribute('data-legend-preview-active')) return 'legend';

If the user's system prefers reduced motion, the legend preview automatically pauses, and the motion button displays the "reduced‑motion" label via the reducedMotion() function in motion-governor.js. The viewer/viewer-chrome-layout.js file observes these changes to prevent layout overlap between the legend panel and diagram navigation controls.

Handling Legend Attributes During Export

When exporting SVGs from Archify, temporary legend attributes are automatically cleaned up. The viewer/export-cleanup.js file strips data‑legend‑preview‑* attributes from the exported markup, ensuring clean, production-ready assets without internal preview states.

Summary

• Three activation methods: Configure Archify legend mode through the UI toggle, URL hash (#lens=<kind>), or JavaScript API (Archify.lens.select()).
• Core attribute: Legend mode relies on the data‑legend‑preview‑active SVG attribute, managed by viewer/semantic-lens.js.
• Motion integration: The Motion Governor (viewer/motion-governor.js) detects legend state at line 50 and handles reduced-motion preferences automatically.
• Clean exports: The export pipeline (viewer/export-cleanup.js) removes temporary legend attributes to ensure clean SVG output.

Frequently Asked Questions

What is the data-legend-preview-active attribute?

The data‑legend‑preview‑active attribute is an HTML data attribute added to the SVG element when legend mode is active. According to viewer/semantic-lens.js, this attribute stores the current legend kind identifier (e.g., "backend") and serves as the source of truth for the Motion Governor and other viewer components to detect active legend states.

How does Archify handle reduced motion preferences in legend mode?

When a user’s system prefers reduced motion, Archify automatically pauses legend previews and updates the motion button to display a "reduced‑motion" label. This behavior is implemented in the reducedMotion() function within viewer/motion-governor.js, which checks system preferences alongside the legend state detection logic.

Can I activate multiple legend entries simultaneously?

Based on the current implementation in viewer/semantic-lens.js, Archify stores a single value in the data‑legend‑preview‑active attribute. The system is designed to preview one legend kind at a time. To view multiple groups simultaneously, you would need to implement custom filtering logic outside the standard legend mode API.

How are legend attributes handled during SVG export?

The viewer/export-cleanup.js file automatically strips all temporary legend attributes (specifically those matching data‑legend‑preview‑*) from the SVG before export. This ensures that exported diagrams do not contain internal preview states or temporary UI metadata, resulting in clean, portable SVG files.

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