Dashboard Visual Specification Framework
How to render data so humans can comprehend it in 30 seconds
Every dashboard panel that contains data must have a Visual Specification. A panel without a visual spec is a panel that a developer will render as a plain table — which defeats the purpose of a dashboard. This framework defines the chart types, libraries, colour standards, interaction patterns, and performance budgets that govern every visualisation in the HIRO system.
Section 1
Visual Specification Template
Every visualisation in the system must be specified using this template. These are the required and optional fields that define how a chart is rendered.
Required Fields
| Field | Type | Description |
|---|---|---|
| viz_id | VARCHAR | Unique identifier (e.g., VIZ-D06-NEBULA) — Dashboard number + short name |
| viz_name | VARCHAR | Human-readable name (e.g., “C-Space Nebula”) |
| dashboard | INTEGER | Which dashboard this belongs to (1–29) |
| panel | ENUM | WORKING (“Is it working?”) or DOING (“What is it doing?”) |
| chart_type | ENUM | The visualisation type (from the Chart Type Library) |
| library | ENUM | The rendering library (from the Approved Library List) |
| data_source | VARCHAR | Where the data comes from (API endpoint, Knowledge Graph query, database table) |
| refresh_rate | ENUM | How often the visualisation updates (from the Refresh Rate Classes) |
| data_mapping | JSON | Which data fields map to which visual dimensions (x, y, z, colour, size, opacity, label) |
| interaction_model | JSON | What happens on click, hover, zoom, drag (from the Interaction Patterns) |
| actionable_links | JSON ARRAY | What clicking a data point triggers (navigation, filter, search, escalation) |
| determinism | JSON | For projections/layouts: fixed seeds, recalculation schedule, caching rules |
| thresholds | JSON | Colour breakpoints, alert triggers, zone boundaries |
| responsive | VARCHAR | How the viz adapts to smaller screens (collapse, scroll, simplify) |
Optional Fields
| Field | Type | Description |
|---|---|---|
| annotations | JSON ARRAY | Static labels, reference lines, zone labels overlaid on the chart |
| empty_state | VARCHAR | What to show when there is no data yet |
| error_state | VARCHAR | What to show when the data source is unavailable |
| performance_budget | VARCHAR | Maximum render time |
Section 2
Chart Type Library
Every visualisation must use one of these approved chart types. This ensures consistency across dashboards and limits the number of rendering patterns developers must implement.
Status & KPI Charts (for “Is it working?” panels)
| Chart Type | When To Use | Example | Library |
|---|---|---|---|
| Traffic Light | Single overall health status (GREEN/YELLOW/RED) | System Health indicator | Custom HTML/CSS |
| Gauge | Single metric with min/max/threshold zones | Budget remaining, verification pass rate | Chart.js (doughnut) |
| Metric Card | Single number with trend arrow and sparkline | “Packets completed today: 14 ↑” | Custom HTML + Recharts sparkline |
| Status Grid | Multiple components each with health indicator | Component Health Grid (10 items) | Custom HTML/CSS grid |
| Progress Bar | Completion percentage for a single dimension | Phase completion: 67% | Custom HTML/CSS |
| Multi-Progress | Multiple progress bars stacked vertically | Phase 0–10 progress bars | Custom HTML/CSS |
Operational Charts (for “What is it doing?” panels)
| Chart Type | When To Use | Example | Library |
|---|---|---|---|
| Pipeline Bar | Sequential status flow with counts at each stage | QUEUED → EXECUTING → VERIFYING → COMPLETED | Custom HTML/CSS |
| Data Table | Structured records that need sorting/filtering/clicking | Live Packet Tracker, Proof Object Registry | React Table or custom |
| Gantt Timeline | Time-based activity with parallel tracks | Execution Timeline (packets over 24 hours) | D3.js |
| Line Chart | Trend over time (single or multi-series) | 30-day spending history, failure rate trend | Recharts |
| Stacked Bar | Composition breakdown over time | Daily cost by agent type | Recharts |
| Pie / Donut | Proportion of a whole (max 6 segments) | Failure type distribution | Recharts |
| Heatmap | 2D matrix with colour intensity | Phase × Status matrix, Symbol × Timeframe grid | D3.js |
| Bubble Chart | 3 dimensions on 2D plane (x, y, size) | 4-Quadrant Concept Heatmap | Plotly |
| 3D Scatter | High-dimensional data projected to 3D | C-Space Nebula (UMAP projection) | Plotly |
| Network Graph | Relationships between entities | Dependency graph, Knowledge Graph explorer | D3.js force layout |
| Sparkline Grid | Many small trend lines in a grid | Per-symbol feed health, per-operator RAR trend | Recharts (inline) |
| Histogram | Distribution of a single variable | Confidence score distribution, latency distribution | Recharts |
| Sankey Diagram | Flow between categories | Packet flow through pipeline stages | D3.js |
Alert & Action Charts
| Chart Type | When To Use | Example | Library |
|---|---|---|---|
| Alert Feed | Scrollable timestamped event list | Active Alerts, Chief Engineer Activity Log | Custom HTML/CSS |
| Action Card | Decision required with option buttons | Escalation Queue items | Custom HTML/CSS |
| Countdown / Timer | Time since event or time remaining | “HARD_HALT active for 2h 14m” | Custom HTML/JS |
Section 3
Approved Rendering Libraries
All dashboards must use these libraries. No others permitted without Architect review. Rule: use the simplest library that achieves the visualisation.
| Library | Version | Use For | Rationale |
|---|---|---|---|
| Recharts | Latest stable | Line, bar, area, pie, sparklines | React-native, lightweight, good for standard 2D charts |
| D3.js | v7 | Gantt, heatmap, network, Sankey, custom layouts | Most flexible for custom visualisations |
| Plotly | Latest stable | 3D scatter, bubble, surface plots | Best 3D interactivity without Three.js complexity |
| Chart.js | v4 | Gauges (doughnut variant), simple charts | Lightweight for single-metric displays |
| Three.js | r128 | Only if Plotly 3D is insufficient | Heavy — avoid unless genuinely needed |
| Custom HTML/CSS | N/A | Traffic lights, status grids, pipeline bars, metric cards, progress bars | No library needed for simple status indicators |
Section 4
Refresh Rate Classes
How often each visualisation updates. Real-time for things that change every second. Session-load for things that change slowly. Daily for computationally expensive projections.
| Class | Frequency | Mechanism | Use For |
|---|---|---|---|
| REALTIME | Every 1–5 seconds | WebSocket push | Agent status, active build progress, system health indicators |
| FREQUENT | Every 30–60 seconds | Polling (setInterval) | Pipeline status, queue depth, budget remaining |
| PERIODIC | Every 5–15 minutes | Polling | Code quality metrics, template registry status, canary results |
| SESSION | On page load + manual refresh | HTTP GET | Historical data, trend charts, proof object registry |
| DAILY | Once per day (scheduled) | Batch computation | UMAP projections, clustering analysis, 30-day aggregates |
Section 5
Interaction Patterns
Every interactive element must use one of these standard patterns.
| Pattern | Trigger | Behaviour | Example |
|---|---|---|---|
| Drill-down | Click on data point | Navigate to a detail view for that entity | Click packet in pipeline → full execution history |
| Filter | Click on category | Filter the current view to show only that category | Click “FAILED” in pipeline bar → show only failed packets |
| Tooltip | Hover over data point | Show detail card with key fields | Hover over agent in pool → show agent_id, current packet, uptime |
| Cross-highlight | Hover in one chart | Highlight related data in adjacent charts | Hover over phase 3 bar → highlight Phase 3 packets in tracker |
| Zoom | Scroll wheel or pinch | Zoom into a region of the chart | Zoom into a cluster in the C-Space Nebula |
| Pan | Click-drag | Move the viewport | Pan across the execution timeline |
| Toggle | Click button/checkbox | Show/hide a data layer | Toggle “Show drift trails” in the Nebula |
| Action | Click button | Trigger a system action | “Approve Repair” button in Escalation Queue |
| Link-out | Click badge | Navigate to a different page | Click section badge → navigate to genesis.html |
Section 6
Colour Standards
Consistent colour usage across all dashboards. Never use rainbow colour maps — they are perceptually non-uniform and mislead human interpretation.
Zone Colours (from dashboard-architecture.html)
| Zone | Primary | Background | Use For |
|---|---|---|---|
| Blue | #185FA5 | #E6F1FB | Data & Awareness dashboards |
| Teal | #0F6E56 | #E1F5EE | Discovery & Intelligence dashboards |
| Green | #3B6D11 | #EAF3DE | Portfolio & Quality dashboards |
| Amber | #854F0B | #FAEEDA | Execution & Cost dashboards |
| Purple | #534AB7 | #EEEDFE | Governance & Configuration dashboards |
| Coral | #993C1D | #FAECE7 | Risk & Failure dashboards |
| Grey | #5F5E5A | #F1EFE8 | System & Infrastructure dashboards |
Semantic Colours (for data encoding)
| Colour | Hex | Meaning | Use For |
|---|---|---|---|
| Success Green | #16a34a | Pass, healthy, complete | Health checks, test passes, completed phases |
| Warning Amber | #d97706 | Caution, degraded, approaching threshold | Budget warnings, slow responses, stale canary |
| Failure Red | #dc2626 | Fail, broken, halt | Failed tests, HARD_HALT, unresponsive agents |
| Active Blue | #2563eb | In progress, executing, busy | Currently building, currently verifying |
| Neutral Grey | #6b7280 | Not started, inactive, no data | Future phases, idle agents, empty states |
| Info Purple | #7c3aed | Diagnostic, analysis, governance | Chief Engineer activity, escalation events |
Continuous Colour Ramps
| Ramp | Use For | Library Reference |
|---|---|---|
| Viridis | Productivity scores, performance metrics (low = purple → high = yellow) | Plotly: colorscale='Viridis', D3: d3.interpolateViridis |
| RdYlGn | Health/quality (red = bad → green = good) | Recharts: custom gradient, D3: d3.interpolateRdYlGn |
| Blues | Density, concentration (light = sparse → dark = dense) | D3: d3.interpolateBlues |
Section 7
Determinism Requirements
The dashboard must look the same if you refresh the page. If a human builds spatial memory, the visualisation must not break that memory on refresh.
| Requirement | Specification |
|---|---|
| UMAP projections | random_state=42. Recalculate DAILY only (not on each page load). Cache the projection result in Redis. |
| DBSCAN clustering | Deterministic (no random seed needed). But input data order must be consistent — sort by entity_id before clustering. |
| D3 force layouts | Use d3.forceSimulation().alphaTarget(0) with a fixed number of iterations (300). Cache final positions. Recompute only when underlying data changes. |
| Network graph layouts | Cache node positions after initial layout. Only recompute when nodes are added or removed. |
| Colour assignment | Categorical colours assigned by deterministic mapping (entity_id → colour index), not by render order. |
Section 8
Performance Budgets
Every visualisation has a maximum render time. If exceeded, it must degrade gracefully — reduce point count rather than freeze the browser.
| Dashboard Complexity | Max Render Time | Max Data Points | Strategy |
|---|---|---|---|
| Simple (gauges, status grids, metric cards) | < 100ms | N/A | Direct DOM rendering |
| Standard (tables, line charts, bar charts) | < 300ms | 1,000 rows | Pagination for tables, windowed rendering |
| Complex (heatmaps, bubble charts, Gantt) | < 500ms | 5,000 points | Canvas rendering, requestAnimationFrame |
| Heavy (3D scatter, network graphs) | < 1,000ms | 10,000 points | WebGL (Plotly/Three.js), level-of-detail |
| Massive (full C-Space with all operators) | < 2,000ms | 50,000 points | WebGL + server-side pre-computation + progressive loading |
Section 9
Empty & Error States
Every visualisation must handle two non-happy-path states. Never show a blank space or a loading spinner that never resolves.
| State | Display | Example |
|---|---|---|
| Empty | Grey placeholder with contextual message explaining why there is no data and what will make data appear | “No operators in C-Space yet. Operators will appear here after the Genesis Process (Phase 7) produces its first generation.” |
| Error | Red-bordered placeholder with the error source and a retry button | “Cannot reach Knowledge Graph (last attempt: 14:32:05). The C-Space Nebula requires Knowledge Graph access. [Retry] [View Health Check]” |
Section 10
Responsive Behaviour
| Screen Width | Behaviour |
|---|---|
| ≥ 1200px | Full 2-column dashboard grid. All charts at full size. |
| 860–1199px | Single column. Charts maintain aspect ratio but fill width. |
| < 860px | Single column. Complex charts (3D, Gantt, heatmap) collapse to summary cards with a “View Full Chart” link. Tables switch to card layout. |
Section 11
Reference Example: C-Space Nebula (VIZ-D06-NEBULA)
This is the reference implementation. All future visual specifications should follow this format.
// ===== C-SPACE NEBULA VISUAL SPECIFICATION =====
viz_id: "VIZ-D06-NEBULA"
viz_name: "C-Space Nebula"
dashboard: 6 // Operator Concept Space
panel: "DOING" // "What is it doing?" panel
chart_type: "3D Scatter"
library: "Plotly"
data_source: {
endpoint: "/api/operators/cspace"
fields: ["operator_id", "embedding_vector", "rar_score", "generation",
"creation_method", "engine_id", "symbol", "status", "trade_count"]
projection: "Server-side UMAP (3D) applied to embedding_vector"
}
refresh_rate: {
class: "DAILY"
projection_recalculation: "Once per day at 00:00 UTC"
point_metadata: "SESSION (refreshed on page load)"
cache: "Redis key: cspace:umap:3d, TTL: 24 hours"
}
data_mapping: {
x: "umap_component_0"
y: "umap_component_1"
z: "umap_component_2"
colour: "engine_id" // categorical — deterministic mapping
size: "rar_score" // continuous — range [2, 12] pixels
// formula: 2 + (rar_score / max_rar) * 10
opacity: "trade_count" // continuous — range [0.3, 1.0]
// formula: 0.3 + min(trade_count / 100, 1.0) * 0.7
label: "operator_id (shown on hover only)"
}
determinism: {
umap_random_state: 42
umap_n_neighbors: 15
umap_min_dist: 0.1
recalculate_trigger: "Daily cron OR population change > 10%"
cache_ttl: "24 hours"
}
interaction_model: {
hover: "Tooltip: operator_id, RAR, generation, creation_method, engine_id, trade_count"
click: "Navigate to /operator/{operator_id} detail page"
zoom: "Plotly scroll-zoom (continuous)"
pan: "Plotly click-drag orbit (3D rotation)"
toggle_fog: "Checkbox: show/hide fog-of-war isosurfaces"
toggle_trails: "Checkbox: show/hide drift trail lines"
}
annotations: [
{ type: "isosurface", label: "Fog of War",
description: "Semi-transparent surfaces around engine cluster centroids. Radius = 2 * std_dev of cluster. Colour = engine colour at 15% opacity." },
{ type: "line", label: "Drift Trails",
description: "Line from operator's position 30 days ago to current position. Colour gradient from grey (old) to engine colour (current). Only shown for operators with > 30 days history." },
{ type: "label", label: "Zone Labels",
description: "Floating text labels at engine cluster centroids: 'Engine {engine_id} ({count} operators)'. Semi-transparent background." }
]
thresholds: {
overcrowded: "Engine cluster with > 50 operators in radius 0.5 UMAP units — highlight boundary in orange"
sparse: "Region with 0 operators within radius 2.0 UMAP units — mark as 'Unexplored' with grey label"
drifting: "Operator with drift trail > 3.0 UMAP units in 30 days — highlight trail in red"
}
actionable_links: [
{ trigger: "Click empty region", action: "Suggest genesis exploration in that C-Space region" },
{ trigger: "Click overcrowded cluster", action: "Navigate to engine detail with retirement candidates" },
{ trigger: "Click sparse region", action: "Navigate to archetype library for similar archetypes" }
]
empty_state: "No operators in C-Space yet. Operators will appear here after the
Genesis Process (Phase 7) produces its first generation."
error_state: "Cannot reach Knowledge Graph (last attempt: {timestamp}).
The C-Space Nebula requires Knowledge Graph access.
[Retry] [View Health Check]"
performance_budget: {
target: "< 2,000ms initial render"
max_points: 50000
degradation_strategy: "If > 10,000 operators: subsample to 10,000 (top RAR per engine).
If > 50,000: server-side pre-render to static image with
hover overlays only."
}
responsive: {
desktop: "Full 3D interactive Plotly chart"
tablet: "2D projection (UMAP components 0 and 1 only), Plotly 2D scatter"
mobile: "Summary card: '{count} operators across {engine_count} engines.
Top RAR: {top_rar}. View full chart on desktop.'"
}