Data Visualise

Data Visualise

This skill orchestrates which visual artefact to build. Two renderers, one metrics contract (analysis.json or declarative specs):

Both are local, offline, and draft-for-review. PowerPoint and letters stay out of scope.

HTML / Excel parity (treat them as peers)

Neither path requires data-analyse. A simple table (CSV / JSON / .xlsx) is enough for both. What differs is only the renderer and how you declare the series — not whether the job is allowed.

Do not steer every Excel request through analyse first, and do not treat HTML as the only “simple data” path. Build the category/value series once from the table, then:

• HTML → bar_chart / line_chart / donut_chart / waterfall / table…
• Excel → chart_type column / line / pie / doughnut / waterfall…

Rough block ↔ chart mapping (same story, different file):

Use data-analyse when the brief needs engine-exact metrics (ageing, concentration, MoM, currency gates) or you want one analysis.json to drive HTML and Excel together. For “chart this column by that column”, skip analyse and declare the series directly on both paths.

0 — Pick the artefact (do this first)

Ask (briefly) who reads it and where it will live:

1. HTML if they want a branded board, print-to-PDF, or an in-chat artifact.
2. Excel if they say “charts in a spreadsheet”, will filter/annotate further, or the pack lives in a shared drive as .xlsx.
3. Both is fine — same table-derived series, or the same analysis.json via suggest_blocks_from_analysis and suggest_charts_from_analysis.

Infer from the plan when unspoken: format: "xlsx" or output ending in .xlsx → Excel; otherwise HTML.

Excel charts use openpyxl (toolkit hard dep). Chart prop names follow OfficeCLI / AionUi (chartType, categories, series, waterfall colours) — OfficeCLI is not required at runtime. See references/workbook-charts.md.

When to use it

• A weekly operations / task one-pager (HTML).
• A compliance status board — what's due, overdue, by owner (HTML).
• A finance / pipeline scorecard — KPI cards + trend + breakdown (HTML or Excel).
• Native Excel charts from a simple export or an analyse run (Excel).

To clean or extract first, run data-tidy / data-extract. Optional: data-analyse when metrics must be engine-exact or shared across HTML + Excel.

Workflow

1. Intent — purpose, reader, and artefact (HTML vs Excel). Don't render twelve charts when four KPIs and one trend answer the question.
2. Data — plain table rows, or analysis.json when you need the analyse engine.
3. Propose — derive the same category/value series for either path. HTML: block list (or $analysis). Excel: type: chart list (or $analysis). Confirm.
4. Render & review — HTML → dashboard(...) / open in browser; Excel → write_charts_xlsx / charts_from_analysis. Draft for a qualified person; never auto-send.

HTML path (viz.py)

Brandable, self-contained HTML — inline SVG, no CDN/remote images; prints to PDF. Ships unbranded (teal / cool-paper) and is fully brandable (references/brand.md). Renders as a live Artifact in Cowork / Claude.ai when handed over as written.

Building blocks

Each returns an HTML fragment; dashboard() assembles them.

Full signatures, parameters, and examples for every block: references/blocks.md.

Minimal example:

import sys; sys.path.insert(0, "scripts")
from viz import kpi_row, bar_chart, table, section, dashboard, open_in_browser

Run from the skill directory (skills/data-visualise/). The scripts path resolves to this skill's scripts/ subdirectory where viz.py lives.

blocks = [ kpi_row([{"label": "Open", "value": 12, "status": "brand"}, {"label": "Overdue", "value": 3, "status": "red"}]), section("Throughput", bar_chart([("Mon", 4), ("Tue", 7), ("Wed", 5)], title="Done by day")), table(rows, title="Detail", rag={"Days late": lambda v: "red" if v > 7 else "green"}), ] path = dashboard("Operations dashboard", blocks, as_of="14 Jun 2026", out_path="ops-dashboard.html") open_in_browser(path)

See `references/blocks.md` for the full cookbook and `references/brand.md` for the theming
guide. `examples/operations-dashboard.html` is a built sample.

### From data-analyse (HTML)

