@loreto-labs/skill-echarts 0.1.0

package/skill/README.md

@@ -0,0 +1,85 @@
+# building-branded-echarts-visualizations
+
+Turn a company's **brand styles (colors + fonts)** into polished, on-brand **Apache ECharts**
+charts — rendered server-side to **SVG + PNG**, no browser. Capture the brand once as a small
+JSON token file; 14 chart types render from it consistently, and re-skinning to a new brand is a
+one-file change.
+
+## Example output
+
+The same engine, styled entirely by one small brand file. Here's a monochrome theme across a
+range of chart types — scatter, line, radar, KPI cards, and a heatmap:
+
+![Branded scatter chart — monochrome theme](https://loreto.io/api/files/6a2d49f1ac9763d6b99ef18f)
+
+![Branded line chart — monochrome theme](https://loreto.io/api/files/6a2d49f2ac9763d6b99ef191)
+
+![Branded radar chart — monochrome theme](https://loreto.io/api/files/6a2d53b781ee262fc64b4cad)
+
+![Branded KPI cards — monochrome theme](https://loreto.io/api/files/6a2d571f81ee262fc64b4caf)
+
+![Branded heatmap — monochrome theme](https://loreto.io/api/files/6a2d572081ee262fc64b4cb1)
+
+## Quick start
+
+```bash
+cd scripts
+npm install                       # echarts + @resvg/resvg-js
+
+# Render every example chart for every brand → out/<brand>/*.svg + *.png + a gallery
+node render-all.mjs
+open ../out/index.html            # or just open the SVGs/PNGs in out/<brand>/
+
+# Render a single chart
+node render.mjs --brand ../brands/onyx.json --chart ../examples/01_bar.json --out ../out/onyx/bar.svg
+```
+
+Ships with two **dark, monochrome demo brands** — `onyx` (sleek greyscale) and `apricot` (warm
+peach pastel). Each is a near-black canvas with a single-hue palette stepped light→deep and crisp
+typography. Add your own brand the same way (any hue — the palette derives + contrast-checks
+automatically).
+
+## How it works
+
+A small pipeline turns your **brand tokens** + **chart data** into rendered charts:
+
+1. **Brand** — `brands/<brand>.json` (colors + fonts) is read by `lib/palette.mjs`, which completes
+   and contrast-checks the palette, then `lib/theme.mjs` maps the tokens to an ECharts theme object.
+2. **Data** — `examples/<chart>.json` (chart type + data) is turned into a per-type ECharts option
+   by `lib/charts.mjs`.
+3. **Render** — ECharts server-side renders the option to an SVG (`renderToSVGString`), and
+   `lib/fonts.mjs` embeds the brand `@font-face` (and loads the font for the PNG via resvg).
+4. **Output** — `out/<brand>/<chart>.svg` plus a 2× `.png`.
+
+## Brand it for a company
+
+1. Copy a brand (e.g. `brands/onyx.json`) to `brands/<company>.json`.
+2. Replace `colors.categorical` + neutrals with the brand's hex codes; set `fonts.family` /
+   `titleFamily` and add `fonts.faces[]` webfont URLs (e.g. from fontsource / Google Fonts).
+3. `node render-all.mjs` → review `out/<company>/`.
+
+Fonts are **referenced** (family + webfont URL), never bundled as binaries. SVG output is
+font-accurate via embedded `@font-face`; PNG uses a local font file (`faces[].file`) if given,
+otherwise a system fallback (colors/layout stay correct).
+
+## Chart types
+
+`bar`, `groupedBar`, `stackedBar`, `hbar`, `line`, `area`, `pie`, `donut`, `scatter`, `kpi`,
+`heatmap`, `radar`, `treemap`, `dashboard` — one `examples/*.json` per type shows the data shape.
+
+## Files
+
+- `SKILL.md` — the methodology (this is a Claude Code skill package).
+- `references/` — ECharts theming model, brand→token mapping, chart recipes, font/SVG embedding.
+- `scripts/` — the render pipeline (`render.mjs`, `render-all.mjs`, `lib/`).
+- `brands/`, `examples/` — demo brands and chart specs.
+- `tests/` — a functional test that renders a chart and asserts brand color + font landed.
+
+`node_modules/` and `out/` are generated and gitignored.
+
+## Sources
+
+- Apache ECharts — theming & options: <https://echarts.apache.org/en/option.html>
+- Apache ECharts — server-side rendering: <https://echarts.apache.org/handbook/en/how-to/cross-platform/server/>
+- resvg-js (SVG→PNG): <https://github.com/yisibl/resvg-js>
+- WCAG 2.1 contrast: <https://www.w3.org/TR/WCAG21/#contrast-minimum>

package/skill/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: building-branded-echarts-visualizations
+description: >
+  Turns a company's brand styles (color codes + fonts) into polished, on-brand Apache
+  ECharts data visualizations — bar, line, area, pie/donut, scatter, KPI cards, heatmap,
+  radar, treemap, and full dashboards — rendered server-side to SVG and PNG. Use when you
+  need "branded charts", "on-brand data viz", "style ECharts to our brand", "company-branded
+  dashboards", "charts that match our brand guidelines", or to produce a reusable chart
+  theme from a brand's palette and typography. You give it a brand token file (hex colors,
+  font families, optional webfont URLs) and a chart spec (type + data); it emits a styled
+  SVG (font-accurate) plus a PNG. Bundled Node scripts do the rendering — no browser needed.
+  Invoke it by NAMING a theme — e.g. "apply the Apricot style to all of our analytics charts"
+  or "render this data in the Onyx theme" — and it resolves the named style to its brand file
+  and applies it to every chart. Bundled themes: onyx, apricot (list with `ls brands/`).
+---
+
+# Building Branded ECharts Visualizations
+
+Generic charts undercut a brand. This skill makes Apache ECharts charts that look like they
+came out of a company's own design system: its palette, its typefaces, its tone (light or
+dark), applied consistently across every chart type. You capture the brand once as a small
+JSON token file; every chart is rendered from that, so 14 chart types stay visually coherent
+and re-skinning to a new brand is a one-file change.
+
+## When to Use This Skill
+
+- A client/company wants report, deck, or dashboard charts in **their** brand, not default ECharts blue.
+- You have brand guidelines (hex codes + fonts) and need a **repeatable** way to produce many on-brand charts.
+- You want a reusable **ECharts theme** derived from a brand, plus ready-to-run render scripts.
+- You need static, embeddable outputs (**SVG** for crisp/web, **PNG** for slides) generated headlessly.
+
+Not for: live, interactive in-browser dashboards (use ECharts directly in the page); one-off
+charts where branding doesn't matter.
+
+## Why On-Brand Charts Are Hard
+
+1. **Theming surface area.** A coherent look means setting dozens of ECharts properties (axis
+   lines, split lines, label colors, legend, tooltip, title, per-series defaults) — consistently,
+   for every chart type. Do it ad hoc and charts drift.
+2. **Palette math.** Brands ship 2–6 colors; a stacked bar or multi-series line needs more, all
+   distinguishable *and* legible on the brand's background. Naively repeating or randomizing colors
+   looks off-brand and fails contrast.
+3. **Fonts don't travel.** An SVG references a font by name but carries no font data; a PNG
+   rasterizer needs the actual font file. Miss this and your "branded" chart silently falls back
+   to Arial.
+4. **Light vs dark.** The same palette needs different neutrals, gridlines, and contrast handling
+   on white vs near-black. One theme must adapt.
+
+## The Brand → Theme Pipeline
+
+1. **Capture brand tokens** → `brands/<brand>.json` (schema below). Colors + fonts + a few shape knobs.
+2. **Complete the palette** (`lib/palette.mjs`): reuse the brand's categorical colors, then derive
+   extra hues by golden-angle rotation, each contrast-checked against the background, so many-series
+   charts stay on-brand and legible.
+3. **Build the ECharts theme** (`lib/theme.mjs`): map tokens → an ECharts theme object (color list,
+   background, `textStyle`, title/legend/tooltip, category/value axis treatment, and per-type series
+   defaults like bar corner radius and line width). Registered via `echarts.registerTheme`.
+4. **Render per chart type** (`lib/charts.mjs`): each builder supplies only data + type-specific
+   touches; all styling comes from the theme. Heatmaps use a **sequential single-hue ramp** from the
+   primary color (never the categorical rainbow).
+5. **Embed fonts + rasterize** (`lib/fonts.mjs`): inject `@font-face` (webfont URL) into the SVG so a
+   browser renders the real brand font; for PNG, `@resvg/resvg-js` uses any local font file declared
+   on the brand, else a system fallback. **SVG is the font-accurate source of truth.**
+
+## Brand Token Schema (`brands/*.json`)
+
+```json
+{
+  "name": "Onyx",
+  "mode": "dark",                               // "light" | "dark" — drives default neutrals
+  "colors": {
+    // Monochrome: ONE hue (or greyscale) stepped light → deep (auto-extended, contrast-checked)
+    "categorical": ["#f4f6f7", "#7e858e", "#c0c5cb", "#565d67", "#9aa1a9", "#3f454e"],
+    "background": "#0b0d10", "surface": "#15181c",
+    "text": "#fafafa", "textMuted": "#8a9099",
+    "axis": "#2a2e34", "grid": "#1a1d21",
+    "positive": "#e8e9eb", "negative": "#787e86"
+  },
+  "fonts": {
+    "family": "Inter", "titleFamily": "Space Grotesk", "baseSize": 14,
+    "faces": [                                  // for SVG @font-face (url) + PNG (optional file)
+      { "family": "Inter", "weight": 400, "url": "https://.../inter-400.woff2" },
+      { "family": "Space Grotesk", "weight": 700, "url": "https://.../space-grotesk-700.woff2", "file": "fonts/SpaceGrotesk.ttf" }
+    ]
+  },
+  "shape": { "barRadius": 2, "lineWidth": 2, "symbolSize": 7, "gridline": "dashed" }
+}
+```
+
+Only `name`, `colors.categorical`, and `colors.background` are strictly required — everything else
+has sensible per-mode defaults. **Editing this file (colors/fonts) and re-running is the whole
+workflow.** Fonts are referenced, never bundled as binaries.
+
+## Running the Scripts
+
+```bash
+cd scripts && npm install            # echarts + @resvg/resvg-js (no native toolchain needed)
+
+# One chart:
+node render.mjs --brand ../brands/onyx.json --chart ../examples/05_line.json --out ../out/onyx/line.svg
+
+# Everything — every example × every brand → out/<brand>/*.svg + *.png + out/index.html gallery:
+node render-all.mjs
+```
+
+To brand it for a new company: copy a `brands/*.json`, drop in their hex codes and font families
+(+ webfont URLs), run `render-all.mjs`, open `out/index.html`.
+
+## Invoking by Theme Name
+
+A user will usually just **name a theme** and a dataset — e.g. *"apply the Apricot style to all of
+our analytics charts."* Resolve it like this:
+
+1. **Map the named style → a brand file.** A theme name is a `brands/<name>.json` (case-insensitive;
+   `ls brands/` lists what's available — bundled: `onyx`, `apricot`). "Apricot style" → `brands/apricot.json`.
+   - If the named theme isn't bundled (e.g. *"apply our Acme brand"*), first create
+     `brands/<name>.json` from the user's hex codes + fonts, then proceed.
+2. **Gather the data as chart specs.** Turn each chart the user wants into an `examples/*.json`
+   spec (`{type, title, data}`) — one per chart. For "all of our analytics charts," create a spec
+   per dataset/metric they gave you.
+3. **Apply the theme to every chart.** Render each spec with the resolved brand:
+   `node render.mjs --brand brands/<theme>.json --chart <spec>.json --out out/<theme>/<name>.svg`
+   (or drop the specs in `examples/` and run `render-all.mjs` to do the whole set in that theme).
+4. **Return the artifacts** — the `out/<theme>/*.svg` (+ `.png`) files.
+
+So "apply the Apricot style to all our analytics charts" = resolve `apricot` → `brands/apricot.json`,
+build a spec per chart, render them all with that brand. The skill is "theme-aware": the user names
+the look, you map it to the brand file and apply it across the data.
+
+## Chart-Type Recipes (the 14 builders)
+
+`bar`, `groupedBar`, `stackedBar`, `hbar`, `line`, `area`, `pie`, `donut`, `scatter`, `kpi`
+(graphic number cards w/ colored deltas), `heatmap` (sequential ramp), `radar`, `treemap`, and
+`dashboard` (KPI strip + bar + line composite). See `references/chart-type-recipes.md` for the
+`spec.data` shape and which tokens each one leans on.
+
+## Anti-Patterns
+
+- **Default ECharts palette** on a branded deck — instantly reads as "stock chart."
+- **Rainbow heatmaps** — using categorical colors for magnitude is unreadable; use a single-hue ramp.
+- **Bundling `.ttf`/`.woff2` binaries** — they bloat the package and are stripped on publish; reference fonts by URL.
+- **Low-contrast text/series** on the brand background — always contrast-check (this skill does, automatically).
+- **Too many raw series colors** — beyond ~6, derive harmonized hues instead of inventing clashing ones.
+- **Ignoring light/dark** — reusing white-mode neutrals on a dark brand kills legibility.
+
+## Output
+
+Per chart: a font-accurate **`.svg`** (with embedded `@font-face`) and a 2× **`.png`**. `render-all.mjs`
+also writes **`out/index.html`**, a side-by-side gallery of every brand × chart for quick review.
+
+## References
+
+- `references/echarts-theming-model.md` — the ECharts theme object + server-side rendering (`renderToSVGString`).
+- `references/brand-style-mapping.md` — turning a brand style guide into tokens (+ WCAG contrast).
+- `references/chart-type-recipes.md` — per-type `spec.data` shapes and token usage.
+- `references/fonts-and-svg-embedding.md` — `@font-face` in SVG, resvg fonts for PNG, why binaries aren't bundled.
+
+## Verification Checklist
+
+- [ ] `npm install` succeeds; `node render-all.mjs` renders all charts for every brand with no errors.
+- [ ] Each `out/<brand>/*.svg` contains a brand categorical hex **and** the brand `font-family`.
+- [ ] The brands look distinctly on-brand from identical data (palette, neutrals, type, light/dark).
+- [ ] Editing a color/font in a `brands/*.json` and re-running propagates everywhere.
+- [ ] `python3 tests/test_building_branded_echarts_visualizations.py` prints `PASSED`.

package/skill/brands/apricot.json

@@ -0,0 +1,30 @@
+{
+  "name": "Apricot",
+  "mode": "dark",
+  "colors": {
+    "categorical": ["#ffe0c2", "#eda468", "#fac59a", "#db8a43", "#f1b783", "#ba6d2f"],
+    "background": "#160f08",
+    "surface": "#241710",
+    "text": "#fbeee2",
+    "textMuted": "#c2a288",
+    "axis": "#3c2c1e",
+    "grid": "#241810",
+    "positive": "#ffe0c2",
+    "negative": "#ba6d2f"
+  },
+  "fonts": {
+    "family": "Inter",
+    "titleFamily": "Outfit",
+    "monoFamily": "JetBrains Mono",
+    "baseSize": 14,
+    "weights": { "regular": 400, "medium": 600, "bold": 700 },
+    "faces": [
+      { "family": "Inter", "weight": 400, "url": "https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-400-normal.woff2" },
+      { "family": "Inter", "weight": 600, "url": "https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-600-normal.woff2" },
+      { "family": "Outfit", "weight": 600, "url": "https://cdn.jsdelivr.net/fontsource/fonts/outfit@latest/latin-600-normal.woff2" },
+      { "family": "Outfit", "weight": 700, "url": "https://cdn.jsdelivr.net/fontsource/fonts/outfit@latest/latin-700-normal.woff2" }
+    ]
+  },
+  "shape": { "barRadius": 5, "lineWidth": 2.5, "symbolSize": 8, "gridline": "dashed" },
+  "logo": { "text": "APRICOT" }
+}

package/skill/brands/onyx.json

@@ -0,0 +1,31 @@
+{
+  "name": "Onyx",
+  "mode": "dark",
+  "colors": {
+    "categorical": ["#f4f6f7", "#7e858e", "#c0c5cb", "#565d67", "#9aa1a9", "#3f454e"],
+    "background": "#0b0d10",
+    "surface": "#15181c",
+    "text": "#fafafa",
+    "textMuted": "#8a9099",
+    "axis": "#2a2e34",
+    "grid": "#1a1d21",
+    "positive": "#e8e9eb",
+    "negative": "#787e86"
+  },
+  "fonts": {
+    "family": "Inter",
+    "titleFamily": "Space Grotesk",
+    "monoFamily": "JetBrains Mono",
+    "baseSize": 14,
+    "weights": { "regular": 400, "medium": 600, "bold": 700 },
+    "faces": [
+      { "family": "Inter", "weight": 400, "url": "https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-400-normal.woff2" },
+      { "family": "Inter", "weight": 600, "url": "https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-600-normal.woff2" },
+      { "family": "Inter", "weight": 700, "url": "https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-700-normal.woff2" },
+      { "family": "Space Grotesk", "weight": 600, "url": "https://cdn.jsdelivr.net/fontsource/fonts/space-grotesk@latest/latin-600-normal.woff2" },
+      { "family": "Space Grotesk", "weight": 700, "url": "https://cdn.jsdelivr.net/fontsource/fonts/space-grotesk@latest/latin-700-normal.woff2" }
+    ]
+  },
+  "shape": { "barRadius": 2, "lineWidth": 2, "symbolSize": 7, "gridline": "dashed" },
+  "logo": { "text": "ONYX" }
+}

package/skill/examples/01_bar.json

@@ -0,0 +1,12 @@
+{
+  "type": "bar",
+  "title": "Revenue by quarter",
+  "subtitle": "FY2026 · $M",
+  "width": 900,
+  "height": 540,
+  "yName": "$M",
+  "data": {
+    "categories": ["Q1", "Q2", "Q3", "Q4"],
+    "series": [{ "name": "Revenue", "data": [42, 51, 49, 63] }]
+  }
+}

package/skill/examples/02_grouped_bar.json

@@ -0,0 +1,16 @@
+{
+  "type": "groupedBar",
+  "title": "Revenue by region",
+  "subtitle": "FY2026 · $M",
+  "width": 960,
+  "height": 540,
+  "yName": "$M",
+  "data": {
+    "categories": ["Q1", "Q2", "Q3", "Q4"],
+    "series": [
+      { "name": "Americas", "data": [22, 26, 25, 31] },
+      { "name": "EMEA", "data": [14, 17, 16, 21] },
+      { "name": "APAC", "data": [9, 11, 13, 16] }
+    ]
+  }
+}

package/skill/examples/03_stacked_bar.json

@@ -0,0 +1,16 @@
+{
+  "type": "stackedBar",
+  "title": "Bookings by plan",
+  "subtitle": "Stacked · thousands",
+  "width": 960,
+  "height": 540,
+  "yName": "k",
+  "data": {
+    "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
+    "series": [
+      { "name": "Starter", "data": [12, 14, 13, 16, 18, 19] },
+      { "name": "Pro", "data": [8, 9, 11, 12, 13, 15] },
+      { "name": "Enterprise", "data": [3, 4, 4, 6, 7, 9] }
+    ]
+  }
+}

package/skill/examples/04_hbar.json

@@ -0,0 +1,12 @@
+{
+  "type": "hbar",
+  "title": "Top products by units sold",
+  "subtitle": "Last 30 days",
+  "width": 900,
+  "height": 540,
+  "xName": "units",
+  "data": {
+    "categories": ["Atlas", "Beacon", "Cobalt", "Drift", "Ember", "Forge"],
+    "series": [{ "name": "Units", "data": [1840, 1610, 1320, 980, 870, 540] }]
+  }
+}

package/skill/examples/05_line.json

@@ -0,0 +1,16 @@
+{
+  "type": "line",
+  "title": "Monthly active users",
+  "subtitle": "By plan · thousands",
+  "width": 960,
+  "height": 540,
+  "yName": "k MAU",
+  "data": {
+    "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug"],
+    "series": [
+      { "name": "Free", "data": [120, 132, 141, 154, 162, 178, 191, 210] },
+      { "name": "Pro", "data": [40, 44, 49, 53, 58, 65, 71, 80] },
+      { "name": "Enterprise", "data": [12, 13, 15, 17, 19, 22, 25, 29] }
+    ]
+  }
+}

package/skill/examples/06_area.json

@@ -0,0 +1,15 @@
+{
+  "type": "area",
+  "title": "Traffic by source",
+  "subtitle": "Sessions · thousands",
+  "width": 960,
+  "height": 540,
+  "yName": "k",
+  "data": {
+    "categories": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
+    "series": [
+      { "name": "Organic", "data": [32, 38, 41, 44, 48, 30, 26] },
+      { "name": "Paid", "data": [18, 21, 22, 25, 27, 19, 15] }
+    ]
+  }
+}

package/skill/examples/07_pie.json

@@ -0,0 +1,16 @@
+{
+  "type": "pie",
+  "title": "Market share",
+  "subtitle": "By vendor",
+  "width": 900,
+  "height": 540,
+  "data": {
+    "items": [
+      { "name": "Acme", "value": 38 },
+      { "name": "Globex", "value": 24 },
+      { "name": "Initech", "value": 18 },
+      { "name": "Umbrella", "value": 12 },
+      { "name": "Other", "value": 8 }
+    ]
+  }
+}

package/skill/examples/08_donut.json

@@ -0,0 +1,17 @@
+{
+  "type": "donut",
+  "title": "Cloud spend by category",
+  "subtitle": "This month",
+  "centerLabel": "$84k",
+  "width": 900,
+  "height": 540,
+  "data": {
+    "items": [
+      { "name": "Compute", "value": 38 },
+      { "name": "Storage", "value": 21 },
+      { "name": "Network", "value": 14 },
+      { "name": "Data", "value": 17 },
+      { "name": "Other", "value": 10 }
+    ]
+  }
+}

package/skill/examples/09_scatter.json

@@ -0,0 +1,15 @@
+{
+  "type": "scatter",
+  "title": "Price vs. rating",
+  "subtitle": "Bubble size = monthly volume",
+  "width": 960,
+  "height": 560,
+  "xName": "Price ($)",
+  "yName": "Rating",
+  "data": {
+    "series": [
+      { "name": "Hardware", "points": [[29, 4.1, 320], [49, 4.4, 540], [79, 4.6, 410], [99, 4.2, 260], [129, 4.7, 180]] },
+      { "name": "Software", "points": [[12, 4.5, 880], [19, 4.6, 760], [29, 4.8, 620], [49, 4.7, 430], [99, 4.9, 210]] }
+    ]
+  }
+}

package/skill/examples/10_kpi.json

@@ -0,0 +1,15 @@
+{
+  "type": "kpi",
+  "title": "Business at a glance",
+  "subtitle": "Month to date",
+  "width": 1100,
+  "height": 280,
+  "data": {
+    "cards": [
+      { "label": "Revenue", "value": "$1.28M", "delta": "+12.4%", "deltaDir": "up" },
+      { "label": "Active users", "value": "48,210", "delta": "+6.1%", "deltaDir": "up" },
+      { "label": "Churn", "value": "2.3%", "delta": "-0.4 pp", "deltaDir": "down" },
+      { "label": "NPS", "value": "61", "delta": "+5", "deltaDir": "up" }
+    ]
+  }
+}

package/skill/examples/11_heatmap.json

@@ -0,0 +1,21 @@
+{
+  "type": "heatmap",
+  "title": "Activity by day and hour",
+  "subtitle": "Sessions",
+  "width": 1000,
+  "height": 560,
+  "showValues": false,
+  "data": {
+    "x": ["12a", "2a", "4a", "6a", "8a", "10a", "12p", "2p", "4p", "6p", "8p", "10p"],
+    "y": ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
+    "values": [
+      [0,0,2],[1,0,1],[2,0,1],[3,0,3],[4,0,6],[5,0,9],[6,0,12],[7,0,11],[8,0,9],[9,0,7],[10,0,5],[11,0,3],
+      [0,1,1],[1,1,1],[2,1,1],[3,1,4],[4,1,9],[5,1,14],[6,1,18],[7,1,17],[8,1,15],[9,1,10],[10,1,6],[11,1,3],
+      [0,2,1],[1,2,1],[2,2,2],[3,2,5],[4,2,10],[5,2,16],[6,2,20],[7,2,19],[8,2,16],[9,2,11],[10,2,6],[11,2,3],
+      [0,3,1],[1,3,1],[2,3,2],[3,3,5],[4,3,11],[5,3,17],[6,3,21],[7,3,20],[8,3,17],[9,3,12],[10,3,7],[11,3,4],
+      [0,4,2],[1,4,1],[2,4,2],[3,4,6],[4,4,12],[5,4,18],[6,4,22],[7,4,21],[8,4,18],[9,4,13],[10,4,8],[11,4,5],
+      [0,5,2],[1,5,2],[2,5,2],[3,5,5],[4,5,10],[5,5,15],[6,5,17],[7,5,16],[8,5,15],[9,5,14],[10,5,11],[11,5,7],
+      [0,6,3],[1,6,2],[2,6,2],[3,6,4],[4,6,7],[5,6,10],[6,6,12],[7,6,12],[8,6,13],[9,6,13],[10,6,11],[11,6,8]
+    ]
+  }
+}

package/skill/examples/12_radar.json

@@ -0,0 +1,21 @@
+{
+  "type": "radar",
+  "title": "Product comparison",
+  "subtitle": "Normalized scores",
+  "width": 900,
+  "height": 560,
+  "data": {
+    "indicators": [
+      { "name": "Performance", "max": 100 },
+      { "name": "Reliability", "max": 100 },
+      { "name": "Usability", "max": 100 },
+      { "name": "Security", "max": 100 },
+      { "name": "Support", "max": 100 },
+      { "name": "Value", "max": 100 }
+    ],
+    "series": [
+      { "name": "Our product", "value": [88, 92, 80, 95, 78, 84] },
+      { "name": "Competitor", "value": [72, 80, 88, 70, 85, 76] }
+    ]
+  }
+}

package/skill/examples/13_treemap.json

@@ -0,0 +1,20 @@
+{
+  "type": "treemap",
+  "title": "Revenue by segment",
+  "subtitle": "Segment › product",
+  "width": 1000,
+  "height": 560,
+  "data": {
+    "nodes": [
+      { "name": "Enterprise", "value": 52, "children": [
+        { "name": "Platform", "value": 30 }, { "name": "Add-ons", "value": 12 }, { "name": "Services", "value": 10 }
+      ]},
+      { "name": "Mid-market", "value": 33, "children": [
+        { "name": "Platform", "value": 19 }, { "name": "Add-ons", "value": 9 }, { "name": "Services", "value": 5 }
+      ]},
+      { "name": "SMB", "value": 21, "children": [
+        { "name": "Starter", "value": 13 }, { "name": "Pro", "value": 8 }
+      ]}
+    ]
+  }
+}

package/skill/examples/14_dashboard.json

@@ -0,0 +1,28 @@
+{
+  "type": "dashboard",
+  "title": "Q3 performance dashboard",
+  "subtitle": "Company KPIs · revenue · growth",
+  "width": 1200,
+  "height": 760,
+  "data": {
+    "cards": [
+      { "label": "Revenue", "value": "$1.28M", "delta": "+12.4%", "deltaDir": "up" },
+      { "label": "Gross margin", "value": "71%", "delta": "+1.8 pp", "deltaDir": "up" },
+      { "label": "Active users", "value": "48.2k", "delta": "+6.1%", "deltaDir": "up" },
+      { "label": "Churn", "value": "2.3%", "delta": "-0.4 pp", "deltaDir": "down" }
+    ],
+    "bar": {
+      "categories": ["Americas", "EMEA", "APAC"],
+      "series": [
+        { "name": "New", "data": [31, 21, 16] },
+        { "name": "Expansion", "data": [12, 9, 7] }
+      ]
+    },
+    "line": {
+      "categories": ["Apr", "May", "Jun", "Jul", "Aug", "Sep"],
+      "series": [
+        { "name": "MRR ($k)", "data": [820, 870, 910, 980, 1040, 1120] }
+      ]
+    }
+  }
+}

package/skill/references/brand-style-mapping.md

@@ -0,0 +1,58 @@
+# Mapping a brand style guide → chart tokens
+
+How to translate a company's brand guidelines into the `brands/*.json` token file.
+
+## Colors
+
+| Brand guideline element | Token | Notes |
+|---|---|---|
+| Primary + secondary + accent colors | `colors.categorical[]` | Series colors. Order them by visual priority; the 1st is the "hero" hue (also used for heatmap ramps). |
+| Page/canvas color | `colors.background` | White-ish for light mode, near-black for dark. |
+| Card/panel color | `colors.surface` | KPI cards, tooltip background. Slightly off the background. |
+| Body text color | `colors.text` | Titles, data labels. |
+| Secondary text | `colors.textMuted` | Axis labels, subtitles, legend. |
+| Hairline/divider | `colors.axis`, `colors.grid` | Axis lines vs split (grid) lines — grid is fainter. |
+| Success / error | `colors.positive`, `colors.negative` | KPI deltas, up/down. |
+
+You only need to supply `categorical` + `background`; the rest derive from `text`/`background`
+if omitted. The palette is then **auto-extended and contrast-checked**: brands rarely give 8+
+series colors, so `lib/palette.mjs` rotates hue (golden angle) and nudges lightness to fill in
+distinguishable, legible extras.
+
+### Contrast (accessibility)
+
+Every series/text color is checked against the background and nudged in lightness until it clears
+a minimum contrast ratio (WCAG-style luminance math). Aim for **≥ 3:1** for large graphical
+elements and **≥ 4.5:1** for small text. On dark brands, push series colors lighter; on light
+brands, darker. The skill does this automatically (`ensureContrast`), but if you hand-pick colors,
+sanity-check them against the background.
+
+Reference: <https://www.w3.org/TR/WCAG21/#contrast-minimum>
+
+## Typography
+
+| Brand guideline element | Token | Notes |
+|---|---|---|
+| Body / UI typeface | `fonts.family` | Axis labels, legend, data labels, KPI labels. |
+| Display / heading typeface | `fonts.titleFamily` | Chart titles, KPI values (falls back to `family`). |
+| Mono typeface (optional) | `fonts.monoFamily` | For code-like figures if you want it. |
+| Base text size | `fonts.baseSize` | px; other sizes scale from it. |
+| Weights | `fonts.weights` | `{ regular, medium, bold }`. |
+| Webfont files | `fonts.faces[]` | `{ family, weight, url, file? }` — `url` (woff2) for SVG, optional local `file` (ttf/otf) for PNG. |
+
+Match the brand's actual type scale: a display serif for titles + a clean sans for data reads as
+intentional; one default sans everywhere reads as generic. See `fonts-and-svg-embedding.md` for
+how the fonts actually get into the output.
+
+## Shape / tone
+
+| Token | Effect |
+|---|---|
+| `shape.barRadius` | Bar corner rounding (0 = sharp/corporate, 6–8 = friendly). |
+| `shape.lineWidth` | Line series thickness. |
+| `shape.symbolSize` | Point/marker size. |
+| `shape.gridline` | `solid` \| `dashed` \| `none` — gridline style (or hide for a minimal look). |
+| `mode` | `light` \| `dark` — sets default neutrals if you don't specify them. |
+
+A finance/enterprise brand → sharp bars, solid thin gridlines, restrained palette. A consumer
+brand → rounded bars, dashed/none gridlines, brighter palette.