# How the Semantic Lens Compares Roles in Archify Diagrams: A Complete Technical Guide > Explore the Semantic Lens feature in Archify to visualize, filter, and contrast architectural roles with role-based color coding and compare mode. This technical guide offers a complete deep-dive. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: deep-dive - Published: 2026-08-14 --- **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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) at lines 1225–1229, the lens defines `--lens-color` per `data-kind`: ```css [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 ```html
``` 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:** ```js 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** ```js // 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: ```css .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`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) | 1150, 1197–1229, 1300 | CSS rules, markup structure, toggle logic | | [`README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.