Flint 0.5

.github/release-notes/0.5.0.md

@@ -0,0 +1,69 @@
+Flint 0.5 introduces formal visual themes: one specification can now carry
+layout behavior, semantic presentation, and visual identity across an entire
+chart library.
+
+### Define the visual system once
+
+Add `theme_spec` beside `chart_spec`. The chart spec continues to define what
+the chart means; the theme defines how that meaning is presented.
+
+```json
+{
+  "chart_spec": {
+    "chartType": "Bar Chart",
+    "encodings": {
+      "x": { "field": "region" },
+      "y": { "field": "revenue" }
+    }
+  },
+  "theme_spec": "economist"
+}
+```
+
+Themes participate in compilation. They can guide spacing and density, labels
+and legends, axes and annotations, mark geometry, typography, color, and chart
+furniture while adapting those decisions to each chart.
+
+### Start from nine visual themes
+
+Flint ships New York Times, Economist, Swiss, Nature, McKinsey, Datawrapper,
+Power BI, Power BI Light, and Cartoon presets. The
+[visual-theme wall](https://microsoft.github.io/flint-chart/#/themes) applies
+each preset to the same set of charts for direct comparison.
+
+### Create a brand theme
+
+Pass a custom `ThemeSpec`, or inherit a built-in preset and override only the
+decisions that should differ:
+
+```json
+{
+  "theme_spec": {
+    "extends": "economist",
+    "id": "our-brand",
+    "ink": {
+      "series": {
+        "single": "#6b3fa0"
+      }
+    }
+  }
+}
+```
+
+Nested objects merge; arrays and scalar values replace inherited values. See
+[Using themes](https://microsoft.github.io/flint-chart/#/documentation/theme-spec)
+for the complete vocabulary and examples.
+
+### Use themes with agents
+
+The MCP server adds `list_themes` so an agent can inspect the available visual
+systems and their authoring guidance. The interactive MCP App also exposes a
+theme picker for Vega-Lite charts.
+
+ThemeSpec is currently realized by the Vega-Lite backend. Other backends
+continue to accept the shared Flint input but do not yet apply `theme_spec`.
+
+See the [changelog](https://github.com/microsoft/flint-chart/blob/main/CHANGELOG.md)
+for the complete technical summary.
+
+**Full Changelog**: https://github.com/microsoft/flint-chart/compare/0.4.1...0.5.0

CHANGELOG.md

@@ -11,6 +11,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Formal visual themes for Vega-Lite through the new top-level `theme_spec`
+  field. Callers can select one of nine built-in presets, provide a custom
+  `ThemeSpec`, or inherit a preset with `extends` and override selected fields.
+  Nested objects merge while arrays and scalar values replace inherited values.
+- A semantic theme-grounding system that applies layout behavior, presentation
+  rules, mark geometry, typography, color, labels, legends, axes, annotations,
+  and chart furniture as one visual system across chart types and data shapes.
+- Public theme APIs: `ThemeSpec`, `ThemePreset`, `THEME_PRESETS`,
+  `listThemePresets()`, and `resolveThemeSpec()`.
+- Theme discovery in the MCP server through `list_themes`, plus preset selection
+  in the interactive MCP App.
+- A public visual-theme wall, a complete **Using themes** guide, and
+  preset/custom/inherited live examples on the Flint project site.
+
+### Changed
+
+- Vega-Lite assembly now grounds the selected theme before layout and realizes
+  its decisions throughout compilation instead of applying a post-render style
+  layer. Existing inputs without `theme_spec` retain Flint's default behavior.
+
 ## [0.4.1] - 2026-07-27
 
 ### Changed

README.md

@@ -6,7 +6,7 @@
 [![CI](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**Please visit:** [**Flint Project Site**](https://microsoft.github.io/flint-chart/) | [**MCP Server Guide**](https://microsoft.github.io/flint-chart/#/mcp) | [**中文主页**](https://microsoft.github.io/flint-chart/#/zh)
+**Please visit:** [**Flint Project Site**](https://microsoft.github.io/flint-chart/) | [**Visual Themes**](https://microsoft.github.io/flint-chart/#/themes) | [**MCP Server Guide**](https://microsoft.github.io/flint-chart/#/mcp) | [**中文主页**](https://microsoft.github.io/flint-chart/#/zh)
 
 Flint is a visualization intermediate language that lets **AI agents create
 expressive, polished visualizations from simple, human-editable chart specs**.
@@ -38,6 +38,9 @@ This repo contains two main components:
   semantic types such as `Rank`, `Temperature`, `Price`, or `Country`.
 - **Automatic layout.** Flint adapts sizing, spacing, labels, marks, and legends
   to the data cardinality, chart design, and canvas constraints.
+- **Formal visual themes.** Define layout behavior, semantic presentation, and
+  visual identity once, then apply them across a chart library with a preset,
+  custom `ThemeSpec`, or inherited theme.
 - **Multiple backends.** Compile one input to backend-native output across
   [Vega-Lite](https://vega.github.io/vega-lite/),
   [ECharts](https://echarts.apache.org/),
@@ -110,6 +113,43 @@ const plotlyFigure = assemblePlotly(input);
 const excelArtifact = assembleExcel(input);
 ```
 
+## Apply Visual Themes
+
+`theme_spec` sits beside `chart_spec`: the chart spec defines what the chart
+means, while the theme defines how that meaning is presented. A theme can guide
+layout, labels, legends, axes, mark geometry, typography, and color as one
+coherent visual system.
+
+Use one of Flint's nine built-in presets:
+
+```ts
+const themedSpec = assembleVegaLite({
+  ...input,
+  theme_spec: 'economist',
+});
+```
+
+Or inherit a preset and override only the decisions that belong to your brand:
+
+```ts
+const brandedSpec = assembleVegaLite({
+  ...input,
+  theme_spec: {
+    extends: 'economist',
+    id: 'our-brand',
+    ink: {
+      series: { single: '#6b3fa0' },
+    },
+  },
+});
+```
+
+Nested objects merge; arrays and scalar values replace the inherited value.
+ThemeSpec currently affects Vega-Lite output. Compare all presets on the
+[theme wall](https://microsoft.github.io/flint-chart/#/themes) and see
+[Using themes](docs/theme-spec.md) for the complete custom and inherited-theme
+reference.
+
 See the [API reference](docs/api-reference.md), backend references for
 [Vega-Lite](docs/reference-vegalite.md), [ECharts](docs/reference-echarts.md),
 [Chart.js](docs/reference-chartjs.md), [Plotly](docs/reference-plotly.md), and
@@ -160,6 +200,7 @@ flint-chart/
 The [project site](https://microsoft.github.io/flint-chart/) is the main entry
 point for examples, the live editor, and concept docs. For source-level
 references, start with the [API reference](docs/api-reference.md), the
+[theme guide](docs/theme-spec.md), the
 [Flint MCP project page](https://microsoft.github.io/flint-chart/#/mcp), or the
 [Development guide](docs/DEVELOPMENT.md). See the [changelog](CHANGELOG.md) for
 notable changes in each release.

agent-skills/flint-chart-author/SKILL.md

@@ -83,15 +83,19 @@ published, use the npm package or MCP server for released workflows.
 interface ChartAssemblyInput {
   // Bound by the HOST or by you, depending on the situation (see below).
   data: { values: any[] } | { url: string };
-  semantic_types?: Record<string, string>;   // field → semantic type  ← you write this
+  semantic_types?: Record<string, string | SemanticAnnotation>;  // field → type ( ← you write this)
   chart_spec: {                               //                        ← you write this
     chartType: string;                        // e.g. "Scatter Plot"
+    title?: string;                           // the headline — write one
+    subtitle?: string;                        // what is measured, of whom, when, in what units
     encodings: Record<string, EncodingValue>; // channel → { field, ... } (or array)
     baseSize?: { width: number; height: number };    // target layout size, default 400×320
     canvasSize?: { width: number; height: number };  // optional hard ceiling on stretch
     chartProperties?: Record<string, any>;    // per-chart tuning (optional)
   };
   options?: Record<string, any>;              // global layout options (rarely needed)
+  field_display_names?: Record<string, string>; // field → readable axis/legend title
+  theme_spec?: string | ThemeSpec;            // design language, e.g. "economist" (Vega-Lite only)
 }
 ```
 
@@ -167,6 +171,49 @@ For a Vega-Lite-specific style tweak:
 This edited Vega-Lite spec is no longer a portable Flint spec. Do not send it to
 `render_chart`; use `render_chart` only for Flint `ChartAssemblyInput`.
 
+## Write a headline
+
+Set `chart_spec.title` to the finding, in a sentence, and `chart_spec.subtitle`
+to the reading of it — what is measured, of whom, when, in what units:
+
+```
+title:    "A pyramid that is no longer a pyramid"
+subtitle: "United States population by age and sex, 2020, millions"
+```
+
+`Jan`, `Cairo`, `Chrome` name their own kind; `26`, `5,300`, `0.42` do not, and
+the headline is where they get named. Leave it out only where the chart is not
+read on its own — a sparkline in a cell, a tile under its own caption. Nothing
+breaks: with no headline to lean on, the compiler keeps the axis titles instead.
+
+## Design languages (`theme_spec`)
+
+Name a house Flint ships and the compiler styles the chart to it:
+
+```json
+{ "chart_spec": { ... }, "theme_spec": "economist" }
+```
+
+| id | what it is for |
+| --- | --- |
+| `nyt` | Newsroom graphics: headline states the finding, values on the marks, series named at their ends. |
+| `economist` | Print weekly: compact, flat headline over a deck, units repeated down the ruler. |
+| `swiss` | International Typographic Style: strong grid structure, black typography, and a focused red accent. |
+| `nature` | Journal figure: small panel, axis titles with units, statistics beside the fit. |
+| `mckinsey` | Consulting deck: wide bands, every value printed, headline states the takeaway. |
+| `datawrapper` | Embedded web chart: narrow column, plain headline and deck, rule under the footer. |
+| `powerbi` | Dashboard tile: compact, legend to the right, latest point emphasised. |
+| `powerbi-light` | Light dashboard tile: white canvas, fine gridlines, and bright categorical color. |
+| `cartoon` | Playful illustration: warm paper, rounded type, bold outlines, and bright color. |
+
+A house governs the visual only — you still choose the fields, the aggregation
+and the sort. Where a house depends on something only you can supply, it says
+so: call `list_themes` with an `id` for that house's guidance, and read it
+*before* writing the chart spec, since it may change how you prepare the data.
+Vega-Lite only for now. You can also pass a custom `ThemeSpec`, or use
+`{ "extends": "economist", ... }` to inherit a preset and override selected
+fields.
+
 ## Step 1 — pick `chartType`
 
 Use one of the registered names **exactly**. Vega-Lite is the default and
@@ -250,8 +297,8 @@ support a subset (verify if targeting a non-VL backend):
   `"Funnel"`, `"Treemap"`, `"Sunburst"`, `"Sankey"`,
   `"Parallel Coordinates"`, `"Graph"`, `"Tree"`.
 - **Chart.js** supports: Scatter, Bubble, Bar, Grouped Bar, Stacked Bar,
-  Combo, Line, Bump, Area, Range Area, Pie, Doughnut, Histogram, Radar, Rose,
-  Slope, Connected Scatter.
+  Lollipop, Bump, Combo, Line, Area, Range Area, Pie, Doughnut, Histogram,
+  Radar, Rose, Slope, Connected Scatter.
 
 You do not need to call the library or inspect its source to author the
 input — pick from this table.
@@ -333,6 +380,29 @@ What choosing well gets you (automatically):
 If you don't know, use `Quantity` for numbers, `Category` for strings,
 `Date`/`DateTime` for date-shaped values. Do **not** invent type names.
 
+### Saying more than the type name
+
+A field's entry can be an object instead of a string when the type alone
+understates what you know:
+
+```json
+"semantic_types": {
+  "anomaly": { "semanticType": "Quantity", "unit": "°C", "divergingMidpoint": 0 },
+  "rating":  { "semanticType": "Score", "intrinsicDomain": [1, 5] }
+}
+```
+
+- `unit` — the unit or currency code: `"USD"`, `"°C"`, `"kg"`.
+- `intrinsicDomain` — the field's own bounds, for bounded scales only: `[1, 5]`
+  for a five-star rating, `[0, 100]` for a percentage score. Not for
+  open-ended measures.
+- `divergingMidpoint` — where the middle colour of a diverging scale sits.
+  Set it if you can tell what the reader is comparing against; leave it out if
+  you can't.
+- `sortOrder` — the order the categories should appear in, when the order in
+  the data is not the one you want and it isn't alphabetical either:
+  `["Low", "Medium", "High"]`. For a handful of categories, not a long list.
+
 ## Chart-level properties (`chartProperties`)
 
 `chartProperties` is an optional per-chart tuning map. Set a property only
@@ -365,7 +435,8 @@ derived). Values are clamped to the ranges shown.
 | Lollipop | `dotSize` | 20–300 (80) | Circle size (px) |
 | Waterfall | `cornerRadius` | 0–8 (0) | Round bar corners |
 | Waterfall | `totals` | `auto` \| `none` \| `first` \| `last` \| `both` (`auto`) | Which bars anchor to zero as totals (only when no Type column) |
-| Waterfall | `showTextLabels` | boolean (false) | Render value labels on bars |
+| Waterfall | `showTextLabels` | boolean (false) | Legacy spelling of `showValueLabels`; still accepted |
+| Bar / Grouped Bar / Stacked Bar / Lollipop / Pyramid / Pie / Donut / Heatmap / Waterfall | `showValueLabels` | boolean | Print the numbers on the marks. Works with or without a theme: unset, it follows the house's own habit at this density (and with no house named, stays off), so the default the compiler reports is always the honest one. Set it to overrule that for one chart. Reported inapplicable (and ignored) where the marks are too dense to carry readable numbers, or where the template already writes its own text, so it is never a control that does nothing. On a stacked bar each segment prints its own value in the middle of the segment (at the edge it would read as the running total); segments too thin to hold a line of text go unlabelled, and a normalized stack prints each segment's share rather than its raw value, since the share is what the length shows. The printed number is rounded to roughly three significant figures — with a k/M suffix once the values get long, and enough decimals that the smallest value in the series still says something — so a raw `3.14159265` lands as `3.14` and a series of `0.001` to `5000` reads at both ends. Rounding never goes so far that two marks of different size print the same number, or that a non-zero value prints as `0`; where a house asked for a coarser precision than that, the digits are raised until the labels agree with the marks. |
 | Regression | `regressionMethod` | `linear` \| `log` \| `exp` \| `pow` \| `quad` \| `poly` (`linear`) | Fit method |
 | Regression | `polyOrder` | 1–5 (3) | Polynomial order (when `poly`) |
 | Radar | `filled` | boolean (true) | Fill the polygon |
@@ -395,6 +466,8 @@ default:
 - **Sort a category axis by its measure:** `encodings.x = { field: "name", sortBy: "y", sortOrder: "descending" }`.
 - **Pick a color scheme:** `encodings.color = { field: "region", scheme: "tableau10" }`.
 - **Override an inferred type:** `encodings.x = { field: "year", type: "ordinal" }` (e.g. treat a year as discrete bands).
+- **Use readable field titles:** `field_display_names = { percentageOfCountries: "Percentage of countries" }`.
+  Keep encodings bound to the real column name; Flint uses the display name for axis titles and legend headers.
 - **Resize the chart:** Flint sizes from two numbers — `baseSize` (the *target*
   it aims for, default 400×320) and `canvasSize` (a *hard ceiling* it may never
   exceed). With dense data the chart stretches from base toward the ceiling.

docs/DEVELOPMENT.md

@@ -68,5 +68,7 @@ Start with the guide that matches the surface you want to extend:
 ## Test coverage
 
 - **Smoke tests:** `packages/flint-js/tests/smoke.test.ts`
-- **Visual coverage:** [Gallery](/gallery), driven by `TEST_GENERATORS` in test-data
+- **Complete visual coverage:** [Full test cases](/playground/full-test-cases), driven by `TEST_GENERATORS` in `packages/flint-js/src/test-data/`
+- **Curated examples:** [Gallery](/gallery)
 - **Shared fixtures:** `shared/test-data/`, consumed by JS and Python tests
+- **Coverage matrices and authoring workflow:** [Chart engine test plan](/documentation/test-plan)

docs/adding-a-backend.md

@@ -111,9 +111,13 @@ Register in `templates/index.ts`: import defs, add them to the category map, and
 # §5 Site and gallery
 
 - **Gallery dev server:** `npm run site` from the repo root, then open `/gallery`
+- **Full visual matrix:** open `/playground/full-test-cases`; it renders every generator registered in `packages/flint-js/src/test-data/index.ts`
 - **Supported backends:** update `site/src/shared/supported-backends.ts` if the new backend should appear in the UI
 - **Renderers:** only add a new React view (`site/src/components/`) when the spec format cannot reuse `VegaLiteView`, `EChartsView`, or `ChartjsView`. `TripleChart` currently covers VL + ECharts + Chart.js.
 
+Use the [Chart engine test plan](/documentation/test-plan) to choose normal,
+semantic, density, and edge-case coverage for backend bring-up.
+
 Optional: wire the assembler into `agent-skills/mcp-server/` if MCP clients should be able to call it.
 
 ---
@@ -134,5 +138,6 @@ A backend is ready when:
 # §7 Related
 
 - [Extending chart templates](/documentation/adding-a-chart-template) — `ChartTemplateDef` authoring
+- [Chart engine test plan](/documentation/test-plan) — shared cases and backend bring-up coverage
 - [Auto Layout Algorithm](/documentation/layout-model) — what `computeLayout()` expects
 - [API reference](/documentation/api-reference) — `ChartAssemblyInput` and assembler entry points

docs/api-reference.md

@@ -116,6 +116,8 @@ interface ChartAssemblyInput {
   semantic_types?: Record<string, string | SemanticAnnotation>;
   chart_spec: {
     chartType: string;
+    title?: string;                                    // headline
+    subtitle?: string;                                 // deck: what is measured, of whom, when, in what units
     encodings: Record<string, ChartEncoding | string>;  // string = field shorthand
     baseSize?: { width: number; height: number };      // target layout size, default 400×320
     canvasSize?: { width: number; height: number };    // optional hard ceiling on stretch
@@ -137,11 +139,30 @@ interface ChartAssemblyInput {
 
 Maps column name → semantic type. This drives encoding type, formatting, aggregation defaults, color class, and layout. See [Semantic Type](/documentation/semantic-types).
 
+### `field_display_names`
+
+Maps raw column names to readable presentation labels used for axis titles and
+legend headers. Keep encodings bound to the original field names:
+
+```ts
+{
+  field_display_names: {
+    percentageOfCountries: 'Percentage of countries'
+  },
+  chart_spec: {
+    chartType: 'Bar Chart',
+    encodings: { x: 'country', y: 'percentageOfCountries' }
+  }
+}
+```
+
 ### `chart_spec`
 
 | Field | Description |
 |-------|-------------|
 | `chartType` | Template name — must match a backend registry entry (`"Bar Chart"`, `"Heatmap"`, …) |
+| `title` | The headline. Write one: `Jan` and `Cairo` name their own kind, `26` and `5,300` do not, and a theme that omits axis titles is delegating that naming to the headline. Vega-Lite only for now; where no headline is given, the compiler puts the axis titles back. |
+| `subtitle` | The deck — what is measured, of whom, when, in what units. |
 | `encodings` | Channel → encoding map |
 | `baseSize` | **Target** layout size in pixels (default 400×320): the size the chart aims for with typical data. Dense data may stretch past it, up to the ceiling. |
 | `canvasSize` | **Hard ceiling:** the maximum size the chart may ever reach, including faceted grids. If omitted, the ceiling is `baseSize × options.maxStretch` (default 1.5×). Per-dimension caps are `βx = canvasSize.width / baseSize.width`, `βy = canvasSize.height / baseSize.height` (each ≥ 1). The base is clamped to the ceiling, so a `canvasSize` on its own acts as a fixed box the chart fills and shrinks to fit without overflowing. |