Experimental

Visualization knowledge layer for agents by humans

chartcoach represents visualization design knowledge as guidelines that agents can retrieve, cite, apply, and improve. Each guideline links back to its original sources, so agents can explain where guidance comes from when reviewing charts, recommending encodings, and evaluating trade-offs.

$ npx skills add chartcoach/skills$ claude 'hey $chartcoach, evaluate this chart for mobile use.'

Agent workflow

1Human

Chart request

A person asks an agent to review, recommend, evaluate, or explain a chart decision.

2Agent

Guideline retrieval

The agent searches the Guideline Catalog by label, section role, source reference, and semantic match.

3Answer

Grounded response

The answer cites the guideline entries it used and names the guidance applied to the chart.

4Community

Public contribution

When guidance is missing, weak, or contested, the agent drafts a catalog issue after receiving confirmation so the community can review the proposed guideline entry.

Representation

Human-readable, agent-actionable design knowledge

chartcoach represents each visualization design guideline as a catalog entry that people can author and read while agents can query it. The same entry carries sources, roles, labels, formats, and contribution paths.

A guideline is a Markdown document with a small metadata header and natural-language sections for advice, rationale, context, checks, and fixes.

Guidelines cite papers, standards, and practitioner material, so feedback can name where its recommendation came from.

Agents can ask for the advice, rationale, context, exceptions, costs, mistakes, checks, and fixes separately.

The Guideline Catalog supports semantic search across guideline sections, so agents can retrieve the relevant passage for a chart task.

People and apps can open the same guidance through public pages, Markdown, JSON, Python, TypeScript, and the CLI.

Agent skills give agents a repeatable path from retrieval to cited answer, chart evaluation, and contribution draft.

After human confirmation, agents can draft a GitHub issue for missing or contested guidance in the catalog repository.

Readable by people

Markdown document

advice, context, checks

guideline.mdMARKDOWN

---
id: direct-labels
title: Use direct labels
labels:
  - chart:bar
  - task:compare
  - quality:readability
---
 
## Label marks directly <!-- role: advice -->
Place labels next to compared values.
 
## Why it works <!-- role: reason -->
Direct labels reduce legend lookup work.
 
## Where it applies <!-- role: context -->
Use this for a small number of bars or series.
 
## When to keep a legend <!-- role: exceptions -->
Keep a legend when labels would crowd marks.
 
## Trade-off <!-- role: costs -->
Labels use plot space and may need manual placement.
 
## Common mistake <!-- role: mistakes -->
Label only the marks readers need to compare in a dense chart.
 
## Check the chart <!-- role: check -->
Can each value be read without matching color to a legend?
 
## Fix <!-- role: fix -->
Move labels beside marks and remove the legend.

Traceable to sources

Source references

papers and practice

Use direct labels

chart:bartask:comparequality:readability

advice

Label marks directly

Place labels next to compared values.

reason

Why it works

Direct labels reduce legend lookup work.

context

Where it applies

Use this for a small number of bars or series.

exceptions

When to keep a legend

Keep a legend when labels would crowd marks.

costs

Trade-off

Labels use plot space and may need manual placement.

mistakes

Common mistake

Label only the marks readers need to compare in a dense chart.

check

Check the chart

Can each value be read without matching color to a legend?

fix

Fix

Move labels beside marks and remove the legend.

references

Lisa Charlotte Muth

What to consider when using text in data visualizations. Datawrapper Blog, 2022.

Structured for machines

Role-annotated sections

granular structure

guideline.jsonJSON

