Skip to main content
Technology & EngineeringData Visualization49 lines

Build Accessible Declarative Charts with Vega-Lite

Create versioned Vega-Lite specifications with explicit aggregation, meaningful chart descriptions, and interaction tests that include keyboard and non-hover access.

Quick Summary10 lines
State the comparison the reader needs and the grain of the source rows. For weekly incident counts, define whether a row is an incident or an aggregate, how dates are bucketed, and whether timezone and week start can change the result. Test a small fixture with known totals before writing the visualization. Make any explicit aggregation consistent with the row grain. Counting aggregate rows can silently produce a plausible but incorrect chart.

## Key Points

- [Vega-Lite overview](https://vega.github.io/vega-lite/docs/)
- [Vega-Lite selection parameters](https://vega.github.io/vega-lite/docs/selection.html)
- [Vega-Lite mark properties](https://vega.github.io/vega-lite/docs/mark.html)
- [Vega-Lite v5 JSON schema](https://vega.github.io/schema/vega-lite/v5.json)
skilldb get data-visualization-skills/vega-lite-declarative-chartsFull skill: 49 lines
Paste into your CLAUDE.md or agent config

Build Accessible Declarative Charts with Vega-Lite

Translate the question into data and encodings

State the comparison the reader needs and the grain of the source rows. For weekly incident counts, define whether a row is an incident or an aggregate, how dates are bucketed, and whether timezone and week start can change the result. Test a small fixture with known totals before writing the visualization. Make any explicit aggregation consistent with the row grain. Counting aggregate rows can silently produce a plausible but incorrect chart.

Use the schema version supported by the Vega-Lite runtime bundled in the application. Declare channel field types deliberately. Treat categorical labels as nominal, orderable groups as ordinal where appropriate, dates as temporal, and numeric quantities as quantitative. Document sorting, units, and axis or scale choices. Show a meaningful zero or comparison baseline when the mark relies on lengths. Distinguish zero, missing data, and categories absent from the fixture.

Write a meaningful chart description and label the marks and controls where the version and renderer support it. Use shape, labels, or line style alongside color for essential comparisons. Provide an accessible data alternative with the same important values and units. Hover alone is insufficient for retrieving an essential value. Review visual contrast, label readability, and the chart’s behavior in a narrow layout.

Test interaction and aggregation together

This fixture counts incident rows by service. The numeric axis should show 2 for Checkout and 1 for Search. An application can add a date field and a documented time unit once the source timestamps and reporting timezone are agreed.

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "description": "Incident counts by service for the example period",
  "data": {
    "values": [
      {"service": "Checkout"}, {"service": "Search"}, {"service": "Checkout"}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "service", "type": "nominal"},
    "y": {"aggregate": "count", "type": "quantitative", "title": "Incidents"}
  }
}

Use a named selection parameter for a clear task such as isolating a service or brushing a date range. Choose whether the selection filters rows or only changes visual emphasis. If the selected values also affect aggregate totals in a second view, explicitly test where the filter and aggregation apply. Describe the empty selection behavior and test it at initial load and after clearing the selection. Configure the documented parameter or predicate behavior for the pinned version.

Render the specification in the same embed and renderer used by the product. A schema validator catches misspelled fields and incompatible properties, while a renderer check establishes behavior with the project's dependency versions. Exercise tooltip units, initial state, selection, clear or reset, and keyboard navigation to any exposed controls or data fallback. Use fixtures for empty, incomplete, and repeated rows. Compare every displayed total to a small independent calculation.

Retain the versioned spec, fixture, reconciliation, and render result. When publishing a static export, state which interactions the export omits and provide a suitable alternative for the information those interactions reveal.

References

Install this skill directly: skilldb add data-visualization-skills

Get CLI access →