/visual-report

name: visual-report
description: "Turns existing audit or health output, or saved recurring runs, into an HTML dashboard, SVG charts or Mermaid diagrams. Triggers: visualise the findings, dashboard, chart, graph the trends. Does not run audits (run one first); for a written brief use stakeholder-brief."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(sort:*), Bash(tail:*), Bash(wc:*), Bash(npm view:*)
references:
  - ../../knowledge-notes/output-discipline.md

Visual Report

A skill for transforming audit findings, system health statuses, and saved recurring runs 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.

---

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

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

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

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: `.ds-ops/visuals` (the same as the config default, so a run with and without a config file lands in the same place)

---

Input formats

This skill accepts any of these as input:

1. **Raw skill output** — Copy-pasted or referenced output from any audit skill 2. **Saved reports** — previous runs in `recurring.output_directory`, for trend lines 3. **System health statuses** — The dimension statuses from system-health 4. **Comparison data** — the trend section a recurring run adds to its report 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 | |---|---|---| | **Status strip** | System health dimension statuses | One tile per dimension, coloured by status | | **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 → Status strip
• 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 saved recurring runs

Extract:

• Dates and skill names
• Key metrics per run (aligned for trend lines)
• Deltas between runs, from each report's trend section

From system health

Extract:

• The dimension statuses the report has (system-health has seven; don't assume, read them)
• 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? }]