```python
from viz import suggest_blocks_from_analysis, blocks_from_analysis, dashboard
specs = suggest_blocks_from_analysis(analysis)   # declarative — show the user
path = dashboard("Insight board", blocks_from_analysis(analysis),
                 as_of="18 Jul 2026", out_path="insight.html")

Plan: "blocks": "$analysis" or {"type": "from_analysis", "ops": [...]} with analysis.json as the input.

Excel path (workbook.py)

Chart-only workbook: one sheet per chart, data in cells, embedded native Excel chart. Vocabulary aligned with OfficeCLI (column / bar / line / pie / doughnut / waterfall). Full prop list: references/workbook-charts.md.

From a simple table (parity with HTML — no analyse):

from workbook import write_charts_xlsx
# same series you'd pass to viz.bar_chart([(lab, val), ...])
write_charts_xlsx("charts.xlsx", [
    {"chart_type": "column", "title": "By region",
     "categories": ["North", "South"],
     "series": [{"name": "Amount", "values": [120, 80]}]},
])

Optional — from analysis.json:

from workbook import suggest_charts_from_analysis, charts_from_analysis
charts_from_analysis(analysis, "insight-charts.xlsx")

Plans (format from format: "xlsx" or .xlsx output):

{
  "skill": "data-visualise",
  "format": "xlsx",
  "dashboard": {
    "title": "By region",
    "blocks": [{
      "type": "chart", "chart_type": "column", "title": "By region",
      "categories": ["North", "South"],
      "series": [{"name": "Amount", "values": [120, 80]}]
    }]
  },
  "output": "out/charts.xlsx"
}

Or "input": "out/analysis.json" with "blocks": "$analysis" when an analyse run exists.

Theming (neutral default, fully brandable)

The engine ships a neutral, unbranded default out of the box. To apply a firm's brand, pass a theme dict (any subset overrides the default):

from viz import apply_theme, dashboard
my_theme = {"brand_name": "Acme Co",
            "logo_path": "assets/acme-logo.png",        # transparent PNG; omit → text wordmark
            "colours": {"burgundy": "#0B3D91", "rose": "#1565C0"}}  # token names are historical
apply_theme(my_theme)                                   # re-skins chart colours too
dashboard("Operations dashboard", blocks, theme=my_theme, out_path="dashboard.html")

dashboard(theme=...) re-skins the page shell (header rule, logo/wordmark, font, footer brand line); apply_theme(theme) (called before building blocks) also re-skins the chart colours. Full guide: references/brand.md.

Interactivity (optional — still print-first)

By default a dashboard is a static, printable report. You can opt into light interactivity with plain inline JS (no library, no CDN, no JSX) that the engine adds only when a block asks for it — the file stays single, self-contained and offline:

• line_chart(..., toggle=True) — click a legend item to show/hide that series.
• table(..., sortable=True) — click a column header to sort (numeric-aware).
• table(..., filter_by="City") — a dropdown that filters rows by that column.

These degrade cleanly for print: the current sort order prints, filtered-out rows stay out, and the controls/print button drop away under @media print. Default everything off for a pure report. This is the deliberate ceiling — for anything heavier, see below.

Need a React / app-like dashboard?

This skill is HTML-only by design (self-contained, offline, printable, and a live HTML Artifact in Cowork). If a genuine React/JSX dashboard is needed — rich state, cross-filtering, app-like behaviour — that's out of scope here. Hand off to the built-in anthropic-skills:web-artifacts-builder skill, but carry this skill's guidance across: the theme tokens from references/brand.md / scripts/viz.py (BRAND/FONT), the data-handling / PII rule (../../PRINCIPLES.md#data-handling--pii-policy — a React artifact runs in the cloud runtime, so gated data must be de-identified first), and the house style (British English, DD MMM YYYY, draft not advice). Keep this skill for the common case: a clean, branded, printable dashboard that also opens as a live artifact.

House style & boundary

• British English; dates DD MMM YYYY; the as_of stamp should be real.
• Output is a draft for a qualified person to review — the footer says so on every page. It is not advice and is never auto-distributed.
• Don't invent numbers. Visualise what you're given (or what a store holds); if a figure is derived, make the derivation obvious.

Files

• scripts/viz.py — HTML engine: theme, blocks, dashboard(), analysis→blocks handoff; python viz.py [out.html] self-test.
• scripts/workbook.py — Excel chart engine: OfficeCLI-aligned chart specs, analysis→charts; python workbook.py [out.xlsx] self-test.
• references/brand.md — HTML theming guide.
• references/blocks.md — HTML building-block cookbook.
• references/workbook-charts.md — Excel chart types, props, analysis mapping.
• examples/operations-dashboard.html — built HTML sample.

Principles

Behavioural charter: ../../PRINCIPLES.md — drafts not advice, never invent, honesty and calibration, plain speech, action boundary.

Data handling

The renderer is local and offline — it embeds whatever data you pass directly into the HTML and never calls out (no CDN/remote images), so the dashboard file itself leaks nothing. (The AI agent driving the skill does send whatever it reads into its context to your AI provider.) Keep the rendered .html/PDF on your synced or shared file store. If the dashboard contains personal data or confidential business/ financial data (e.g. named individuals with contact details or IDs, customer/supplier lists, pricing, unpublished financials), treat the file as gated — don't send it to any external tool, and only share with entitled recipients. A board built purely from non-sensitive, aggregated numbers is not gated. Full rule: ../../PRINCIPLES.md#data-handling--pii-policy.

Feedback

Have an improvement or found a bug in this skill? Capture it with the toolkit's shared feedback format — ../../CONTRIBUTING.md#skill-feedback-format — so it reaches the skill author consistently (skill name, what you did, expected vs actual, severity, suggestion). Save it as a .txt file (feedback_[skill]_[date].txt) and hand it to the user to file — manual, no fixed destination; fix in scope if asked.

Requirements & mode

Pre-screen before running: see ../../README.md#mode--environment-compatibility and run python ../../scripts/envcheck.py. Highly portable — pure Python stdlib for the HTML itself (no third-party library needed to render). rows_from_xlsx needs openpyxl only if you read an .xlsx. open_in_browser and print-to-PDF need a desktop browser (any OS); in a headless/Cowork session the .html still builds — open it locally to print. No network, no MS Office, no credentials.