Visual Report

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

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): Green zone

Implementation: Use Chart.js radar chart in HTML, or SVG polygon construction.

Severity distribution chart

Produce a donut chart showing the distribution of findings by severity.

Ring segments:

• Critical: Red (brand_secondary)
• High: Orange (#F59E0B)
• Medium: Amber (#D97706)
• Low: Blue (brand_primary)
• Info: Grey (brand_neutral)

Centre text: Total finding count.

Implementation: Chart.js doughnut, or SVG arc paths.

Trend line chart

Produce a line chart with time on the X axis and the metric on the Y axis. One line per metric being tracked.

Include:

• Data points marked with circles
• Hover tooltips with exact values
• A target line if configured
• Positive/negative trend annotation

Implementation: Chart.js line chart in HTML.

Coverage heatmap

Produce a grid where:

• Rows = token categories or component areas
• Columns = coverage dimensions (primitive, semantic, component, documented, tested)
• Cells = colour-coded by coverage status (green = covered, amber = partial, red = missing, grey = not applicable)

Implementation: HTML table with CSS background colours, or SVG grid.

Dependency graph

Produce a Mermaid flowchart showing component relationships:

graph TD
    Button["Button (fan-in: 12)"]
    Card["Card (fan-in: 8)"]
    Modal["Modal (fan-in: 5)"]
    Button --> Card
    Button --> Modal
    Card --> ProductCard["ProductCard"]
    Card --> UserCard["UserCard"]

Colour nodes by health status if data is available. Use line thickness to indicate dependency weight.

Implementation: Mermaid.js syntax block.

Comparison bar chart

Produce grouped bars showing before/after values for each metric. One group per metric (e.g., violations, critical count, coverage %).

Colour coding:

• Improved metrics: Green bars (after < before for violations; after > before for coverage)
• Worsened metrics: Red bars
• Unchanged metrics: Grey bars

Include delta labels above each bar group: "↓ 33%" or "↑ 5%"

Implementation: Chart.js grouped bar chart in HTML.

Action priority matrix

Produce a scatter plot where:

• X axis = Effort (Low → High)
• Y axis = Impact (Low → High)
• Each dot = one finding, sized by severity
• Quadrants labelled: "Quick wins" (low effort, high impact), "Strategic investments" (high effort, high impact), "Fill-ins" (low effort, low impact), "Consider carefully" (high effort, low impact)

Implementation: Chart.js scatter chart with quadrant overlays in HTML.

Full dashboard

Combine multiple charts into a single HTML page with:

• A header showing system name, date, and overall health status
• A grid layout (2 columns on desktop, 1 column on mobile)
• Charts sized proportionally
• A summary section at the top with 3–5 key metric cards
• An interactive filter (if session history data is present): dropdown to switch between sessions

Implementation: Single self-contained HTML file with Chart.js loaded from CDN. No external dependencies beyond Chart.js. All data embedded inline.

Step 3: Build the HTML dashboard (for full dashboard mode)

The dashboard is a single HTML file. Structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[System Name] — Design System Health Dashboard</title>
  <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
  <style>
    /* Inline styles — no external CSS */
    /* Use CSS Grid for layout */
    /* Responsive: 2 columns above 768px, 1 column below */
    /* Cards with subtle shadows for key metrics */
    /* Colour variables from config or defaults */
  </style>
</head>
<body>
  <header>
    <!-- System name, date, overall health status badge -->
  </header>
  <section class="metrics-cards">
    <!-- 3–5 key metric summary cards -->
  </section>
  <section class="charts-grid">
    <!-- Individual chart containers -->
  </section>
  <footer>
    <p>Generated by Design System Ops — visual-report</p>
    <p>[Date]</p>
  </footer>
  <script>
    // All chart configuration inline
    // Data embedded as JS objects
    // Chart.js instantiation for each chart
  </script>
</body>
</html>

Key metric cards

Each card shows:

• Metric label (e.g., "Total violations")
• Current value (large font)
• Delta from previous session (if available, with arrow and colour)
• Sparkline trend (if 3+ data points available)

Responsive behaviour

• Desktop (>768px): 2-column grid for charts, 3–5 cards in a row
• Tablet (768px): 2-column grid for charts, cards wrap to 2 per row
• Mobile (<768px): Single column, cards stack vertically

Colour accessibility

• Never rely on colour alone to convey meaning
• Use patterns (dashed lines for targets, solid for actuals)
• Use labels on all chart segments
• Ensure contrast ratio ≥ 4.5:1 for all text
• Include a text-based summary below each chart for screen readers

Step 4: Output

For HTML dashboard

Save the file to the configured output directory: [output_directory]/[system-name]-dashboard-[YYYY-MM-DD].html

For individual charts (SVG)

Save each chart as a separate SVG file: [output_directory]/[chart-type]-[YYYY-MM-DD].svg

For Mermaid diagrams

Output the Mermaid syntax block inline in the conversation (for embedding in markdown documentation).

For all formats

Also output a text-based summary of what the visuals show, so the findings are accessible without viewing the visual output:

Dashboard generated: agds-dashboard-2026-03-09.html

What the visuals show:
- Health radar: Strongest in Tokens (🟢 Strong), weakest in Documentation (🟠 Weak)
- Severity distribution: 12 findings — 2 Critical, 4 High, 4 Medium, 2 Low
- Trend: Violations decreased 33% since January
- Coverage: Feedback token category has zero coverage across all tiers
- Priority: 3 findings in the "Quick wins" quadrant — TA-04, NA-02, CA-11

Integration with other skills

As a follow-up to any audit skill

After any audit completes, suggest: "Run visual-report to generate charts from these findings."

As part of the full-system-diagnostic agent

The diagnostic agent can chain visual-report after Phase 4 to auto-generate a dashboard from the full diagnostic output.

As a companion to stakeholder-brief

When generating a stakeholder brief, suggest: "Run visual-report first and attach the dashboard to the brief."

With session-memory

Load session history from memory files to produce trend lines across multiple runs.

Quality checks

• All charts render correctly in a standard browser (Chrome, Firefox, Safari)
• No external dependencies beyond Chart.js CDN
• Colours pass WCAG AA contrast ratios
• Text summaries accompany every visual
• Dashboard is responsive across desktop, tablet, and mobile
• Data embedded inline — no external data fetches
• File saved to correct directory with correct naming convention
• Mermaid diagrams use valid syntax that renders in GitHub, GitLab, and Notion
• Provenance marker present: "Generated by Design System Ops — visual-report"