docs-chart

Inline Data Visualization Charts Skill

When to apply

Use inline SVG charts when nexus-agents docs reference quantitative data:

Data source	Best chart type
OutcomeStore success-rate-by-CLI	Horizontal bar
Per-call cost from usage-log.jsonl	Donut (per model)
Fitness audit history (target ≥ 90/100)	Line chart
CLI success rate over time	Line / area
Voter approval distribution	Lollipop
Cost-per-success comparison	Grouped bar
Multi-dimensional model scoring (reasoning / speed / cost / quality)	Radar

Mermaid handles sequence / state / flow diagrams (see docs-mermaid), but renders quantitative charts ugly and inflexibly. SVG is the right tool for "compare these numbers." Each rendered chart is dark-mode- compatible (uses currentColor for text + transparent backgrounds) and includes a role="img" + aria-label for accessibility.

Step 1 — Identify the chart type

Look at the data pattern:

Pattern	Chart type
Before/after comparison (claude vs codex success rates)	Grouped bar
Ranked factors / correlations (per-CLI categories)	Lollipop
Parts of whole / market share (cost split per model)	Donut
Trend over time (fitness score by week)	Line
Percentage improvement (single dimension)	Horizontal bar
Distribution / range (latency p50/p99)	Area
Multi-dimensional scoring	Radar

Don't reuse the same chart type for unrelated data within the same section, but feel free to use it again where the data shape repeats — e.g., two horizontal-bar comparisons in different parts of an architecture doc is fine.

Step 2 — Render with the canonical SVG shell

All charts share this shell (viewBox may be tuned per chart):

<svg
  viewBox="0 0 560 380"
  style="max-width: 100%; height: auto; font-family: 'Inter', system-ui, sans-serif"
  role="img"
  aria-label="<one-line description with the headline number>"
>
  <title>Chart Title</title>
  <desc>Description for screen readers with all key data points and source.</desc>

  <!-- Chart content (axes, bars, labels) -->

  <text x="280" y="372" text-anchor="middle" font-size="10"
        fill="currentColor" opacity="0.35">
    Source: Source Name (Year)
  </text>
</svg>

Color palette (dark-mode safe, all text uses currentColor):

Color	Hex	Use case
Orange	#f97316	Primary / highest value
Sky blue	#38bdf8	Secondary / comparison
Purple	#a78bfa	Tertiary / special category
Green	#22c55e	Quaternary / positive indicator

For text inside colored fills, use fill="white" with font-weight:800.

Step 3 — Pull data from canonical sources when applicable

For nexus-agents-specific data, reach for these existing surfaces rather than asking the operator for raw numbers:

Need	Read from
Per-call cost / latency / success	<NEXUS_DATA_DIR>/usage/usage-YYYY-MM.jsonl
Per-CLI rolling success rate	weather_report MCP tool output
Vote outcomes by role	<NEXUS_DATA_DIR>/voting/*.jsonl
Fitness audit history	<NEXUS_DATA_DIR>/audit/fitness-*.json
Routing decision distribution	query_trace MCP tool output

When the data isn't available locally, ask the operator for a JSONL or CSV path — don't fabricate numbers.

Cross-references — when to redirect

This skill is the quantitative-charts lane. Redirect when the request fits a different lane:

• Sequence / state / flow / class / ER diagram → docs-mermaid
• Hero or conceptual illustration → docs-image
• Doc structure / placement → documentation-management

Say the rule of thumb when redirecting: "Charts are for numbers; for 'show me how X works', use docs-mermaid."

What this skill does NOT do

• Architecture / sequence diagrams — those belong in docs-mermaid.
• Live charts — output is static SVG. If the data needs to update, re-run the skill against fresh JSONL.
• Server-side rendering / build-time generation — produces SVG strings; embedding into a doc is the doc author's choice.
• Theme customization — uses currentColor so the doc's existing theme handles light/dark. Don't override.

See also

• references/chart-types.md — copy-pasteable templates for all seven chart types with nexus-agents-flavored examples.
• nexus-agents usage --format=json — JSON output suitable for direct ingestion by chart rendering.