Experimental

Visualization guidelines agents can inspect and cite

chartcoach helps agents retrieve, inspect, cite, apply, and improve visualization guidelines. Each guideline links to its 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, 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.

Research

Backed by research

chartcoach is developed by researchers from ETH Zürich, Carnegie Mellon University, the University of Vienna, and MBZUAI.

The catalog draws on research and practical guidance for chart design, accessibility, and data journalism. It builds on work such as Draco, which recommends and checks chart designs, and studies of how people create and interpret charts.

Each guideline links to its sources so people can review the evidence and agents can cite it.

Read the paper

Representation

Human-readable, agent-actionable visualization guidelines

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.

Plain Markdown

Readable by people

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

Markdown documentadvice, 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.

References

Traceable to sources

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

Referencespapers 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.

Section Roles

Structured for machines

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

Role-annotated sectionsgranular structure

sectionsJSON

[
  {
    "role": "advice",
    "title": "Advice",
    "content": "Label marks."
  },
  {
    "role": "reason",
    "title": "Reason",
    "content": "Less lookup."
  },
  {
    "role": "context",
    "title": "Context",
    "content": "Few series."
  },
  {
    "role": "exceptions",
    "title": "Exceptions",
    "content": "Crowded marks."
  },
  {
    "role": "costs",
    "title": "Costs",
    "content": "Uses space."
  },
  {
    "role": "mistakes",
    "title": "Mistakes",
    "content": "Avoid clutter."
  },
  {
    "role": "check",
    "title": "Check",
    "content": "Clear values?"
  },
  {
    "role": "fix",
    "title": "Fix",
    "content": "Move labels."
  }
]

Semantic Index

Searchable by meaning

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

Semantic indexrole-aware matches

Open Formats

Portable across tools

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

Open formatsMarkdown, JSON, APIs

main.pyPYTHON

from chartcoach import open_catalog
 
catalog = open_catalog()
release = catalog.release
entry = catalog.read(ids=["direct-labels"], source_detail="full")[0]
 
summary = {
    "title": entry["title"],
    "labels": entry["labels"],
    "references": entry["references"],
}

main.tsTYPESCRIPT

import { openCatalog } from "@chartcoach/catalog"
 
const catalog = await openCatalog()
const entry = catalog.require("direct-labels")
 
const summary = {
  title: entry.title,
  labels: entry.labels,
  references: entry.references,
}

Agent skills

Agent-ready

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

Agent skillsretrieve, cite, apply

chartcoach/skills

skill run

evaluate chart

retrieve

guideline

cite

source

answer

advice

Public Review

Open to revision

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

catalog repositoryGitHub issues and review

catalog repositorygithub.com/chartcoach/catalog

missing guidance

The chart issue needs a new guideline.

propose guideline entry

Draft the issue with 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

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