/visual-report

name: visual-report
description: "Generate visual output — charts, dashboards, and trend graphs — from audit findings, session history, or system health data. Produces an interactive HTML dashboard or a set of SVG/Mermaid charts that make design system health visible at a glance. Trigger when someone says: visualise the findings, show me a chart, create a dashboard, graph the trends, make this visual, health dashboard, show me the data, I need charts for the stakeholder meeting, turn this into a visual report, or anything about producing visual representations of design system data. Do NOT trigger for producing a written stakeholder brief without visuals — use stakeholder-brief for that. Do NOT trigger for running an audit — run the audit skill first, then use visual-report to visualise the output."
references:
  - ../../knowledge-notes/human-oversight-framework.md

Visual Report

A skill for transforming audit findings, system health statuses, and session history into visual outputs — interactive HTML dashboards, SVG charts, and Mermaid diagrams — that make design system health visible at a glance.

**Output type:** File creation. This skill produces HTML dashboard files, SVG chart files, or Mermaid diagram blocks that can be embedded in documentation, presentations, or shared directly.

---

Why this exists

Numbers in a markdown table are accurate. They are also invisible. A stakeholder will not register "System health: 🟡 Functional with two weak dimensions" from a text report. But a radar chart showing dimension statuses — with red zones, amber zones, and green zones — communicates instantly.

Design system health data is inherently visual. Token coverage maps, component dependency graphs, severity distribution pie charts, trend lines over time — these are the natural representations of the data that audit skills produce. This skill bridges the gap between raw findings and visual communication.

Boundaries

This skill visualises existing findings — it does not run audits or generate new data. If no audit output or session history exists, there is nothing to visualise; run the relevant audit skill first. If the request is for a written stakeholder summary rather than a visual artefact, use `stakeholder-brief` instead. This skill produces HTML dashboards, SVG charts, and Mermaid diagrams — if the request is for a slide deck or PDF, the visual output from this skill can feed into those formats but this skill does not produce them directly.

---

Configuration

Check for `.ds-ops-config.yml` in the project root:

visuals:
  brand_primary: "#0052CC"           # Primary colour for charts
  brand_secondary: "#FF5630"         # Accent colour for warnings/critical
  brand_success: "#36B37E"           # Success colour
  brand_neutral: "#6B778C"           # Neutral/baseline colour
  output_format: "html"              # html, svg, or mermaid
  output_directory: ".ds-ops/visuals"

If no configuration exists, use these defaults:

• Primary: `#2563EB` (blue)
• Secondary: `#DC2626` (red)
• Success: `#16A34A` (green)
• Neutral: `#6B7280` (grey)
• Output format: `html`
• Output directory: current working directory

---

Input formats

This skill accepts any of these as input:

1. **Raw skill output** — Copy-pasted or referenced output from any audit skill 2. **Session memory files** — Files from the session-memory skill's directory 3. **System health statuses** — The dimension statuses from system-health 4. **Comparison data** — Before/after data from session-memory comparisons 5. **Manual data** — User-provided metrics in any format (will be normalised)

---

Step 0: Determine the visual type

Based on the input data and the request, select one or more visual types:

Visual types available

| Type | Best for | Format | |---|---|---| | **Health radar** | System health dimension statuses | Radar/spider chart | | **Severity distribution** | Audit findings by severity | Donut chart | | **Trend line** | Metric changes over time | Line chart | | **Coverage heatmap** | Token or component coverage | Grid heatmap | | **Dependency graph** | Component relationships | Mermaid flowchart | | **Comparison bar** | Before/after comparisons | Grouped bar chart | | **Action priority matrix** | Findings by effort vs. impact | Scatter plot | | **Full dashboard** | Multiple visuals on one page | HTML dashboard |

If the request is vague ("make this visual"), choose the visual type that best fits the data:

• System health statuses → Health radar
• Audit findings → Severity distribution + action priority matrix
• Session history → Trend line
• Before/after data → Comparison bar
• Multiple data types → Full dashboard

---

Step 1: Parse and normalise the data

From audit output

Extract:

• Finding IDs, severities, categories
• Metric totals (violation counts, coverage percentages)
• Component names (for dependency graphs)
• Token tiers (for coverage heatmaps)

From session memory

Extract:

• Dates and skill names
• Key metrics per session (aligned for trend lines)
• Deltas between sessions

From system health

Extract:

• Seven dimension statuses (tokens, components, documentation, adoption, governance, AI readiness, platform maturity)
• Overall health status
• Maturity stage

Normalise all data into simple structures:

metrics: [{ label, value, max, category }]
timeseries: [{ date, metric, value }]
findings: [{ id, severity, category, effort, impact }]
relationships: [{ source, target, weight }]

---

Step 2: Generate the visuals

Health radar chart

Produce a radar chart with seven axes (one per system health dimension). Map statuses to numeric values for charting: 🟢 Strong = 3, 🟡 Functional = 2, 🟠 Weak = 1, 🔴 Absent = 0.

Display axis labels using the status names, not numbers. The numeric mapping is internal for chart rendering only.

Colour coding:

• 0 (Absent): Red zone
• 1 (Weak): Amber zone
• 2 (Functional): Yellow-green zone
• 3 (Strong): Gr