How the Semantic Lens Compares Roles in Archify Diagrams: A Complete Technical Guide

The Semantic Lens is a UI overlay that uses role-based color coding, interactive swatches, and dedicated compare mode to let you visualize, filter, and contrast architectural roles across an entire Archify diagram.

The Semantic Lens transforms abstract architectural taxonomy into an interactive exploration tool. In experiments/mco-showcase/mco-runtime.html, this feature maps each node's semantic data-kind to a distinct visual identity—letting you instantly see where frontend, backend, database, and other roles cluster, connect, or dominate the system. Below is a complete breakdown of how the lens performs role comparison, with implementation details from the Archify source code.

---

Role-Based Color Coding System

Every role receives dedicated CSS custom property mapping that propagates through the diagram.

In experiments/mco-showcase/mco-runtime.html at lines 1225–1229, the lens defines --lens-color per data-kind:

[data-kind="frontend"]  { --lens-color: var(--frontend-stroke); }
[data-kind="backend"]   { --lens-color: var(--backend-stroke); }
[data-kind="database"]  { --lens-color: var(--database-stroke); }
[data-kind="cloud"]     { --lens-color: var(--cloud-stroke); }
[data-kind="messagebus"]{ --lens-color: var(--messagebus-stroke); }
[data-kind="security"]  { --lens-color: var(--security-stroke); }

This color system enables instant visual comparison: similar roles share hue families, while contrasting roles pop for relationship tracing.

---

Interactive Swatch Panel for Role Selection

The lens exposes a compact legend UI built from the .semantic-lens-kinds container (lines 1197–1206). Each .semantic-lens-kind button carries a data-kind attribute that wires to the CSS above.

Key UI behaviors:

• Hover/preview: Highlights matching nodes while dimming others
• Click/toggle: Adds or removes data-kind-visible state to filter the diagram
• ARIA support: Buttons maintain aria-pressed for accessibility state

<section class="semantic-lens-kinds">
  <button class="semantic-lens-kind" data-kind="frontend">Frontend</button>
  <button class="semantic-lens-kind" data-kind="backend">Backend</button>
  <button class="semantic-lens-kind" data-kind="database">Database</button>
  <button class="semantic-lens-kind" data-kind="cloud">Cloud</button>
  <button class="semantic-lens-kind" data-kind="messagebus">Message-Bus</button>
  <button class="semantic-lens-kind" data-kind="security">Security</button>
</section>

The swatch's visual chrome inherits --lens-color through CSS, keeping the legend synchronized with the diagram.

---

Visibility Toggling and Overlay State

Role comparison requires granular visibility control. The lens implements this through attribute-driven CSS and lightweight JavaScript.

Attribute mechanism:

Attribute	Effect	CSS Selector
hidden on swatch	Dim nodes to 34% opacity	.semantic-lens-kind[data-kind="frontend"][hidden]
data-kind-visible on root	Globally show/hide a role type	Controlled via script around line 1300
hidden on .semantic-lens	Collapse entire overlay	.semantic-lens[hidden] { display:none; }

JavaScript toggle implementation:

document.querySelectorAll('.semantic-lens-kind').forEach(btn => {
  btn.addEventListener('click', () => {
    const kind = btn.dataset.kind;
    const root = document.querySelector('.diagram-container');
    const hidden = root.dataset[`hide${kind}`] === 'true';
    root.dataset[`hide${kind}`] = !hidden;
    btn.setAttribute('aria-pressed', !hidden);
  });
});

This pattern lets you isolate role combinations—show only frontend and backend, hide infrastructure layers, or spotlight security boundaries.

---

Dedicated Compare Mode for Cross-Role Analysis

Beyond individual toggling, the Semantic Lens supports bidirectional role comparison through a dedicated compare mode.

Activation flow:

1. User clicks #btn-semantic-lens-compare (line 1123)
2. Script sets data-compare-kinds="frontend,backend" on the diagram container
3. Rendering layer highlights only edges connecting the two selected roles

// Compare Frontend vs Backend interactions
document.getElementById('btn-semantic-lens-compare')
  .addEventListener('click', () => {
    const diagram = document.querySelector('.diagram-container');
    diagram.dataset.compareKinds = 'frontend,backend';
  });

What compare mode reveals:

• Dependency direction: Which role initiates calls versus receives them
• Coupling density: How many edges span the two roles
• Bottleneck identification: Single points where roles interface

This mode answers critical architecture questions: Does every frontend path go through the security layer? Which backend services lack database connections?

---

Dockable Overlay Positioning

The lens maintains visibility during diagram navigation through flexible docking. The data-dock-side attribute controls positioning:

.semantic-lens[data-dock-side="left"] {
  left: 1rem;
  right: auto;
}
.semantic-lens[data-dock-side="right"] {
  right: 1rem;
  left: auto;
}

This ensures the comparison panel remains accessible while you pan and zoom through large system diagrams.

---

Implementation Files Reference

File	Lines	Responsibility
experiments/mco-showcase/mco-runtime.html	1150, 1197–1229, 1300	CSS rules, markup structure, toggle logic
README.md	—	Conceptual overview of semantic kinds

---

Summary

The Semantic Lens compares roles in Archify diagrams through four integrated mechanisms:

• Color coding: CSS custom properties bind data-kind to visual identity
• Swatch interaction: Clickable legend enables individual role filtering
• Compare mode: Bidirectional role selection isolates cross-role dependencies
• Dockable UI: Persistent overlay positioning supports exploration at any zoom level

Together, these features transform static architecture diagrams into interactive role analysis tools grounded in the actual data-kind taxonomy defined in the source code.

---

Frequently Asked Questions

How does the Semantic Lens know which color to assign each role?

The lens reads each node's data-kind attribute and maps it to a CSS custom property --lens-color defined in experiments/mco-showcase/mco-runtime.html. Each supported kind—frontend, backend, database, cloud, messagebus, security—has a dedicated rule linking it to a stroke color variable.

Can I compare more than two roles at once?

Yes. The standard swatch toggling lets you activate any combination of roles. The dedicated "compare mode" specifically highlights edges between exactly two selected roles, but you can extend the data-compare-kinds format or chain multiple toggle states for broader comparison.

Where is the lens visibility state stored?

State lives in data-* attributes on the diagram container root element, not in JavaScript variables. This attribute-driven architecture lets CSS handle most visual updates without JavaScript repaint cycles, improving performance on large diagrams.

What happens if a node has no recognized data-kind?

Unrecognized kinds fall back to default styling without --lens-color assignment. They remain visible but uncolored in the lens overlay and won't appear in the swatch panel, which is populated from a predefined list in the HTML markup.

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