{
  "id": "direct-labels",
  "title": "Use direct labels",
  "labels": [
    "chart:bar",
    "task:compare",
    "quality:readability"
  ],
  "sections": [
    { "role": "advice", "text": "Place labels beside values." },
    { "role": "reason", "text": "Reduce legend lookup work." },
    { "role": "context", "text": "Use with small bar sets." },
    { "role": "exceptions", "text": "Keep legends when labels crowd." },
    { "role": "costs", "text": "Uses plot space." },
    { "role": "mistakes", "text": "Label only compared marks." },
    { "role": "check", "text": "Can values be read directly?" },
    { "role": "fix", "text": "Move labels beside marks." }
  ],
  "references": [
    "muth_text_in_data_visualizations_2022"
  ]
}

Portable across tools

Open formats

Markdown, JSON, APIs

main.pyPYTHON

from chartcoach import Catalog
 
catalog = Catalog.open()
entry = catalog.entry("direct-labels")
 
summary = {
    "title": entry["title"],
    "labels": entry["labels"],
    "references": entry["references"],
}

main.pyPYTHON

from chartcoach import Catalog
 
catalog = Catalog.open()
entry = catalog.entry("direct-labels")
 
summary = {
    "title": entry["title"],
    "labels": entry["labels"],
    "references": entry["references"],
}

main.tsTYPESCRIPT

import { DEFAULT_CATALOG, loadCatalog } from "@chartcoach/catalog"
 
const { entriesUrl, manifestUrl } = DEFAULT_CATALOG
const entries = await (await fetch(entriesUrl)).arrayBuffer()
const manifestText = await (await fetch(manifestUrl)).text()
const catalog = await loadCatalog({ entries, manifestText })
const entry = catalog.require("direct-labels")
 
const summary = {
  title: entry.title,
  labels: entry.labels,
  references: entry.references,
}

terminalSHELL

chartcoach catalog read direct-labels
chartcoach catalog find "legend lookup in bar chart"
chartcoach catalog cite direct-labels

Open to revision

catalog repository

GitHub issues and review

catalog repositorygithub.com/chartcoach/catalog

missing guidance

The chart issue needs a new guideline.

propose guideline entry

Draft the issue with source references, context, and proposed labels.

community review

Review the proposed guideline entry in the catalog repository.

Add guideline for missing chart guidanceopened in catalog repositoryreview

Readable by peoplePlain Markdown

A guideline is a Markdown document with a small metadata header and natural-language sections for advice, rationale, context, checks, and fixes.

Markdown document

advice, context, checks

guideline.mdMARKDOWN

---
id: direct-labels
title: Use direct labels
labels:
  - chart:bar
  - task:compare
  - quality:readability
---
 
## Label marks directly <!-- role: advice -->
Place labels next to compared values.
 
## Why it works <!-- role: reason -->
Direct labels reduce legend lookup work.
 
## Where it applies <!-- role: context -->
Use this for a small number of bars or series.
 
## When to keep a legend <!-- role: exceptions -->
Keep a legend when labels would crowd marks.
 
## Trade-off <!-- role: costs -->
Labels use plot space and may need manual placement.
 
## Common mistake <!-- role: mistakes -->
Label only the marks readers need to compare in a dense chart.
 
## Check the chart <!-- role: check -->
Can each value be read without matching color to a legend?
 
## Fix <!-- role: fix -->
Move labels beside marks and remove the legend.

Traceable to sourcesSource references

Guidelines cite papers, standards, and practitioner material, so feedback can name where its recommendation came from.

Source references

papers and practice

Use direct labels

chart:bartask:comparequality:readability

advice

Label marks directly

Place labels next to compared values.

reason

Why it works

Direct labels reduce legend lookup work.

context

Where it applies

Use this for a small number of bars or series.

exceptions

When to keep a legend

Keep a legend when labels would crowd marks.

costs

Trade-off

Labels use plot space and may need manual placement.

mistakes

Common mistake

Label only the marks readers need to compare in a dense chart.

check

Check the chart

Can each value be read without matching color to a legend?

fix

Fix

Move labels beside marks and remove the legend.

references

Lisa Charlotte Muth

What to consider when using text in data visualizations. Datawrapper Blog, 2022.

Structured for machinesSection Roles

