UI / UX Design — Design Reference¶
Overview¶
The Substrate UI is a graph-centric interface for engineering teams. Its central challenge is the "hairball problem": a naively rendered graph of a real engineering organization is an impenetrable tangle of nodes and edges that conveys no information. The UI solves this through progressive disclosure and semantic zoom — the same techniques used by cartographic applications to show a continent at one zoom level and a street intersection at another.
Every screen in the Substrate UI serves a specific persona and use case. The UI is not a generic graph browser; it is a purpose-built governance and intelligence interface.
Progressive Disclosure and Semantic Zoom¶
The hairball problem arises when all graph data is rendered simultaneously. A 500-service organization with 2,000 dependencies rendered at full resolution produces an image that communicates less than a single aggregated health badge.
Substrate's approach uses three complementary strategies:
Data-Level Filtering and Aggregation¶
Before any pixel is rendered, the data layer applies: - Domain clustering: Services are grouped into domain super-nodes. Only domain-level aggregates are loaded initially. - Confidence filtering: Nodes below the configured confidence threshold (default 0.60) are hidden by default; a toggle exposes them with visual dimming. - Violation filtering: Users can filter to show only nodes and edges involved in active violations, dramatically reducing visual noise for governance workflows. - Temporal filtering: The graph can be scoped to a time window (e.g., "changes in the last 7 days"), showing only nodes and edges added, modified, or removed in that period.
Geometry-Level Hierarchical Edge Bundling¶
At the rendering layer: - Hierarchical edge bundling: Edges between nodes in the same domain cluster are routed along the cluster boundary rather than drawn individually. This reduces visual clutter from O(n²) edge spaghetti to O(k) bundle routes, where k is the number of inter-domain relationships. - ELK.js Sugiyama layout: The layered Sugiyama layout algorithm enforces edge directionality in the DAG, making dependency flow visually unambiguous (dependencies flow downward, callers are above callees). - Force-directed intra-cluster layout: Within an expanded domain cluster, React Flow's force-directed layout positions services by their relationship density, naturally clustering tightly-coupled services together.
Image-Level LOD Rendering¶
Level-of-detail rendering adapts what is drawn based on zoom level: - Far zoom: domain super-nodes only — single rounded rectangle per domain with aggregate health badge - Mid zoom: individual service nodes with tension rings and violation badges; edges as curves - Close zoom: module and function nodes; internal edges as fine lines; code metrics visible
Technology Stack¶
| Concern | Technology | Rationale |
|---|---|---|
| Graph rendering | React Flow + ELK.js | React Flow handles up to ~1,000 nodes comfortably with SVG; ELK.js provides the Sugiyama/layered layout algorithm for dependency DAGs |
| Charts | Recharts | Drift trends, coverage sparklines, velocity charts; composable SVG charting with React |
| Policy editor | CodeMirror 6 | Rego syntax highlighting and OPA syntax validation; extensible via CodeMirror's modular language support |
| Framework | React 19 + TypeScript | React 19 concurrent rendering for non-blocking graph updates; TypeScript for graph data type safety |
| Design System | Obsidian Atlas (Custom CSS) | Warm-toned, grain-textured design system. No external UI libraries. |
| State management | Zustand | Lightweight; graph viewport state, filter state, and selected node state without Redux boilerplate |
Design System (Obsidian Atlas)¶
"The Immortal Senior" · Quad-Engine Knowledge Architecture
A warm-toned, grain-textured dark-first design system built for a knowledge architecture platform. No external UI libraries — pure CSS custom properties, semantic class abbreviations, and meticulous typographic layering.
Aesthetic Direction¶
Tone: Industrial-luxury with archival warmth. Dark backgrounds with brown/amber undertones rather than cool grays. The feel is a leather-bound operational dashboard — dense, precise, and alive with pulsing health indicators.
Grain overlay: A subtle SVG fractal-noise texture covers the entire viewport at 0.4 opacity (body::after), giving surfaces a tactile, slightly analog quality. This is non-negotiable — it's core to the visual identity.
Corner radii: Consistent rhythm of 6px (buttons, inputs), 8px (cards, code blocks), 10px (panels), 12px (auth cards).
Color Tokens¶
| Token | Dark | Light | Purpose |
|---|---|---|---|
--bg |
#0A0908 |
#EDE8DF |
Page background |
--panel |
#131210 |
#FEFCF9 |
Card/panel backgrounds |
--tx |
#E4DDD4 |
#1C1813 |
Primary text |
--acc |
#5A9DD0 |
#1A4A7A |
Accent/primary action |
Typography¶
Three font stacks, each with a distinct role:
- Display — Fraunces: Used for page titles, dashboard greetings, engine card names, and logo text.
- Body — Instrument Sans: Default for all UI text. Base:
13px. - Data — JetBrains Mono: Used for metric values, code blocks, and timestamps.
Semantic Zoom Levels¶
| Zoom Level | What Is Shown | Data Displayed | Primary Interactions |
|---|---|---|---|
| Far (Domain) | Domain super-nodes as rounded rectangles | Aggregate health badge (red/yellow/green), violation count delta, structural tension score for the domain | Click to expand domain; hover for domain scorecard popover |
| Mid (Service) | Individual service nodes as labeled circles | Tension ring (colored border indicating worst-case state), violation badge count, primary owner, criticality score | Right-click context menu (drill down, simulate); drag to simulation panel |
| Close (Component) | Module nodes, function nodes, internal edges | Function names, call counts, test coverage percentage, tech debt indicators, last modified | Click function for root cause context in violation panel |
Dashboard Patterns¶
Traffic Light Topology¶
Every service node displays a colored ring indicating its worst-case governance state:
- Green: No active violations; tension score below threshold
- Yellow: Active soft violations (warnings) or tension score above threshold but below critical
- Red: Active hard violations (policy blocks) or critical structural tension
Drill-Down Hierarchy¶
The UI enforces a consistent drill-down path across all screens:
Executive Summary (system-wide health)
→ Domain/Team View (per-domain scorecards)
→ Service View (individual service detail, dependencies, violations)
→ Component Detail (module/function level, root cause context)
Key Screens¶
- Architecture Graph: The central viewport with full progressive-disclosure graph.
- PR Check Detail: Structural diff of graph changes introduced by a PR.
- Institutional Memory Timeline: Chronological view of captured decisions, post-mortems, and ADRs.
- Simulation Panel: "Before/after" what-if analysis without modifying production.
- Drift and Alerts Dashboard: Real-time operational view of domain health and alerts.
- Verification Queue: Task inbox for graph data that requires human review.
- Policy Authoring: Interface for Architects to write, test, and publish OPA/Rego policies.