Define a consistent visual and semantic language for Explorer graphs

[MuttleyD]

Context

Explorer uses graph views to help users understand MIDAS governance structures, including Context Graph and Authority Graph views.

As Explorer grows to include context, authority, evidence, drift, operational measures, and future knowledge views, it needs a consistent visual and semantic language. Users should be able to understand what nodes, connectors, actions, badges, overlays, and graph controls mean without relearning the interface in each graph.

This is especially important because Explorer is intended to become an operational governance surface, not just a visual demo.

Problem

Graph views can become confusing if each view uses different conventions for:

• node types;
• connector styles;
• connector direction;
• edge labels;
• status badges;
• action menus;
• selected states;
• hover states;
• warning/error/drift indicators;
• toolbar actions;
• inspector behaviour.

A consistent graph language will make Explorer easier to use, easier to extend, and easier to validate.

Scope

Define and begin implementing a consistent visual and semantic language for Explorer graph views.

The work should assess existing graph surfaces and propose a reusable graph design contract covering:

• node type representation;
• connector/edge styles;
• edge direction and labels;
• selected, hovered, focused, and disabled states;
• node status badges;
• warning, risk, drift, and evidence indicators;
• graph toolbar actions;
• node-level action surfaces;
• inspector panel behaviour;
• empty, loading, and error states;
• light and dark mode consistency.

The design should include the “more actions” ellipsis pattern for node-specific actions where appropriate. The ellipsis should be positioned consistently on graph node cards, aligned to the right and centred vertically.

Acceptance Criteria

• Existing Explorer graph views are assessed for visual and semantic inconsistencies.
• A documented graph visual language or graph UI contract is added to the repo.
• The document defines how common graph elements should behave and appear across Context Graph, Authority Graph, and future drift/knowledge views.
• Connector semantics are explicitly defined, including direction, relationship meaning, and label usage.
• Node action affordances are defined, including the ellipsis pattern for node-specific actions.
• The design accounts for both light and dark mode.
• The design avoids breaking existing Cytoscape-native graph correctness.
• The design recognises that HTML overlays are for richer presentation, not a substitute for correct graph layout and semantics.
• At least one small implementation alignment is made if appropriate and low risk.
• Existing graph behaviour is not regressed.
• git diff --check passes.

Out of Scope

• Full Explorer redesign.
• Replacing Cytoscape.
• Replacing current graph layout algorithms.
• Implementing all future graph views.
• Building the complete drift graph.
• Adding new backend graph APIs unless clearly required.
• Large visual rebranding.