# flint-chart-author

Adopt this skill: https://proskills.md/skills/other/microsoft-flint-chart-github-extensions-flint-chart-skills-flint-chart-author

Page: https://proskills.md/skills/other/microsoft-flint-chart-github-extensions-flint-chart-skills-flint-chart-author
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .github/extensions/flint-chart/skills/flint-chart-author/SKILL.md
size: 8035
upstream: https://github.com/microsoft/flint-chart/blob/main/.github/extensions/flint-chart/skills/flint-chart-author/SKILL.md

````text
---
name: flint-chart-author
description: "Use when: the user asks to make or render charts with flint-chart, visualize tabular data, generate a ChartAssemblyInput, validate/render through MCP, or add Flint to a JS/TS project. Author the semantic spec, transform data before Flint when needed, install/import Flint only when executable code is needed, and reserve backend-specific style tweaks for after compiling from Flint."
---

# flint-chart: authoring and using a chart spec

## What you produce (and what you do NOT)

Your output is the **spec**: the `chart_spec` and `semantic_types` of a
`ChartAssemblyInput`. You reference data columns **by name**. The host
passes the resulting input to `assembleVegaLite`, `assembleECharts`,
or `assembleChartjs` to get a backend spec.

**You write the input spec, not the output spec.** And critically:

- **DO** emit `chart_spec` (chart type, channel→field mapping, properties)
  and `semantic_types` (field → semantic type).
