@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/chart-area.md

@@ -0,0 +1,87 @@
+# Stacked area chart
+
+Two or more series stacked over time, so the top edge is the total and each band is one part of it, such as applications per week split by source.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- When the total over time matters and so does how it splits, such as weekly applications by source (LinkedIn, Indeed, Careers page, Referral).
+- When the parts always add up to a meaningful whole, such as candidates in the pipeline by stage at the end of each week.
+
+## When not to use
+
+- For one series. Use the Line chart card; a single filled area only adds ink.
+- For values that can go negative, such as net change in open roles. Use the Line chart card or Bar chart.
+- For series that do not add up to a whole, such as applications for two unrelated listings. Overlapping areas hide each other; use lines.
+- When people need to compare the middle bands exactly. Only the bottom band sits on a flat baseline; use the Line chart card or a Breakdown table.
+
+## Structure
+
+1. Title (what is measured) and subtitle (period)
+2. Controls row: time range, Chart or Table
+3. Plot: stacked bands from a zero baseline, a thin surface-colour line between bands, one y-axis
+4. Legend: one item per band, in stack order, each a toggle
+5. Crosshair tooltip: every band's value and the total at the hovered date
+6. Optional threshold: dashed line with a text label
+7. Footer: source and updated time
+
+## Guidelines
+
+- Always stack, always from zero. The top edge must read as the true total.
+- Use two to five bands. Fold the smallest sources into "Other" at the top of the stack rather than adding a sixth colour.
+- Put the largest or steadiest band at the bottom so the most important part has a flat baseline, and keep the stack order the same on every chart.
+- Use categorical colours in fixed order from colour 1, separated by a thin line in the surface colour so neighbouring bands stay distinct.
+- The tooltip lists bands in the same order as the stack, top to bottom, then the total.
+- Show missing weeks as a gap, never as a drop to zero.
+- Hiding a band from the legend restacks the rest and updates the total in the tooltip. Colours do not move.
+
+## Content
+
+- Title names the total and the split: "Applications by source". Subtitle gives the period: "Last 12 weeks".
+- Legend items use the names people use in the product: "Careers page", not "careers_site". Never truncate a name if the end is what tells two apart.
+- Skip x-axis labels at a regular interval (every other week) instead of crowding them, and abbreviate months: "3 Nov".
+
+## Accessibility
+
+- The chart has an accessible name matching its title and a description such as "Stacked area chart showing applications by source, last 12 weeks."
+- The Table view lists every band per week plus the total, and is the long description.
+- Bands are named in the tooltip and legend, so colour is never the only way to tell them apart.
+- Legend items are toggle buttons with a pressed state; hiding one is announced politely: "Referral hidden".
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the plot, then each legend item |
+| ← → | Move the crosshair to the previous or next week |
+| Enter | Pin the tooltip so its links can be reached with Tab |
+| Esc | Close the tooltip and return focus to the plot |
+| Space (legend item) | Show or hide that band |
+
+## Examples
+
+### pipeline
+
+```tsx
+import { CartesianChart, ChartFrame, ChartLegend, chartTable, seriesColor } from "@twoux/ui";
+import { APPLICATIONS, WEEKS } from "../chart-card-line/data";
+
+export const meta = { title: "Applications, stacked by team", description: "Stacked from zero, so the top edge is the total and each band is one team. Use it when the total matters as much as the parts; for comparing teams, use lines.", order: 1 };
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Applications per week" description="Stacked by team" table={chartTable("Week", WEEKS, APPLICATIONS)} legend={<ChartLegend items={APPLICATIONS.map((s, i) => ({ id: s.id, label: s.label, color: seriesColor(i) }))} />}>
+			<CartesianChart kind="area" stacked x={WEEKS} series={APPLICATIONS} aria-label="Applications per week, stacked by team" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Line chart card
+- Bar chart
+- Data visualisation colours
+- Breakdown table
+- Data visualisation

package/agent/docs-md/chart-bar.md

@@ -0,0 +1,100 @@
+# Bar chart
+
+Vertical bars from a zero baseline for comparing amounts per period or category, with the latest bar labelled and an incomplete period shown lighter.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Comparing amounts across items or periods; simple bars are quickly processed and understood.
+- Emphasising the total of each data point.
+
+## When not to use
+
+- Showing a trend over time where shape matters more than totals. Use the TwoUX Line chart card.
+- Two dimensions at once. Use the TwoUX Heatmap.
+- Breaking down task outcomes as stacks; stacked bars are hard to read. Use separate simple bars.
+
+## Structure
+
+1. Title and subtitle
+2. Zero baseline
+3. Bars (4px rounded top, gap between)
+4. Latest-bar label
+5. Incomplete period bar (lighter, labelled)
+6. Hover tooltip
+
+## Guidelines
+
+- Bars always start at zero.
+- Use horizontal bars when category names are long.
+- Label only the latest bar; hover shows the rest.
+- The current, incomplete period is lighter and says so in a label.
+- A single series uses colour 1 and no legend.
+- Bar charts have the same four states as line charts: skeleton plot while loading, empty, no match with Clear filters, and error with Try again.
+- Use horizontal bars when there are many categories or long names, such as applications by listing title; vertical bars for periods.
+- With several series, group bars to compare the parts. Stack only when the total is the main reading and there are four parts or fewer, with a 2px surface-colour gap between segments.
+- A single series uses one colour for every bar. Never colour bars by month or by category for variety.
+- A goal or limit is a dashed threshold line with a text label, such as "Target 120".
+- The pinned popover can break a bar down into up to seven parts, with a link on the name or the value, not both.
+
+## Content
+
+- Title names the measure; subtitle gives the period and scope.
+- Keep tick increments fixed and match time labels to the data's period.
+- Label the incomplete period plainly, "This week so far".
+
+## Accessibility
+
+- 1.1.1 and WAI complex images: provide a short alternative and a table with the values.
+- 1.4.11 Non-text Contrast: bars reach 3:1 against the background.
+- 1.4.1 Use of Color: the incomplete period is marked in text, not lightness alone.
+- 2.1.1 Keyboard: arrow keys move between bars and show each value.
+- Description: "Bar chart showing applications per week, last 12 weeks." It matches the visible title and period.
+- Grouped and stacked bars name each part in the tooltip and table, so colour is not the only cue.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the chart |
+| ← → | Move to the previous or next bar |
+
+## Examples
+
+### hires
+
+```tsx
+import { CartesianChart, ChartFrame, ChartLegend, SegmentedControl, Segment, chartTable, seriesColor } from "@twoux/ui";
+import { useState } from "react";
+import { HIRES, WEEKS } from "../chart-card-line/data";
+
+export const meta = { title: "Hires per week", description: "Grouped bars compare teams week by week; stacked shows the total. Bars start at zero with 4px rounded ends and 2px gaps.", order: 1 };
+
+export default function Example() {
+	const [mode, setMode] = useState("grouped");
+	return (
+		<ChartFrame
+			className="w-full"
+			title="Hires per week"
+			description="Offers accepted, by team"
+			table={chartTable("Week", WEEKS, HIRES)}
+			actions={
+				<SegmentedControl value={mode} onValueChange={setMode} size="sm" aria-label="Bar layout">
+					<Segment value="grouped">Grouped</Segment>
+					<Segment value="stacked">Stacked</Segment>
+				</SegmentedControl>
+			}
+			legend={<ChartLegend items={HIRES.map((s, i) => ({ id: s.id, label: s.label, color: seriesColor(i) }))} />}
+		>
+			<CartesianChart kind="bar" stacked={mode === "stacked"} x={WEEKS} series={HIRES} aria-label="Hires per week by team" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Line chart card
+- Breakdown table
+- Data visualisation colours

package/agent/docs-md/chart-box-plot.md

@@ -0,0 +1,88 @@
+# Box plot
+
+Distributions of several groups on one axis: a box for the middle half, a line for the median, whiskers to 1.5 times the IQR and dots for outliers.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Comparing how spread out several groups are, such as response times by team.
+- Finding outliers worth opening, such as the slowest tickets.
+
+## When not to use
+
+- For one group's shape. Use the TwoUX Histogram.
+- For audiences new to statistics; show median and range in a table or a range plot instead.
+
+## Structure
+
+1. Title and subtitle
+2. Group labels
+3. Shared value axis with title and unit
+4. Box from Q1 to Q3
+5. Median line
+6. Whiskers with caps
+7. Outlier dots
+8. Legend explaining the parts
+9. Tooltip: median, middle half, whiskers, outliers
+
+## Guidelines
+
+- Put every group on one shared axis.
+- Whiskers reach the furthest value within 1.5 times the IQR; values beyond are outlier dots.
+- Always show the legend explaining box, median, whiskers and outliers.
+- Order groups by meaning or by median, not alphabetically by default.
+- Use ChartFrame for the four states: loading keeps the frame, an error says what failed with Try again, an empty period says so, and no match offers Clear filters.
+
+## Content
+
+- Say Middle half (Q1 to Q3) rather than only IQR.
+- Axis title gives the measure and unit, such as Hours to first response.
+
+## Accessibility
+
+- 1.1.1 and WAI complex images: the chart has a short generated summary as its accessible name and a Table view with every value.
+- 2.1.1 Keyboard: the chart is one tab stop; arrow keys move between marks and show the same tooltip as hover.
+- 1.4.13 Content on Hover or Focus: the tooltip never covers the mark it describes, stays while the pointer is over the chart and closes with Esc.
+- Accessible description: "Box plot showing first response time by team, last 40 tickets."
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the chart |
+| ← → ↑ ↓ | Move to the previous or next mark and show its values |
+| Home End | Jump to the first or last mark |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### response-times
+
+```tsx
+import { BoxPlot, boxTable, ChartFrame } from "@twoux/ui";
+
+export const meta = { title: "First response time by team", description: "Four teams on one axis: the box is the middle half of tickets, the line the median, dots the slow outliers worth opening.", order: 1 };
+
+const TEAMS = [
+	{ id: "billing", label: "Billing", values: [4.7, 1.3, 2.9, 3.3, 4.0, 4.2, 3.4, 2.1, 3.4, 5.1, 2.6, 1.9, 2.4, 5.4, 2.1, 3.7, 2.2, 0.9, 2.4, 3.3, 1.7, 10.8, 3.2, 2.4, 2.7, 5.0, 2.8, 1.3, 4.3, 5.4, 1.6, 2.1, 6.8, 2.9, 2.9, 2.7, 3.0, 1.8, 1.6, 7.0] },
+	{ id: "onboarding", label: "Onboarding", values: [9.5, 3.2, 3.3, 11.4, 7.0, 2.4, 4.1, 9.9, 3.3, 18.5, 2.0, 15.3, 5.2, 11.0, 9.5, 6.5, 9.4, 6.5, 8.4, 7.9, 4.3, 2.1, 5.7, 4.8, 4.1, 4.7, 6.5, 2.3, 3.5, 4.4, 5.6, 5.3, 31.2, 8.4, 11.4, 4.3, 6.2, 5.9, 2.1, 5.7] },
+	{ id: "integrations", label: "Integrations", values: [27.7, 7.3, 6.3, 18.5, 10.2, 22.2, 8.0, 22.1, 6.1, 3.5, 8.3, 12.8, 6.9, 10.9, 12.7, 11.7, 12.8, 9.4, 6.0, 8.5, 15.8, 5.0, 5.4, 20.1, 7.7, 15.4, 7.4, 7.5, 13.6, 2.9, 12.4, 3.6, 8.6, 9.0, 4.1, 2.2, 20.4, 11.0, 13.6, 11.3] },
+	{ id: "enterprise", label: "Enterprise", values: [0.9, 1.8, 2.3, 1.1, 2.6, 3.0, 1.8, 2.4, 3.9, 0.8, 2.1, 2.3, 1.2, 0.8, 2.0, 1.3, 2.6, 3.6, 2.2, 4.0, 0.9, 1.5, 2.8, 2.4, 1.4, 2.4, 1.8, 4.9, 3.3, 4.0, 2.5, 2.9, 4.1, 1.5, 2.4, 1.9, 1.4, 1.6, 3.1, 1.5] },
+];
+const hours = (n: number) => `${Math.round(n * 10) / 10}h`;
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="First response time by team" description="Last 40 tickets per team" table={boxTable(TEAMS, hours, "Team")}>
+			<BoxPlot groups={TEAMS} format={hours} xTitle="Hours to first response" aria-label="First response time by team, last 40 tickets" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Histogram
+- Scatter chart
+- Breakdown table

package/agent/docs-md/chart-bullet.md

@@ -0,0 +1,89 @@
+# Bullet chart
+
+Actual against target for a few measures: a thin bar over grey qualitative bands with the target as a dark tick, in a fraction of a gauge's space.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing progress against a target for several measures in one card, such as bookings this quarter.
+- Where a gauge or dial was asked for: a bullet chart says the same in a line.
+
+## When not to use
+
+- For a single number with no target. Use the TwoUX Stat compare.
+- For usage against a hard limit. Use the TwoUX Usage meter.
+
+## Structure
+
+1. Title and subtitle
+2. Row: measure name, actual and target as text
+3. Qualitative bands in neutral grey steps, darkest for the worst
+4. Actual: thin bar in c1
+5. Target: dark tick
+6. Scale under each bar
+7. Legend: actual, target, bands
+
+## Guidelines
+
+- Use a bullet chart, never a gauge or dial.
+- Bands are neutral grey steps, darkest for the worst range; they never use status colours.
+- The actual is a thin bar in the first series colour, the target a dark tick across it.
+- Print actual and target as text on each row, so the bar is never the only way to read them.
+- Each row has its own scale; never compare bar lengths between rows with different scales.
+- Use ChartFrame for the four states: loading keeps the frame, an error says what failed with Try again, an empty period says so, and no match offers Clear filters.
+
+## Content
+
+- Name the bands by meaning (Poor, Satisfactory, Good), worst first.
+- Write actual of target, such as £412k of £450k.
+
+## Accessibility
+
+- 1.4.1 Use of Color: values are printed; bands are named in the legend and in each row's name.
+- 1.1.1 and WAI complex images: each row's accessible name gives the actual, target, percentage of target and band.
+- 2.1.1 Keyboard: each row is focusable and shows the same tooltip as hover.
+- 1.4.11 Non-text Contrast: the actual bar and target tick meet 3:1 against every band.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to the next measure |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### quarter-targets
+
+```tsx
+import { BulletChart, ChartFrame } from "@twoux/ui";
+
+export const meta = { title: "Quarter to date against target", description: "Each measure is a thin bar over grey bands, with the target as a dark tick. It replaces a row of gauges in a third of the space.", order: 1 };
+
+const ROWS = [
+	{ id: "new", label: "New business", value: 412_000, target: 450_000, bands: [300_000, 400_000, 500_000] },
+	{ id: "expansion", label: "Expansion", value: 188_000, target: 160_000, bands: [100_000, 150_000, 220_000] },
+	{ id: "renewals", label: "Renewals", value: 731_000, target: 820_000, bands: [700_000, 800_000, 900_000] },
+];
+const gbp = (n: number) => (n === 0 ? "£0" : `£${Math.round(n / 1000)}k`);
+
+export default function Example() {
+	return (
+		<ChartFrame
+			className="w-full"
+			title="Bookings against target"
+			description="Quarter to date, Q4 2026"
+			table={{ columns: ["Measure", "Actual", "Target", "Of target"], rows: ROWS.map((r) => [r.label, gbp(r.value), gbp(r.target), `${Math.round((r.value / r.target) * 100)}%`]) }}
+		>
+			<BulletChart rows={ROWS} format={gbp} aria-label="Bookings against target, quarter to date" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Stat card with comparison
+- Waterfall chart
+- Bar chart

package/agent/docs-md/chart-candlestick.md

@@ -0,0 +1,112 @@
+# Candlestick chart
+
+Open, high, low and close per period for a price. Up candles are hollow and down candles filled, in two categorical colours, or green and red on trading screens; volume is its own chart below.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing how a traded price moved each day, including its range, for people who read markets.
+- Spotting days with wide ranges or large volume.
+
+## When not to use
+
+- For a general audience or one price over time. Use the TwoUX Price chart or Line chart card.
+- For anything that is not open, high, low and close.
+
+## Structure
+
+1. Title and subtitle
+2. Price axis on the right, not from zero, with a note
+3. Candles: wick for high and low, body for open and close
+4. Optional last-price tag on the axis, with a dashed line
+5. Up: hollow c1; down: filled c2 (green and red with colors="market")
+6. Volume chart below with its own axis, sharing the crosshair
+7. Legend: up and down
+8. Tooltip: change, open, high, low, close, volume
+
+## Guidelines
+
+- Up and down take two categorical colours and differ in fill too: up hollow, down filled.
+- Use two categorical colours by default. On trading screens, where people expect it, use green for up and red for down (colors="market"); the hollow and filled bodies stay, so colour is never the only cue.
+- Put volume in its own chart below with its own axis; never a second y axis.
+- The price axis need not start at zero, and says so.
+- One crosshair for both charts, so a day's price and volume read together.
+- Use ChartFrame for the four states: loading keeps the frame, an error says what failed with Try again, an empty period says so, and no match offers Clear filters.
+- On a live market, tag the last price on the axis (showLast) and move only the forming candle as prices arrive.
+
+## Content
+
+- Dates as day and short month (5 Nov); the unit in the subtitle.
+- Legend says what up means: Up (close above open).
+
+## Accessibility
+
+- 1.4.1 Use of Color: direction is carried by hollow or filled bodies, the tooltip and the table.
+- 1.1.1 and WAI complex images: the chart has a short generated summary as its accessible name and a Table view with every value.
+- 2.1.1 Keyboard: the chart is one tab stop; arrow keys move between marks and show the same tooltip as hover.
+- 1.4.13 Content on Hover or Focus: the tooltip never covers the mark it describes, stays while the pointer is over the chart and closes with Esc.
+- Accessible description: "Candlestick chart showing Ashdown plc daily prices, last 30 trading days."
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the chart |
+| ← → ↑ ↓ | Move to the previous or next mark and show its values |
+| Home End | Jump to the first or last mark |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### daily
+
+```tsx
+import { type Candle, CandlestickChart, candleTable, ChartFrame } from "@twoux/ui";
+
+export const meta = { title: "Daily prices with volume", description: "Ninety trading days. Up days are hollow, down days filled, and volume sits in its own panel under the prices with the same crosshair.", order: 1 };
+
+// 90 trading days from a seeded random walk, so the example looks like a real price series and stays the same on every load.
+function tradingDays(count: number, endDate: Date) {
+	const days: Date[] = [];
+	const d = new Date(endDate);
+	while (days.length < count) {
+		if (d.getDay() !== 0 && d.getDay() !== 6) days.unshift(new Date(d));
+		d.setDate(d.getDate() - 1);
+	}
+	return days;
+}
+function makeCandles(): Candle[] {
+	let seed = 7;
+	const rand = () => ((seed = (seed * 16807) % 2147483647) / 2147483647);
+	let close = 742;
+	return tradingDays(90, new Date(2026, 10, 5)).map((day) => {
+		const open = close + (rand() - 0.5) * 4;
+		const pull = (742 - open) * 0.06; // drifts back towards a middle price, like a stock trading in a range
+		close = open + pull + (rand() - 0.5) * 22 + (rand() > 0.93 ? (rand() - 0.5) * 34 : 0);
+		const high = Math.max(open, close) + rand() * 9;
+		const low = Math.min(open, close) - rand() * 9;
+		const big = Math.abs(close - open) > 12;
+		const v = Math.round((1.4 + rand() * 1.4 + (big ? 1.2 : 0)) * 1_000_000);
+		const r = (n: number) => Math.round(n * 10) / 10;
+		return { t: day.toLocaleDateString("en-GB", { day: "numeric", month: "short" }), o: r(open), h: r(high), l: r(low), c: r(close), v };
+	});
+}
+const DAYS: Candle[] = makeCandles();
+const pence = (n: number) => `${n.toLocaleString("en-GB", { minimumFractionDigits: 1, maximumFractionDigits: 1 })}p`;
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Ashdown plc, daily" description="Last 90 trading days, in pence" table={candleTable(DAYS, pence)} height={320}>
+			<CandlestickChart candles={DAYS} format={pence} aria-label="Ashdown plc daily prices, last 90 trading days" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Price chart
+- Line chart card
+- Bar chart
+- Order book

package/agent/docs-md/chart-card-line.md

@@ -0,0 +1,120 @@
+# Line chart card
+
+A card that shows how one or more series change over time, with a title, period controls, a Chart or Table switch, direct labels, a shared crosshair tooltip and a source footer.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing how a value changes over time.
+- Comparing trends across a few series, such as applies per day by team.
+
+## When not to use
+
+- Comparing amounts between categories. Use the TwoUX Bar chart.
+- Two measures with different units. Use two charts side by side, never two y-axes.
+- One number that matters. Use the TwoUX Stat card with comparison.
+- More than 8 series. Fold extras into "Other" or filter.
+
+## Structure
+
+1. Title (what is measured)
+2. Subtitle (period)
+3. Controls row: time range (7d, 30d, 90d), Chart or Table
+4. Plot: 2px lines, faint grid, one y-axis
+5. Direct labels at line ends
+6. Legend (2 or more series)
+7. Crosshair tooltip
+8. Footer: source, updated time, Export CSV, Add to dashboard
+
+## Guidelines
+
+- Title says what is measured; the subtitle gives the period.
+- Label line ends directly, and add a legend only for two or more series.
+- One tooltip lists every series at the hovered day, sorted by value, with both axis values.
+- Keep the grid faint and lines 2px; remove anything that does not carry data.
+- A line chart may start above zero, unlike a bar chart.
+- Every chart can switch to a table, which is also its accessible version.
+- Every line chart has four states in the plot area, never blank: Loading: skeleton of the plot (axes and faint grid) with "Loading applications" as the region label. Empty: "No applications in this period" with one next step. No match: "No data matches these filters" with Clear filters. Error: "Couldn't load applications. Your filters are kept." with Try again.
+- Missing days show as a break in the line, not a drop to zero.
+- Legend items are toggles that show or hide a series; hidden series keep their colour slot. With three or more series, add a Series filter (all selected by default); with one, no filter and no legend.
+- Selecting a point or pressing Enter pins the tooltip as a popover. A pinned popover can hold a breakdown of up to seven items and up to two footer buttons; see Chart drill-down.
+- A target or limit is a threshold: a dashed line at a fixed value with a text label ("Target 40 a day"), not an extra series.
+- Skip x-axis date labels at a regular interval rather than crowding or rotating them. The y-axis never shows time units.
+- A forecast after today continues in the same colour but dashed, with a vertical "Today" marker, so the split is not shown by colour alone. Keep grey dashed for the previous period only.
+
+## Content
+
+- Use nouns in titles and keep axis titles to one to three words with units.
+- Labels, values and legends use text colours; the series colour sits beside them as a swatch.
+- The footer names the data source and when it updated.
+
+## Accessibility
+
+- 1.1.1 and WAI complex images: a short alternative names the chart type, data and period; the table view is the long description.
+- 1.4.1 Use of Color: direct labels identify series, so colour is not the only cue.
+- 1.4.11 Non-text Contrast: lines needed to read the data reach 3:1 against the background.
+- 2.1.1 Keyboard: the plot is focusable and arrow keys move the crosshair day by day.
+- The accessible name matches the visible title; the description reads "Line chart showing applications per day by team, last 30 days."
+- Legend toggles are buttons with aria-pressed, and hiding a series is announced politely.
+- Enter pins the tooltip, Tab moves into its content, Esc closes it and returns focus to the same day.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the plot |
+| ← → | Move the crosshair to the previous or next day |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### applications
+
+```tsx
+import { CartesianChart, ChartFrame, ChartLegend, type ChartStatus, SegmentedControl, Segment, chartTable, seriesColor } from "@twoux/ui";
+import { useState } from "react";
+import { APPLICATIONS, WEEKS } from "./data";
+
+export const meta = { title: "Applications by team", description: "Hover, or focus the chart and use the arrow keys, to read every value. Click a legend key to hide a series. The table button shows the same numbers as a table.", order: 1 };
+
+export default function Example() {
+	const [hidden, setHidden] = useState<string[]>([]);
+	const [state, setState] = useState<ChartStatus>("ready");
+	const [period, setPeriod] = useState("8w");
+	const n = period === "4w" ? 4 : 8;
+	const x = WEEKS.slice(-n);
+	const series = APPLICATIONS.map((s) => ({ ...s, data: s.data.slice(-n) }));
+	return (
+		<div className="grid w-full gap-3">
+			<ChartFrame
+				title="Applications per week"
+				description={`All open listings, last ${n} weeks`}
+				status={state}
+				onRetry={() => setState("ready")}
+				table={chartTable("Week", x, series)}
+				actions={
+					<SegmentedControl value={period} onValueChange={setPeriod} size="sm" aria-label="Period">
+						<Segment value="4w">4 weeks</Segment>
+						<Segment value="8w">8 weeks</Segment>
+					</SegmentedControl>
+				}
+				legend={<ChartLegend items={APPLICATIONS.map((s, i) => ({ id: s.id, label: s.label, color: seriesColor(i), shape: "line" }))} hidden={hidden} onToggle={(id) => setHidden((h) => (h.includes(id) ? h.filter((x) => x !== id) : [...h, id]))} />}
+			>
+				<CartesianChart kind="line" x={x} series={series} hidden={hidden} aria-label="Applications per week by team" />
+			</ChartFrame>
+			<SegmentedControl value={state} onValueChange={(v) => setState(v as ChartStatus)} size="sm" aria-label="Preview state" className="justify-self-start">
+				{(["ready", "loading", "empty", "error"] as const).map((s) => <Segment key={s} value={s}>{s[0].toUpperCase() + s.slice(1)}</Segment>)}
+			</SegmentedControl>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Bar chart
+- Stat card with comparison
+- Breakdown table
+- Data visualisation colours
+- Export menu