Flint 0.5

.github/release-notes/0.5.0.md

@@ -0,0 +1,127 @@
+# Flint 0.5.0: Formal visual themes
+
+Flint 0.5 introduces `ThemeSpec`, a formal specification for applying a
+coherent design system across an entire chart library. Instead of requiring
+creators or agents to reproduce design guidance chart by chart, a ThemeSpec
+participates directly in compilation and adapts to the chart's semantics,
+data, cardinality, and available space.
+
+A ThemeSpec shapes compilation in three stages. Using resolved semantic
+information, it:
+
+- governs layout constraints and dynamics, including density, spacing, sizing,
+  and stretch limits;
+- conditionally resolves visual preferences for labels, legends, axes,
+  annotations, and semantic roles; and
+- supplies design fixtures such as typography, color, surfaces, mark geometry,
+  and structural line styles to backend-specific code generation.
+
+<p align="center">
+  <img width="100%" alt="ThemeSpec shaping the Flint compilation process through resolved semantics, layout constraints, visual preferences, and design fixtures." src="https://raw.githubusercontent.com/microsoft/flint-chart/2f147ef3d068a8ecf26ec10ad0a50c01c862f0ab/docs/figs/theme-spec-expl.png" />
+  <br>
+  <sub>ThemeSpec participates throughout compilation, from resolved semantics and layout dynamics to conditional visual preferences and backend design fixtures.</sub>
+</p>
+
+This release also adds ten built-in themes, custom and inherited ThemeSpecs,
+public theme APIs, a visual-theme explorer and Theme Lab, plus theme discovery
+and authoring support in the Flint MCP server and MCP App.
+
+## Use a visual theme
+
+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"
+}
+```
+
+## Ten built-in themes
+
+Flint ships New York Times, Economist, Swiss, Nature, McKinsey, Datawrapper,
+Power BI, Power BI Light, Pop, and Cartoon presets. The
+[visual-theme explorer](https://microsoft.github.io/flint-chart/#/themes)
+applies each preset to the same set of charts for direct comparison.
+
+<p align="center">
+  <a href="https://microsoft.github.io/flint-chart/#/themes?theme=economist&amp;layout=banner">
+    <img width="100%" alt="Twelve charts rendered with Flint's Economist theme." src="https://raw.githubusercontent.com/microsoft/flint-chart/d4326cbadd90c8bd2bb642b778be33d0801161f5/docs/figs/flint-theme-economist.png" />
+  </a>
+  <br>
+  <sub><strong>Economist</strong> — compact editorial graphics with a strong red accent.</sub>
+</p>
+
+<p align="center">
+  <a href="https://microsoft.github.io/flint-chart/#/themes?theme=swiss&amp;layout=banner">
+    <img width="100%" alt="Twelve charts rendered with Flint's Swiss theme." src="https://raw.githubusercontent.com/microsoft/flint-chart/d4326cbadd90c8bd2bb642b778be33d0801161f5/docs/figs/flint-theme-swiss.png" />
+  </a>
+  <br>
+  <sub><strong>Swiss</strong> — typographic structure, restrained color, and a clear visual grid.</sub>
+</p>
+
+<p align="center">
+  <a href="https://microsoft.github.io/flint-chart/#/themes?theme=pop&amp;layout=banner">
+    <img width="100%" alt="Twelve charts rendered with Flint's Pop theme." src="https://raw.githubusercontent.com/microsoft/flint-chart/d4326cbadd90c8bd2bb642b778be33d0801161f5/docs/figs/flint-theme-pop.png" />
+  </a>
+  <br>
+  <sub><strong>Pop</strong> — bold color, emphatic marks, and playful graphic contrast.</sub>
+</p>
+
+## 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.
+
+## Tools and integrations
+
+- The [visual-theme explorer](https://microsoft.github.io/flint-chart/#/themes)
+  compares presets across the same chart wall.
+- [Theme Lab](https://microsoft.github.io/flint-chart/#/theme-lab) tests custom
+  ThemeSpecs across chart types and data shapes.
+- The MCP server and MCP App add theme discovery, preset selection, and custom
+  ThemeSpec support through `list_themes`.
+- The bundled `flint://theme-skill` resource and `author_flint_theme` prompt
+  help agents translate design guidance into reusable ThemeSpecs.
+- Public APIs include `ThemeSpec`, `ThemePreset`, `THEME_PRESETS`,
+  `listThemePresets()`, and `resolveThemeSpec()`.
+- The theme explorer, Theme Lab, and authoring guidance are available in
+  English and Chinese.
+
+The release also improves Vega-Lite logarithmic tick and grid spacing, line
+endpoint guides, and heatmap grid treatment.
+
+ThemeSpec is currently realized by the Vega-Lite backend. Other backends still
+accept the shared Flint input but do not yet apply `theme_spec`. Existing inputs
+without a theme retain Flint's default behavior.
+
+See [Using themes](https://microsoft.github.io/flint-chart/#/documentation/theme-spec)
+for the complete vocabulary and examples.
+
+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.0...0.5.0

CHANGELOG.md

@@ -11,6 +11,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-05
+
+### Added
+
+- Formal visual themes for Vega-Lite through the new top-level `theme_spec`
+  field. Callers can select one of ten 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.
+- The `pop` preset, a high-energy extension of Swiss with process colors,
+  strong structure, and chart-aware grid and heatmap treatment.
+- 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.
+- Bundled ThemeSpec authoring guidance through the `flint://theme-skill`
+  resource and `author_flint_theme` prompt. Custom ThemeSpecs remain available
+  in the MCP App while callers compare presets, without becoming global themes.
+- A public visual-theme explorer with regular grid and screenshot-friendly
+  scattered-poster layouts, a compact two-row banner composition, large
+  chart/spec previews, a complete **Using themes** guide, and
+  preset/custom/inherited live examples on the Flint project site.
+- Theme Lab, an interactive editor for authoring a ThemeSpec and testing it
+  against a diverse wall of charts, with built-in Signal Studio, Microsoft
+  Fluent, and People's Daily examples.
+- Complete English and Chinese localization for the public theme explorer,
+  Theme Lab, navigation, and MCP theme-authoring guidance.
+
+### 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.
+- Vega-Lite logarithmic axes choose readable powers-of-ten or 1/2/5 tick and
+  grid spacing from the transformed scale span and available pixels on either
+  axis. Two-position line axes suppress asymmetric endpoint guides, while
+  heatmaps use cell boundaries instead of redundant axis grids.
+
 ## [0.4.1] - 2026-07-27
 
 ### Changed
@@ -178,7 +218,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Treated only lowercase `start` and `end` Waterfall Type values as total
   anchors in Vega-Lite; other values now remain floating deltas colored by sign.
 
-[Unreleased]: https://github.com/microsoft/flint-chart/compare/0.4.1...HEAD
+[Unreleased]: https://github.com/microsoft/flint-chart/compare/0.5.0...HEAD
+[0.5.0]: https://github.com/microsoft/flint-chart/compare/0.4.0...0.5.0
 [0.4.1]: https://github.com/microsoft/flint-chart/compare/0.4.0...0.4.1
 [0.4.0]: https://github.com/microsoft/flint-chart/compare/0.3.0...0.4.0
 [0.3.0]: https://github.com/microsoft/flint-chart/compare/88fbeb5ebf07f18a1cf661ebef71cc570b7425d6...0.3.0

README.md

@@ -6,19 +6,20 @@
 [![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)
-
-Flint is a visualization intermediate language that lets **AI agents create
-expressive, polished visualizations from simple, human-editable chart specs**.
-Instead of asking agents or developers to tune verbose chart configuration
-details such as scales, axes, spacing, labels, and layout, the Flint compiler
-derives optimized chart settings from the data, semantic types, chart type, and
-encodings. The result is a compact chart specification that agents can produce
-reliably, people can edit directly, and multiple backends can render as native
+**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 turn
+simple, human-editable chart specs into expressive, polished visualizations**.
+Rather than requiring agents or developers to tune verbose settings for scales,
+axes, spacing, labels, and layout, Flint derives those decisions from the data,
+semantic types, chart type, encodings, and an optional visual theme. Users can
+use a compact spec to create visually polished, brand-consistent charts rendered
+as native
 [Vega-Lite](https://vega.github.io/vega-lite/),
 [ECharts](https://echarts.apache.org/),
-[Chart.js](https://www.chartjs.org/), or
-[Plotly](https://plotly.com/javascript/) specs, and native Excel charts through Office.js.
+[Chart.js](https://www.chartjs.org/),
+[Plotly](https://plotly.com/javascript/) specs, or as native Excel charts
+through Office.js.
 
 This repo contains two main components:
 
@@ -38,6 +39,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/),
@@ -49,6 +53,11 @@ This repo contains two main components:
 
 ## Updates
 
+- **August 5, 2026** — Flint 0.5.0 introduces a [formal theme specification](https://microsoft.github.io/flint-chart/#/themes)
+  that allows designers and users to define a visual system once and apply it
+  consistently across an entire chart library. It includes ten presets: New
+  York Times, Economist, Swiss, Nature, McKinsey, Datawrapper, Power BI, Power
+  BI Light, Pop, and Cartoon. ([v0.5.0](https://github.com/microsoft/flint-chart/releases/tag/0.5.0))
 - **July 24, 2026** — Flint 0.4.0 adds 38 Plotly chart types and 18 native,
   editable Excel chart templates. ([v0.4.0](https://github.com/microsoft/flint-chart/releases/tag/0.4.0))
 - **July 19, 2026** — Flint 0.3.0 adds dynamic chart widgets that switch chart
@@ -110,6 +119,67 @@ 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 ten 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 explorer](https://microsoft.github.io/flint-chart/#/themes). See
+[Using themes](docs/theme-spec.md) for the complete custom and inherited-theme
+reference.
+
+<p align="center">
+  <a href="https://microsoft.github.io/flint-chart/#/themes?theme=economist&amp;layout=banner">
+    <img src="docs/figs/flint-theme-economist.png" alt="Twelve charts rendered with Flint's Economist theme." width="100%">
+  </a>
+  <br>
+  <sub><strong>Economist</strong> — compact editorial graphics with a strong red accent.</sub>
+</p>
+
+<p align="center">
+  <a href="https://microsoft.github.io/flint-chart/#/themes?theme=swiss&amp;layout=banner">
+    <img src="docs/figs/flint-theme-swiss.png" alt="Twelve charts rendered with Flint's Swiss theme." width="100%">
+  </a>
+  <br>
+  <sub><strong>Swiss</strong> — typographic structure, restrained color, and a clear visual grid.</sub>
+</p>
+
+<p align="center">
+  <a href="https://microsoft.github.io/flint-chart/#/themes?theme=pop&amp;layout=banner">
+    <img src="docs/figs/flint-theme-pop.png" alt="Twelve charts rendered with Flint's Pop theme." width="100%">
+  </a>
+  <br>
+  <sub><strong>Pop</strong> — bold color, emphatic marks, and playful graphic contrast.</sub>
+</p>
+
 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
@@ -128,7 +198,7 @@ For setup, start with the
 includes client configuration, usage examples, and links to deeper references.
 
 <p align="center">
-  <img src="docs/figs/flint-mcp-experience.png" alt="Agent chat showing Flint Chart as an MCP App with a grouped bar chart preview and chart options." width="100%">
+  <img src="docs/figs/flint-mcp-experience.png" alt="Agent chat showing Flint Chart as an MCP App with a grouped bar chart preview and chart options." width="720">
 </p>
 
 MCP calls let agents embed rows directly as `data.values`, or read local JSON,
@@ -140,26 +210,34 @@ use the standalone [agent skill](agent-skills/flint-chart-author/SKILL.md).
 ```
 flint-chart/
 ├── packages/
-│   ├── flint-js/          npm package `flint-chart` (TypeScript)
+│   ├── flint-js/            npm package `flint-chart` (TypeScript)
 │   │   └── src/
-│   │       ├── core/      semantics, layout, decisions, shared types
-│   │       ├── vegalite/  Vega-Lite backend
-│   │       ├── echarts/   ECharts backend
-│   │       ├── chartjs/   Chart.js backend
-│   │       └── test-data/ fixtures + generators (drive tests and the gallery)
-│   ├── flint-py/          Python port preview (package to be released)
-│   └── flint-mcp/         npm package `flint-chart-mcp` (MCP render server)
-├── site/                  Vite + React demo: landing, gallery, editor, docs
-├── agent-skills/          fallback copy of the MCP-served agent skill
-├── shared/test-data/      JSON fixtures shared across JS + Python
-└── docs/                  architecture and design documents
+│   │       ├── core/        semantics, themes, layout, decisions, shared types
+│   │       ├── chart-types/ shared chart definitions and template metadata
+│   │       ├── vegalite/    Vega-Lite backend
+│   │       ├── echarts/     ECharts backend
+│   │       ├── chartjs/     Chart.js backend
+│   │       ├── plotly/      Plotly backend
+│   │       ├── excel/       native Excel backend
+│   │       ├── gallery/     gallery assembly and generated references
+│   │       └── test-data/   fixtures and stress-test generators
+│   ├── flint-mcp/           MCP server, MCP App UI, assets, and tests
+│   └── flint-py/            Python port preview (package to be released)
+├── site/                    Vite + React project site, gallery, editor, and docs
+├── agent-skills/            chart- and theme-authoring skills for agents
+├── agents/                  agent and MCP server configuration
+├── shared/test-data/        JSON fixtures shared across JS and Python
+├── scripts/                 reference generation and theme audit tooling
+├── docs/                    user, API, backend, and architecture documentation
+└── design-docs/             design proposals and implementation research
 ```
 
 ### Documentation
 
 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/README.md

@@ -1,8 +1,14 @@
 # agent-skills/
 
-Agent skill for **flint-chart** — teaches LLMs and IDE agents how to produce
-correct, idiomatic `ChartAssemblyInput` JSON, then use it in the right
-workflow: MCP rendering, project integration, or backend compilation.
+Agent skills for **flint-chart** teach LLMs and IDE agents how to author
+portable chart and theme specifications.
+
+- [flint-chart-author/SKILL.md](flint-chart-author/SKILL.md) covers
+    `ChartAssemblyInput`, MCP rendering, project integration, and backend
+    compilation.
+- [flint-theme-author/SKILL.md](flint-theme-author/SKILL.md) translates brand
+    guidelines, websites, slide decks, and publication references into reusable
+    custom `ThemeSpec` JSON.
 
 ## How agents should use flint-chart
 
@@ -24,5 +30,5 @@ When the user wants more than a spec, the skill also tells the agent how to:
 - call `assembleVegaLite`, `assembleECharts`, or `assembleChartjs` in JS/TS;
 - use the Python package when it is published in a later release.
 
-See [flint-chart-author/SKILL.md](flint-chart-author/SKILL.md) for the full
-contract, worked examples, and the validation checklist.
+See the relevant skill for its full output contract, references, worked
+examples, and validation checklist.