- **Reference columns by name.** How `data` itself gets bound depends on
  the situation — a URL, a host-side variable, or embedded rows (see "How
  data gets bound"). Embedding is fine for small tables; just don't
  re-serialize a *large* dataset by hand, since that risks truncation and
  silent value corruption and wastes tokens.
- **Transform data before Flint.** If the requested chart needs aggregation,
  filtering, joins, pivots, derived columns, or long/wide reshaping beyond
  Flint's built-in static-series fold, use a coding, notebook, SQL, or data tool
  first. Then author the Flint spec against the transformed table.
- **Style after Flint, only when needed.** Author structure in Flint. For a
  presentation tweak Flint does not express (a reference line, annotation, or
  shaded band), use the Vega-Lite escape hatch — see "Post-Flint style
  customization". Never feed edited Vega-Lite JSON back to `render_chart`.

## When the user wants more than a spec

First decide which workflow the user is asking for:

- **Spec authoring only:** return a `ChartAssemblyInput` or its
  `semantic_types` + `chart_spec` pieces. Do not install packages or write
  renderer code unless asked.
- **MCP chart output:** if Flint MCP tools are available, **default to
  `create_chart_view`** whenever the user asks to see a chart — it opens an
  interactive, live-rendered view with a customization panel, and it validates
  the spec for you. Only fall back to `render_chart` (PNG/SVG) when the host has
  no App UI support or the user explicitly wants a static image. Use
  `validate_chart` to check a spec without rendering, `compile_chart` when the
  user wants backend-native JSON, and `list_chart_types` when you need the
  supported chart catalog.
- **Project integration, only when the user asks for code:** add Flint to an
  app, notebook, script, or agentic product, install/import the library, and
  call an assembler in code. Keep the same `ChartAssemblyInput` contract, then
  let the host render the backend result.

For MCP clients, the server can run with `npx`:

```bash
npx -y flint-chart-mcp
```

For JavaScript or TypeScript projects, install Flint first and add only the
renderer peer dependencies needed by the backend you will render:

```bash
npm install flint-chart
npm install vega vega-lite vega-embed  # browser Vega-Lite rendering
npm install echarts                    # ECharts rendering
npm install chart.js                   # Chart.js rendering
```

Then compile with the requested backend:

```ts
import { assembleChartjs, assembleECharts, assembleVegaLite } from 'flint-chart';

const vegaLiteSpec = assembleVegaLite(input);
const echartsOption = assembleECharts(input);
const chartjsConfig = assembleChartjs(input);
```

Python support is planned for a later release. Until the PyPI package is
published, use the npm package or MCP server for released workflows.

```ts
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
  chart_spec: {                               //                        ← you write this
    chartType: string;                        // e.g. "Scatter Plot"
    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)
}
```

## How data gets bound

Use the binding mode that matches the runtime. Do not mix them.

1. **Direct MCP rendering: embed rows.** When calling `render_chart`,
  `compile_chart`, or `validate_chart`, the tool arguments are JSON. If the
  data is small or already transformed by another tool, pass it as
  `data: { values: [...] }`. Do not pass runtime variable names in
  MCP tool calls — the MCP server cannot see your local variables.
2. **Direct MCP rendering: reference a local file.**
  The `flint-chart-mcp` server can load `data: { url: "..." }` from local
  `.json`, `.csv`, or `.tsv` files. By default any local file the agent can
  name is readable (relative paths resolve against the working directory); a
  hardened deployment may reject local file references entirely via
  `--disable-file-reference` (or `FLINT_MCP_DISABLE_FILE_REFERENCE`), in which
  case pass rows inline with `data.values`. Remote URL
  fetching is disabled. If the data must be transformed first, use a
  coding/data tool to write a small prepared file, then reference that file.
3. **Generated application or notebook code: bind runtime variables.** If the
  user asks you to add Flint to code, write normal data-loading code first and
  pass a real runtime value, e.g. `data: { values: rows }`, to
  `assembleVegaLite`, `assembleECharts`, or `assembleChartjs`. This variable
  pattern is for generated code, not for MCP tool calls.

For spec-only answers, return the `semantic_types` and `chart_spec` pieces and
state how the host should bind data. In the worked examples below, `data` is
shown as `{ values: [] }` to signal "host binds this" — focus on `chart_spec`
and `semantic_types`.

## Data transformation before charting

Flint is a chart compiler, not a data-wrangling layer. If the chart needs grouped
totals, time buckets, filters, joins, pivots, derived ratios, or a long-form
table, transform the data first with a host tool, then bind the prepared table
(see "How data gets bound"). Pick semantic types and channels for the transformed
columns, not for columns that no longer exist.

**Sanity-read the values first — don't chart blind.** Inspect the actual data
with your data tool (distinct values per category column, min/max per measure),
not just the column names, and watch for:

- **Embedded totals.** A category column may mix an aggregate level with its
  parts (e.g. `all` alongside `cage-free`/`caged`, or a `Total` region). Charting
  the total with its parts double-counts and flattens the parts — keep one or the
  other on a stacked/grouped/colored channel, not both.
- **Units.** Check whether a rate is a fraction (0–1) or already a percent
  (0–100) before tagging it `Percentage`; don't scale twice.
- **One real entity.** If your breakdown column has a single distinct value, the
  per-group chart collapses to one mark — the intended breakdown is likely a
  different column.

## Post-Flint style customization

Stay at the Flint level for structure (data, chart type, channels, transforms,
sizing, properties) — Flint specs stay portable and regenerate safely. Drop to
backend JSON only after a valid Flint chart exists, and only for a narrow
presentation change Flint does not expose (exact axis/legend/mark styling,
titles, annotations, reference lines, layout
````

## File: README.md
upstream: https://github.com/microsoft/flint-chart/blob/main/README.md

````text
<h1><img src="assets/flint-logo.svg" alt="" width="42" align="absmiddle"> Flint: A Visualization Language for the AI Era</h1>

[![npm: flint-chart](https://img.shields.io/npm/v/flint-chart.svg?label=npm%3A%20flint-chart)](https://www.npmjs.com/package/flint-chart)
[![npm: flint-chart-mcp](https://img.shields.io/npm/v/flint-chart-mcp.svg?label=npm%3A%20flint-chart-mcp)](https://www.npmjs.com/package/flint-chart-mcp)
[![arXiv: 2607.20775](https://img.shields.io/badge/arXiv-2607.20775-b31b1b.svg)](https://arxiv.org/abs/2607.20775)
[![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)
[![Discord](https://img.shields.io/badge/discord-chat-green?logo=discord)](https://discord.gg/hnm4Y8YX8)
[![WeChat](https://img.shields.io/badge/wechat-group-07C160?logo=wechat&logoColor=white)](#community)

[**Project site**](https://microsoft.github.io/flint-chart/) ·
[**中文主页**](https://microsoft.github.io/flint-chart/#/zh) ·
[**MCP server**](https://microsoft.github.io/flint-chart/#/mcp)

<p align="center">
  <img src="docs/figs/chartwall.png" alt="A wall of charts produced by Flint across its supported visualization backends." width="100%">
</p>

Flint is a visualization language that lets **AI agents reliably
create expressive, good-looking and interactive charts from simple,
human-editable chart specs**. It is available as an
[MCP server](https://microsoft.github.io/flint-chart/#/mcp) for everyday use
with your agent, and as an [npm library](https://www.npmjs.com/package/flint-chart)
for building interactive applications.

Flint supports **52 chart types across 5 rendering backends** —
[Vega-Lite](https://vega.github.io/vega-lite/), [ECharts](https://echarts.apache.org/),
[Chart.js](https://www.chartjs.org/), [Plotly](https://plotly.com/javascript/), and
native Excel charts — through one unified interface, with **14 themes and 23
interaction presets**. To create bespoke visualizations, design custom themes in
the [Theme Lab](https://microsoft.github.io/flint-chart/#/theme-lab) and build
[advanced interactions](https://microsoft.github.io/flint-chart/#/interactions/advanced)
with the Flint API.

https://github.com/user-attachments/assets/c1cda0fa-3ea7-41af-b3fd-a127bc83d641

<p align="center">
  <sub>🔊 Click the speaker icon for sound</sub>
  &nbsp;
  <a href="https://youtu.be/JAJy7ToczMs"><img src="https://img.shields.io/badge/Watch%20on-YouTube-FF0000?logo=youtube&logoColor=white" alt="Watch on YouTube" align="absmiddle"></a>
</p>

## Updates

- **October 19, 2026** — Flint 1.0 introduces
  [Flint Interactive](https://microsoft.github.io/flint-chart/#/interactions):
  interaction presets, semantic events, and an interaction API that connects
  charts to your app. ([changelog](CHANGELOG.md))
- **August 12, 2026** — Flint 0.5.1 extends visual themes to the Plotly backend
  and adds Vega-Lite Calendar Heatmap.
- **August 5, 2026** — Flint 0.5.0 introduces formal visual themes with preset
  themes, custom ThemeSpec authoring, and preset inheritance.
  ([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))

See the [changelog](CHANGELOG.md) for every release.

## Get started

### In your agent app (MCP server)

Chart right in the conversation with any MCP client, such as
[GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers),
[Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp),
Claude Code, Codex, or Cursor.

⚡ **Quick start:** paste this setup request into your agent and let it
configure Flint for the current project. For manual setup, see the
[MCP server guide](https://microsoft.github.io/flint-chart/#/mcp).

```text
Help me set up Flint as an MCP server named "flint"!

1. Add it to my client config, using whichever option my client supports:
   - a local (stdio) server: npx -y flint-chart-mcp
   - the hosted server over HTTP: https://flint.data-formulator.ai/mcp
2. Verify the setup by listing the available Flint chart types.
3. Show me a fun first chart: how many moons each planet has, in a Flint theme you like.
```

Then ask your agent for a chart, for example:

```text
Go to Yahoo Finance, find today's percentage change for the Magnificent Seven
tech stocks, and compare their performance with Flint in Economist style.
Let me hover to read each stock's change.
```

The agent can open an interactive chart right in the conversation, return a
static PNG or SVG, or produce a backend-native spec.

<p align="center">
  <img src="docs/figs/flint-mcp-chat.png" alt="An agent chat where the user asks for global temperatures since 1880 in a newspaper style with brushing, and Flint answers with a live, interactive line chart." width="520">
</p>

### Build with your coding agent

Are you a developer building agent apps? Use
[`flint-chart`](https://www.npmjs.com/package/flint-chart), Flint's npm library,
to bring charts into your apps, dashboards, and data stories:

```bash
npm install flint-chart
```

The library compiles Flint specs into backend-native chart specs and provides
React and vanilla JavaScript APIs for embedding interactive charts.

A Flint spec describes the data, semantic types, and field mappings, with
optional theme and interaction settings. In React, pass it to `<FlintChart>`
to embed an interactive chart:

```tsx
import type { ChartAssemblyInput } from 'flint-chart';
import { FlintChart } from 'flint-chart/react';

const spec: ChartAssemblyInput = {
  data: { values: [
    { Month: '2026-01', Users: 1200 },
    { Month: '2026-02', Users: 1800 },
  ] },
  semantic_types: { Month: 'YearMonth', Users: 'Quantity' },
  chart_spec: {
    chartType: 'Line Chart',
    encodings: { x: 'Month', y: 'Users' },
  },
  theme_spec: 'economist',
  interaction_spec: { interactions: [{ type: 'inspect-index' }] },
};

<FlintChart spec={spec} />
```

You can copy the following instruction to your coding agent to build a chart
with Flint, then adapt it to your data and app:

```text
Read Flint's chart authoring and interaction skills:
https://github.com/microsoft/flint-chart/blob/main/agent-skills/flint-chart-author/SKILL.md
https://github.com/microsoft/flint-chart/blob/main/agent-skills/flint-interaction-author/SKILL.md

Use these skills to add a chart to this app.
Install flint-chart and the renderer dependencies needed for this project.
Plot monthly users by region from our data in Economist style.
Let readers hover to compare regions at each month, and add a region selector
that updates the chart.
Integrate it with the app's existing layout and verify it works.
```

The agent can also generate backend-native specs or editable Excel charts
for reports and documents. See the [API reference](docs/api-reference.md),
[interaction API](docs/interaction-api.md), and
[live editor](https://microsoft.github.io/flint-chart/#/editor) for the
underlying APIs and examples.

## How it works

A Flint spec consists of the data, semantic types, the chart spec, and optional
theme and interaction specs. Instead of relying on complex user-side logic to
glue them together, the compiler resolves each part against the others and
composes a complete backend-native spec.

### 1. Describe data with semantic types

Fields are described with semantic types such as `Rank`, `YearMonth`, `Delta`,
or `Temperature`, along with their domains and units. The compiler uses them to
infer parsing, scales, axes, formatting, and colors — a short Flint spec becomes
a complete backend spec.

<p align="center">
  <img src="docs/figs/flint-compilation-pipeline.png" alt="A Flint spec with semantic types, theme and interaction compiled into a Vega-Lite spec and 
````