Agents can ask for the advice, rationale, context, exceptions, costs, mistakes, checks, and fixes separately.

Role-annotated sections

granular structure

guideline.jsonJSON

{
  "id": "direct-labels",
  "title": "Use direct labels",
  "labels": [
    "chart:bar",
    "task:compare",
    "quality:readability"
  ],
  "sections": [
    { "role": "advice", "text": "Place labels beside values." },
    { "role": "reason", "text": "Reduce legend lookup work." },
    { "role": "context", "text": "Use with small bar sets." },
    { "role": "exceptions", "text": "Keep legends when labels crowd." },
    { "role": "costs", "text": "Uses plot space." },
    { "role": "mistakes", "text": "Label only compared marks." },
    { "role": "check", "text": "Can values be read directly?" },
    { "role": "fix", "text": "Move labels beside marks." }
  ],
  "references": [
    "muth_text_in_data_visualizations_2022"
  ]
}

Searchable by meaningSemantic Index

The Guideline Catalog supports semantic search across guideline sections, so agents can retrieve the relevant passage for a chart task.

Semantic index

role-aware matches

Portable across toolsOpen Formats

People and apps can open the same guidance through public pages, Markdown, JSON, Python, TypeScript, and the CLI.

Open formats

Markdown, JSON, APIs

main.pyPYTHON

from chartcoach import Catalog
 
catalog = Catalog.open()
entry = catalog.entry("direct-labels")
 
summary = {
    "title": entry["title"],
    "labels": entry["labels"],
    "references": entry["references"],
}

main.pyPYTHON

from chartcoach import Catalog
 
catalog = Catalog.open()
entry = catalog.entry("direct-labels")
 
summary = {
    "title": entry["title"],
    "labels": entry["labels"],
    "references": entry["references"],
}

main.tsTYPESCRIPT

import { DEFAULT_CATALOG, loadCatalog } from "@chartcoach/catalog"
 
const { entriesUrl, manifestUrl } = DEFAULT_CATALOG
const entries = await (await fetch(entriesUrl)).arrayBuffer()
const manifestText = await (await fetch(manifestUrl)).text()
const catalog = await loadCatalog({ entries, manifestText })
const entry = catalog.require("direct-labels")
 
const summary = {
  title: entry.title,
  labels: entry.labels,
  references: entry.references,
}

terminalSHELL

chartcoach catalog read direct-labels
chartcoach catalog find "legend lookup in bar chart"
chartcoach catalog cite direct-labels

Agent-readyAgent skills

Agent skills give agents a repeatable path from retrieval to cited answer, chart evaluation, and contribution draft.

Agent skills

retrieve, cite, apply

chartcoach/skills

skill run

evaluate chart

retrieve

guideline

cite

source

answer

advice

Open to revisionPublic Review

After human confirmation, agents can draft a GitHub issue for missing or contested guidance in the catalog repository.

catalog repository

GitHub issues and review

catalog repositorygithub.com/chartcoach/catalog

missing guidance

The chart issue needs a new guideline.

propose guideline entry

Draft the issue with source references, context, and proposed labels.

community review

Review the proposed guideline entry in the catalog repository.

Add guideline for missing chart guidanceopened in catalog repositoryreview

Research

Backed by research

chartcoach is developed by researchers from ETH Zürich, Carnegie Mellon University, the University of Vienna, and MBZUAI. It builds on work in visualization recommendation, chart linting, rule-based systems like Draco, accessibility guidance, data journalism, and situated visualization feedback.

The Guideline Catalog brings that research into a form agents can cite and people can author, review, and inspect.

Read the paper

Experimental

Actively developed

chartcoach is a research prototype for chart agents, critique tools, evaluation workflows, and visualization design systems. Browse the Guideline Catalog, request missing guidance in GitHub, or contact the research team about deployment and collaboration.

Try chartcoach Browse the Guideline Catalog Get in touch