#Chart

Chart turns numeric relationships into comparable visual structure. Use it for trends, differences, and composition—not as a substitute for exact data or as decoration for an empty surface.

npm install @a3s-lab/ui@0.4.0 chart.js

<figure aria-labelledby="visitors-title">
  <figcaption id="visitors-title">
    <strong>Monthly visits by device</strong>
    <span id="visitors-summary">Desktop and mobile visits both peak in February.</span>
  </figcaption>
  <div class="chart">
    <canvas id="visitors-chart" aria-describedby="visitors-summary">
      The chart is unavailable in this environment. Use the data table below.
    </canvas>
  </div>
  <table class="sr-only">
    <caption>Monthly visits by device</caption>
    <thead><tr><th scope="col">Month</th><th scope="col">Desktop</th><th scope="col">Mobile</th></tr></thead>
    <tbody>
      <tr><th scope="row">Jan</th><td>186</td><td>80</td></tr>
      <tr><th scope="row">Feb</th><td>305</td><td>200</td></tr>
      <tr><th scope="row">Mar</th><td>237</td><td>120</td></tr>
    </tbody>
  </table>
</figure>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";
import "@a3s-lab/ui/chart";

#Usage

Import the Chart structure and A3S visual tokens. Chart.js remains an explicit host dependency.

@import "tailwindcss";
@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/chart.css";
@import "@a3s-lab/ui/styles/a3s.css";

a3sUI.chart() accepts a native canvas and applies A3S tokens to axes, tooltips, and an optional legend. Pass Chart.js explicitly through Chart in module environments instead of relying on an implicit global.

import ChartJS from "chart.js/auto";
import "@a3s-lab/ui/runtime";
import "@a3s-lab/ui/chart";

const rows = [
  { month: "Jan", desktop: 186, mobile: 80 },
  { month: "Feb", desktop: 305, mobile: 200 },
  { month: "Mar", desktop: 237, mobile: 120 },
];

const chart = window.a3sUI.chart("#visitors-chart", {
  Chart: ChartJS,
  type: "bar",
  labelKey: "month",
  data: rows,
  series: {
    desktop: { label: "Desktop", color: "var(--chart-1)" },
    mobile: { label: "Mobile", color: "var(--chart-2)" },
  },
  legend: true,
});

Place the canvas, a visible title, a concise conclusion, and equivalent data in one figure. The graphic must never be the only representation of the values.

<figure aria-labelledby="visitors-title">
  <figcaption id="visitors-title">
    <strong>Monthly visits by device</strong>
    <span id="visitors-summary">Desktop and mobile visits both peak in February.</span>
  </figcaption>
  <div class="chart">
    <canvas id="visitors-chart" aria-describedby="visitors-summary">
      The chart is unavailable in this environment. Use the data table below.
    </canvas>
  </div>
  <table class="sr-only">
    <caption>Monthly visits by device</caption>
    <thead><tr><th scope="col">Month</th><th scope="col">Desktop</th><th scope="col">Mobile</th></tr></thead>
    <tbody>
      <tr><th scope="row">Jan</th><td>186</td><td>80</td></tr>
      <tr><th scope="row">Feb</th><td>305</td><td>200</td></tr>
      <tr><th scope="row">Mar</th><td>237</td><td>120</td></tr>
    </tbody>
  </table>
</figure>

The helper reuses an existing .chart container or creates one around a bare canvas. When the theme or style pack changes, it resolves the current CSS color tokens again.

#Parameters

Each series.label must be localized user-facing copy. Use stable --chart-1 through --chart-5 tokens for color. surface accepts true, "gradient", or { from, to }; place only native Chart.js dataset options in dataset.

#States and variants

#Choose the right graphic

• Bar charts compare discrete categories and normally start from a zero baseline.
• Line charts communicate an ordered trend. Avoid smoothing that implies unsampled values.
• Stacked charts work only when users need both total and composition; use a table when categories become dense.
• Doughnut charts suit a small number of categories that form a clear whole and must show the values alongside the graphic.
• Radar charts are difficult to compare precisely. Reserve them for a small overview of dimensions on the same scale, never for a critical decision.

<div class="grid gap-8">
  <div><h3 class="mb-3 text-sm font-semibold">Continuous trend</h3><ChartDemo variant="line" /></div>
  <div><h3 class="mb-3 text-sm font-semibold">Whole composition</h3><ChartDemo variant="donut" /></div>
</div>

#Loading, empty, and error

Keep the chart measurement box while data is unavailable, and explain the current condition inside data-chart-state. Empty state says why no values exist; error state includes a recovery path. Do not disguise missing data as a zero-value chart.

<div class="grid w-full gap-4 lg:grid-cols-3">
  <div class="chart" data-state="loading" aria-busy="true">
    <canvas aria-hidden="true"></canvas>
    <div data-chart-state role="status">
      <strong>Loading visit data</strong>
      <span>Chart dimensions remain stable while the data resolves.</span>
    </div>
  </div>
  <div class="chart" data-state="empty">
    <canvas aria-hidden="true"></canvas>
    <div data-chart-state>
      <strong>No comparable data</strong>
      <span>Select at least two points in time or expand the date range.</span>
    </div>
  </div>
  <div class="chart" data-state="error">
    <canvas aria-hidden="true"></canvas>
    <div data-chart-state role="alert">
      <strong>Visit data failed to load</strong>
      <span>Check the data connection and retry. Current filters will remain.</span>
      <footer><button type="button" class="btn" data-size="sm" data-variant="outline">Reload</button></footer>
    </div>
  </div>
</div>

The host drives loading, empty, and error from its data lifecycle. Prefer the Chart.js update API when values change so focus, size, and animation context remain stable. An interactive legend is a filter control and needs real buttons with synchronized aria-pressed; the generated default legend only identifies series.

#Accessibility

Charts need a visible title, a concise conclusion, and an equivalent data table. A canvas aria-label may summarize the main finding but cannot replace exact values. Distinguish series with labels, shape, or position as well as color. Tooltip values must also be available in the table. Keep the default read-only legend out of the tab order; interactive legends must use buttons. Preserve label and data comprehension at 200% zoom, in dark mode, in RTL, and on narrow screens. Respect reduced-motion preferences and avoid noisy live announcements for streaming data. The host owns data truth, formatting, units, time zones, and remote states; the component owns visual mapping and theme integration.