“Line chart, five points” identifies a picture but leaves its finding unanswered. For the sales series below, a reader needs to know that April is highest at 9,100 and May falls to 2,100. describeChart() turns the supplied configuration into a description that includes measurements and a simple account of the pattern.
Why this matters
Alan Lundgard and Arvind Satyanarayan'sfour-level model of semantic contentdistinguishes a chart's construction, statistical relationships, patterns, and domain context. Their study of blind and sighted readers found that useful content depends on the reader, with trends and statistics particularly valuable for blind participants. A chart-type label alone is a thin starting point.
Read three layers of one series
This synthetic series rises from January through April, then drops in May. The panel runsdescribeChart() on those five rows. Read Encoding to learn what is measured, Statistics to find the range and its months, and Trend for the generated account of the direction.
L1EncodingA line chart of sales by month.
L2Statisticssales ranges from 2,100 (May) to 9,100 (Apr), with a mean of 5,460 across 5 points.
L3TrendOverall sales climbs to a peak of 9,100 (Apr), then falls to 2,100 (May).
Notice that the largest value has a month attached. “9,100 in April” gives a reader a place to investigate. The generated text can describe the fall to May, but these rows do not say whether a warehouse closed, demand fell, or a feed failed. That explanation needs evidence outside this chart.
How it works
The helper reads the component, data, and accessors. It describes the encoding, computes supported statistics, and uses rules to summarize patterns such as net direction and reversals. It makes no model or network call. Coverage varies by chart family: a numerical series supports richer statistics than a topology-only network.
When to reach for it
Use the output as a first draft, a fallback, or a caption that stays aligned with new data. Review the units, missing values, grouping, and scope. Write a summary for the supported conclusion and provide an exact-value table when readers need one. An automatically generated trend cannot establish a cause, and a passing accessibility check cannot replace trying the reading experience.
Wiring it up
import { describeChart } from "semiotic/utils" const description = describeChart("LineChart", props) // Inspect description.levels before using the text in a report. <ChartContainer title="Sales by month" chartConfig={{ component: "LineChart", props }} describe > <LineChart {...props} /> </ChartContainer>ChartContainer can present the generated description when describeis enabled. This is separate from the chart's authored title, description, and summary. Compose those layers so the reader encounters a useful explanation without hearing the same sentence repeatedly.
Other places this helps
A dashboard needs captions that follow changing data. An email report needs the main pattern even when its image is unavailable. An assistant needs real statistics before drafting an explanation. In all three cases, computed observations are useful input; the author remains responsible for what the report concludes.