@pixerate/editor 0.222.3 → 0.223.1

package/skills/pixerate-chart-choose-and-build/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: pixerate-chart-choose-and-build
+description: The chart building workflow in the Pixerate chart editor - starting from the question the chart answers, choosing the chart type for it (change over time, comparison, part of a whole, distribution, relationship, flow, geography), loading clean data in order, honest axes (bars from zero, log only for orders of magnitude), units and number formats, colours that colour-blind readers can tell apart, and checking before handing it over. Use when asked to make, build, create, choose, recommend or fix a chart or graph, visualise or plot data, pick the right chart, or make a chart clearer, more honest or accessible, or when recommend_chart, set_chart_data, update_chart or check_chart_colors are available. Load with pixerate-chart, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-chart
+---
+
+# Choosing and building a chart
+
+A chart answers one question. Name the question first ("how did revenue change over the
+year?", "which region sells most?"), and the type, the order of the data, the axes and the
+title follow from it. Build in few calls: data in one, style in one, then check the warnings,
+the colours and the numbers before anyone sees it.
+
+This skill is the method. `pixerate-chart` has the full tool reference; for titles, highlights,
+reference lines and notes that make the point, see `pixerate-chart-annotate`.
+
+## Goal and quality bar
+
+- The type fits the question (see the decision table).
+- The data is in a meaningful order: time in calendar order, categories sorted by value unless
+  they have a natural order.
+- Axes are honest: bars and areas start at zero; a log scale only when values span orders of
+  magnitude, and labelled as such; a second axis only for a second unit.
+- Units are stated (axis title or number `format`); the title says what the chart shows.
+- Colours pass `check_chart_colors` (`ok: true`) and there are at most about seven series
+  colours.
+- `get_chart` `summary.warnings` and `issues` are empty.
+
+## Inputs to confirm
+
+- **The question** the chart must answer, and for whom (a report, a slide, a dashboard).
+- **The data**: where it is (pasted, CSV, a spreadsheet, an Office file) and its units.
+- **House style** if the host has one (`check_chart_style`).
+
+## Working method
+
+1. **Read.** `get_chart` (the spec, the data table, warnings); `list_file_charts` when the
+   data is in an open Office file.
+2. **Name the question and choose the type.** `recommend_chart` suggests types for the data;
+   check its suggestion against the question (see the table).
+   **Check:** you can say the question in one sentence and why this type answers it.
+3. **Load clean data in one call.** `set_chart_data` with categories in the right order and one
+   series per measure (or `import_chart_csv`); numbers as numbers, gaps as `null`.
+   **Check:** `get_chart` `spec.categories` and each series' `values` line up as intended.
+4. **Style in one call.** `update_chart` with `type`, `title`, axis `title` and `format`,
+   `legend`, `stacking`, `orientation`, `dataLabels`. Bars from zero (`yAxis.min` null or 0).
+   **Check:** `get_chart` spec; `summary.description` reads as the chart you meant.
+5. **Colours.** `check_chart_colors`; fix failing pairs with `update_chart_series` `color` (a
+   palette such as `#4269d0` / `#efb118` separates for most colour vision), or
+   `apply_chart_preset` for a tested palette.
+   **Check:** `check_chart_colors` `ok: true`.
+6. **Look.** `render_chart` once after the batch; fix anything that does not read.
+
+## Decision table
+
+| Question | Type |
+| --- | --- |
+| How did it change over time? | `line` (one or a few series), `area` for totals, columns for few periods |
+| Which is biggest? Compare categories | `bar`, horizontal for long labels, sorted by value |
+| Part of a whole (few parts) | `pie` or `donut` (at most five slices), or a stacked bar |
+| Part of a whole, nested | `treemap`, `sunburst` (`set_chart_tree`) |
+| How are values distributed? | `histogram`, `box` |
+| Do two measures relate? | `scatter`, `bubble` for a third measure |
+| Before and after per category | `slope` |
+| Contributions to a total | `waterfall` |
+| Flows between stages | `sankey` (`set_chart_links`), `funnel` for one path |
+| Survey answers | `likert` |
+| By region on a map | `choropleth` |
+
+## Recipes
+
+**Trend over time.** `set_chart_data` with categories in calendar order → `update_chart`
+`{ type: "line", title, yAxis: { title: "Revenue (USD thousands)" } }` → `get_chart`.
+
+**Colour-blind fix.** `check_chart_colors` → `update_chart_series` `color` on the clashing series
+→ `check_chart_colors` again.
+
+**Honest bars.** `update_chart` `{ yAxis: { min: 0 } }`; when small differences matter, show the
+differences themselves (a bar of the change) or a dot plot rather than a cut axis.
+
+## Pitfalls
+
+- **Truncated bar axes** exaggerate differences; bars start at zero.
+- **Pie charts with many or similar slices** cannot be read; use a sorted bar.
+- **Red and green** as the only distinction fail for the most common colour-vision deficiency.
+- **Unsorted categories** without a natural order hide the ranking.
+- **Mixed units on one axis**, or a second axis for the same unit, mislead.
+- **Missing units** leave the reader guessing; put them in the axis title or format.
+
+## Tools used
+
+- `get_chart`, `render_chart`: the spec, data table, warnings, and a picture
+- `recommend_chart`: types that suit the data
+- `set_chart_data`, `import_chart_csv`, `transpose_chart`: load the data in order
+- `update_chart`, `update_chart_series`, `apply_chart_preset`: type, titles, axes, formats and colours
+- `check_chart_colors`, `check_chart_style`: colour-blind and house-style checks
+- `list_file_charts`, `load_file_chart`: data from open Office files
+- `undo_chart`: take back a step

package/skills/pixerate-chart-choose-and-build/evals/colour-blind-safe.json

@@ -0,0 +1,113 @@
+{
+	"prompt": "Some of our readers are colour-blind and can't tell the two years apart in this chart. Fix the colours without changing the data.",
+	"fixture": {
+		"editor": "chart",
+		"setup": [
+			{
+				"tool": "set_chart_data",
+				"args": {
+					"categories": [
+						"North",
+						"South",
+						"East",
+						"West"
+					],
+					"series": [
+						{
+							"name": "2025",
+							"values": [
+								12,
+								15,
+								9,
+								11
+							],
+							"color": "#d62728"
+						},
+						{
+							"name": "2026",
+							"values": [
+								14,
+								13,
+								12,
+								15
+							],
+							"color": "#2ca02c"
+						}
+					]
+				}
+			},
+			{
+				"tool": "update_chart",
+				"args": {
+					"type": "bar",
+					"title": "Sales by region"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the colours pass the colour-blind check",
+			"tool": "check_chart_colors",
+			"expect": {
+				"ok": true
+			}
+		},
+		{
+			"why": "the data is unchanged",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"categories": [
+						"North",
+						"South",
+						"East",
+						"West"
+					],
+					"series": [
+						{
+							"name": "2025",
+							"values": [
+								12,
+								15,
+								9,
+								11
+							]
+						},
+						{
+							"name": "2026",
+							"values": [
+								14,
+								13,
+								12,
+								15
+							]
+						}
+					]
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "check_chart_colors"
+		},
+		{
+			"tool": "update_chart_series",
+			"args": {
+				"series": "2025",
+				"color": "#4269d0"
+			}
+		},
+		{
+			"tool": "update_chart_series",
+			"args": {
+				"series": "2026",
+				"color": "#efb118"
+			}
+		},
+		{
+			"tool": "check_chart_colors"
+		}
+	]
+}

package/skills/pixerate-chart-choose-and-build/evals/honest-baseline.json

@@ -0,0 +1,81 @@
+{
+	"prompt": "This bar chart makes the differences between teams look huge, but they're small. Make it honest.",
+	"fixture": {
+		"editor": "chart",
+		"setup": [
+			{
+				"tool": "set_chart_data",
+				"args": {
+					"categories": [
+						"Team A",
+						"Team B",
+						"Team C",
+						"Team D"
+					],
+					"series": [
+						{
+							"name": "Satisfaction (%)",
+							"values": [
+								92,
+								95,
+								94,
+								97
+							]
+						}
+					]
+				}
+			},
+			{
+				"tool": "update_chart",
+				"args": {
+					"type": "bar",
+					"title": "Satisfaction by team",
+					"yAxis": {
+						"min": 90,
+						"max": 98
+					}
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "bars start at zero (or the chart is no longer bars)",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"$expr": "v.type !== 'bar' || v.yAxis.min === null || v.yAxis.min === 0"
+				}
+			}
+		},
+		{
+			"why": "the data is unchanged",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"series": [
+						{
+							"values": [
+								92,
+								95,
+								94,
+								97
+							]
+						}
+					]
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "update_chart",
+			"args": {
+				"yAxis": {
+					"min": 0,
+					"max": 100
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-chart-choose-and-build/evals/trend-over-time.json

@@ -0,0 +1,175 @@
+{
+	"prompt": "This is our 2026 monthly revenue in thousands of US dollars, pasted in a muddle. Make a chart that shows how revenue changed over the year.",
+	"fixture": {
+		"editor": "chart",
+		"setup": [
+			{
+				"tool": "set_chart_data",
+				"args": {
+					"categories": [
+						"Mar",
+						"Jan",
+						"Feb",
+						"Jun",
+						"Apr",
+						"May",
+						"Sep",
+						"Jul",
+						"Aug",
+						"Dec",
+						"Oct",
+						"Nov"
+					],
+					"series": [
+						{
+							"name": "Revenue",
+							"values": [
+								51,
+								42,
+								45,
+								61,
+								48,
+								55,
+								70,
+								58,
+								64,
+								82,
+								68,
+								75
+							]
+						}
+					]
+				}
+			},
+			{
+				"tool": "update_chart",
+				"args": {
+					"type": "pie"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "a line or area chart for change over time",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"type": {
+						"$in": [
+							"line",
+							"area"
+						]
+					}
+				}
+			}
+		},
+		{
+			"why": "months in calendar order, with their own values",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"categories": [
+						"Jan",
+						"Feb",
+						"Mar",
+						"Apr",
+						"May",
+						"Jun",
+						"Jul",
+						"Aug",
+						"Sep",
+						"Oct",
+						"Nov",
+						"Dec"
+					],
+					"series": [
+						{
+							"values": [
+								42,
+								45,
+								51,
+								48,
+								55,
+								61,
+								58,
+								64,
+								70,
+								68,
+								75,
+								82
+							]
+						}
+					]
+				}
+			}
+		},
+		{
+			"why": "a title and a value axis that says the unit",
+			"tool": "get_chart",
+			"expect": {
+				"spec": {
+					"title": {
+						"$match": "\\S"
+					},
+					"yAxis": {
+						"$expr": "/usd|\\$|dollar/i.test(v.title) || v.format.style === 'currency' || /\\$/.test(v.format.prefix || '')"
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "get_chart"
+		},
+		{
+			"tool": "set_chart_data",
+			"args": {
+				"categories": [
+					"Jan",
+					"Feb",
+					"Mar",
+					"Apr",
+					"May",
+					"Jun",
+					"Jul",
+					"Aug",
+					"Sep",
+					"Oct",
+					"Nov",
+					"Dec"
+				],
+				"series": [
+					{
+						"name": "Revenue",
+						"values": [
+							42,
+							45,
+							51,
+							48,
+							55,
+							61,
+							58,
+							64,
+							70,
+							68,
+							75,
+							82
+						]
+					}
+				]
+			}
+		},
+		{
+			"tool": "update_chart",
+			"args": {
+				"type": "line",
+				"title": "Revenue grew through 2026",
+				"yAxis": {
+					"title": "Revenue (USD thousands)"
+				}
+			}
+		}
+	]
+}