@twoux/ui 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,92 @@
+# Price chart
+
+One price over a session: a line with a light wash, the last value tagged on the right axis, the previous close as a dashed reference, a live dot, and an axis that says when it does not start at zero.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- A price or rate that moves within a narrow band, where the movement is the point, such as a share price today.
+- A live value where people need the latest level and where it stands against a reference.
+
+## When not to use
+
+- For amounts that should be compared from zero, such as revenue. Use the TwoUX Line chart card, which always starts at zero.
+- For open, high, low and close per day. Use the TwoUX Candlestick chart.
+
+## Structure
+
+1. Title and subtitle (unit, delay)
+2. Plot: line with a 10% wash down to the axis floor
+3. Right axis with ticks and the last-value tag
+4. Dashed reference line with label (previous close)
+5. Live dot at the last point
+6. Time axis across the whole session
+7. Note under the axis when it does not start at zero
+8. Crosshair tooltip: time, price, change against the reference
+
+## Guidelines
+
+- Start the axis at zero unless the range is narrow; when it does not, say so under the axis.
+- Lay out the whole session on the time axis so the empty part of the day stays visible.
+- Tag the last value on the right axis and hide ticks that would collide with it.
+- Draw the reference as a dashed grey line with a text label, never a series.
+- Fill under the line with a light wash of the series colour, not a solid block.
+- The live dot pulses only while the market is open, and never under reduced motion.
+- 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
+
+- Put the unit and delay in the subtitle, such as In pence, 15 minutes delayed.
+- Label the reference by what it is (Previous close), with its value.
+
+## 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: "Line chart showing Ashdown plc share price today in pence."
+- 2.2.2 and 2.3.3: the pulsing dot is under five seconds per cycle and stops under prefers-reduced-motion.
+
+## 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
+
+### intraday
+
+```tsx
+import { ChartFrame, PriceChart } from "@twoux/ui";
+
+export const meta = { title: "Share price today", description: "Ten-minute prices from the open, the session's remaining slots left empty, the last price tagged on the right axis and the previous close as a dashed reference. The axis starts above zero and says so.", order: 1 };
+
+const TIMES = ["08:00", "08:10", "08:20", "08:30", "08:40", "08:50", "09:00", "09:10", "09:20", "09:30", "09:40", "09:50", "10:00", "10:10", "10:20", "10:30", "10:40", "10:50", "11:00", "11:10", "11:20", "11:30", "11:40", "11:50", "12:00", "12:10", "12:20", "12:30", "12:40", "12:50", "13:00", "13:10", "13:20", "13:30", "13:40", "13:50", "14:00", "14:10", "14:20", "14:30", "14:40", "14:50", "15:00", "15:10", "15:20", "15:30", "15:40", "15:50", "16:00", "16:10", "16:20", "16:30"];
+const TRADED = [741.8, 742.7, 742.5, 742.2, 741.0, 740.9, 742.6, 743.3, 745.0, 745.5, 746.2, 746.6, 744.4, 745.7, 746.6, 747.4, 745.2, 742.9, 741.8, 741.3, 741.9, 742.0, 742.9, 742.1, 742.7, 743.4, 742.6, 745.2, 746.1, 747.9, 747.2, 746.3, 746.0, 746.0, 747.0, 747.5, 747.1, 745.9, 745.3];
+const PRICES = TIMES.map((_, i) => TRADED[i] ?? null);
+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 share price"
+			description="Today, in pence, 15 minutes delayed"
+			table={{ columns: ["Time", "Price"], rows: TIMES.slice(0, TRADED.length).map((t, i) => [t, pence(TRADED[i])]) }}
+		>
+			<PriceChart x={TIMES} data={PRICES} format={pence} reference={{ value: 741.2, label: "Previous close" }} live aria-label="Ashdown plc share price today" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Line chart card
+- Candlestick chart
+- Change list

package/agent/docs-md/chart-radial-bars.md

@@ -0,0 +1,109 @@
+# Radial bars
+
+One to four small concentric rings, each the share of a fixed limit such as seats, credits or storage, with used of limit always written beside them. Never actual against target: that stays the bullet chart.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing two to four limits of a plan together in the space of a stat card, such as seats, assistant credits and storage this month.
+- One budget that resets, such as an SLA error budget, where a ring with the share in the centre fits a small tile.
+
+## When not to use
+
+- For actual against a target, such as bookings against plan. Use the TwoUX Bullet chart: angles are read less exactly than lengths.
+- For a single limit with a reset date and what stops at the limit. Use the TwoUX Usage meter.
+- To compare amounts across categories around a circle. Use a Bar chart: outer rings look longer than inner ones for the same value.
+- For parts of one total. Use a Donut chart or Share bar.
+- For a value with no fixed maximum, or for the progress of a task. A ring needs a real limit.
+
+## Structure
+
+1. Rings, outermost first: grey track and an arc from 12 o'clock clockwise
+2. Zero tick at 12 o'clock
+3. Share in the centre when there is one ring
+4. List: colour key, measure name, used of limit and share
+5. Status badge when a ring is at or over its limit
+6. Tooltip under the rings on hover or focus
+
+## Guidelines
+
+- Use radial bars only for share of a fixed limit, 0 to 100% of capacity, quota or budget.
+- Show at most four rings, at 96 to 160px. Extra items are not drawn.
+- Write used of limit and the share as text beside the rings; the ring only repeats it.
+- Start every ring at 12 o'clock and run clockwise from zero. A value over the limit fills the ring; it never wraps round twice.
+- Colour rings in series order. A ring at or over its limit adds At limit or Over limit as a badge; never recolour a ring as the only cue.
+- No needle, no half-circle dial and no thresholds on the ring.
+- 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 each ring by what it measures, as a noun: Seats, Assistant credits, Storage.
+- Write used of limit with the unit, then the share: 38 of 50 seats · 76%.
+- Put the plan and reset date in the chart description: Growth plan · resets 1 Dec.
+
+## Accessibility
+
+- 1.1.1 and WAI complex images: the chart's accessible name lists each measure as used of limit, share and status.
+- 1.4.1 Use of Color: every value and status is printed in the list; colour only links a ring to its row.
+- 1.4.11 Non-text Contrast: arcs meet 3:1 against the grey track.
+- 2.1.1 Keyboard: one tab stop, arrow keys move between rings and show the same tooltip as hover.
+- 1.4.10 Reflow: the list moves under the rings on narrow screens.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the chart |
+| ← → ↑ ↓ | Move to the previous or next ring |
+| Home End | Go to the outer or inner ring |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### error-budget
+
+```tsx
+import { ChartFrame, RadialBars, radialBarsTable } from "@twoux/ui";
+
+export const meta = { title: "One ring: SLA error budget", description: "A single ring shows its share in the centre. The budget is a fixed limit for the month, so the ring fits; progress against a target would be a bullet chart.", order: 2 };
+
+const ITEMS = [{ id: "budget", label: "Error budget used", value: 26, limit: 43, unit: "min" }];
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full max-w-sm" title="Checkout API error budget" description="99.9% availability · November" table={radialBarsTable(ITEMS)} height={120}>
+			<RadialBars items={ITEMS} size={104} aria-label="Checkout API error budget used in November" />
+		</ChartFrame>
+	);
+}
+```
+
+### workspace-usage
+
+```tsx
+import { ChartFrame, RadialBars, radialBarsTable } from "@twoux/ui";
+
+export const meta = { title: "Workspace usage this month", description: "Seats, assistant credits and storage, each as a share of the plan's limit. The list says every value in words; the rings only repeat it. Seats at the limit add a status badge.", order: 1 };
+
+const ITEMS = [
+	{ id: "seats", label: "Seats", value: 50, limit: 50, unit: "seats" },
+	{ id: "credits", label: "Assistant credits", value: 13_200, limit: 20_000, unit: "credits" },
+	{ id: "storage", label: "Storage", value: 38, limit: 100, unit: "GB" },
+];
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full max-w-md" title="Plan usage" description="Growth plan · resets 1 Dec" table={radialBarsTable(ITEMS)} height={140}>
+			<RadialBars items={ITEMS} aria-label="Plan usage this month" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Usage meter
+- Bullet chart
+- Donut chart
+- Stat card with comparison

package/agent/docs-md/chart-radial-lines.md

@@ -0,0 +1,111 @@
+# Radial lines
+
+A line chart wrapped round a circle for cyclical periods (hour of day, day of week, month), so the last period runs into the first. One to three series, values from zero, gaps for missing data.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing how a measure rises and falls through a repeating cycle where the wrap-around matters, such as support tickets by hour of day across two queues.
+- Daily or weekly rhythms, such as sign-ins by day of week, where Sunday into Monday should read as one stretch.
+
+## When not to use
+
+- For time that does not repeat, such as revenue by month over two years. Use the TwoUX Line chart card.
+- For exact comparisons between periods. Use a Bar chart: values near the centre are hard to compare.
+- For a cycle against a second dimension, such as hour by weekday. Use the TwoUX Heatmap.
+- For more than three series. Split them into small charts side by side.
+
+## Structure
+
+1. Title and subtitle with the period averaged and time zone
+2. Value rings from zero, three or four, labelled along the top spoke
+3. One spoke per period, labels round the outside
+4. Lines in series colours, joined from the last period to the first
+5. Gaps for missing data
+6. Legend for two or more series
+7. Tooltip for the nearest period on hover or focus
+
+## Guidelines
+
+- Use radial lines only for cyclical periods: hour of day, day of week, month of year.
+- Start the first period at 12 o'clock and run clockwise.
+- Start the value axis at zero with three or four labelled rings; never crop the centre.
+- Draw missing data as a gap, never as zero. Join the last period to the first only when both have values.
+- Show one to three series as lines; no area fill.
+- Show a legend only for two or more series; legend keys hide series without changing colours.
+- 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 measure and the cycle in the title: Tickets opened by hour.
+- Say what was averaged and the time zone in the description: Average per day, last 30 days, UK time.
+- Write periods as people read them: 00:00 to 23:00, Mon to Sun, Jan to Dec.
+
+## Accessibility
+
+- 1.1.1 and WAI complex images: the accessible name gives the cycle, where it starts, and each series' highest and lowest period and gaps.
+- 2.1.1 Keyboard: one tab stop; arrow keys move round the cycle and wrap, showing the same tooltip as hover.
+- 1.4.13 Content on Hover or Focus: the tooltip stays while the period is active and Esc hides it.
+- 1.4.11 Non-text Contrast: lines meet 3:1 against the surface.
+- 1.4.10 Reflow: the chart shrinks to its container and the table view lists every value.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the chart |
+| → ↓ | Next period, clockwise; wraps from the last to the first |
+| ← ↑ | Previous period, anticlockwise |
+| Home End | Go to the first or last period |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### logins-by-weekday
+
+```tsx
+import { ChartFrame, RadialLines, radialLinesTable } from "@twoux/ui";
+
+export const meta = { title: "One series: sign-ins by day of week", description: "One series needs no legend. Sunday meets Monday, so the weekend dip reads as one shape.", order: 2 };
+
+const DAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+const SERIES = [{ id: "signins", label: "Sign-ins", data: [4_820, 5_130, 5_060, 4_910, 3_980, 820, 640] }];
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full max-w-md" title="Sign-ins by day of week" description="Average per day, last 12 weeks" table={radialLinesTable(DAYS, SERIES, undefined, "Day")} height={260}>
+			<RadialLines periods={DAYS} series={SERIES} periodLabel="Day" maxSize={260} aria-label="Sign-ins by day of week, last 12 weeks" />
+		</ChartFrame>
+	);
+}
+```
+
+### tickets-by-hour
+
+```tsx
+import { ChartFrame, RadialLines, radialLinesTable } from "@twoux/ui";
+
+export const meta = { title: "Support tickets by hour of day", description: "Two queues over 24 hours. Midnight sits at the top, so the overnight hours read as one stretch. 04:00 has no data after a logging outage and shows as a gap.", order: 1 };
+
+const HOURS = Array.from({ length: 24 }, (_, h) => `${String(h).padStart(2, "0")}:00`);
+const SERIES = [
+	{ id: "billing", label: "Billing", data: [6, 4, 3, 2, null, 3, 8, 18, 34, 52, 61, 58, 49, 55, 60, 54, 44, 31, 22, 17, 14, 12, 10, 8] },
+	{ id: "technical", label: "Technical", data: [14, 12, 10, 9, null, 11, 16, 24, 31, 38, 42, 40, 36, 39, 43, 41, 37, 33, 29, 27, 24, 21, 18, 16] },
+];
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Tickets opened by hour" description="Average per day, last 30 days, UK time" table={radialLinesTable(HOURS, SERIES, undefined, "Hour")} height={320}>
+			<RadialLines periods={HOURS} series={SERIES} periodLabel="Hour" aria-label="Support tickets opened by hour of day, last 30 days" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Line chart card
+- Heatmap
+- Bar chart
+- Data visualisation

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

@@ -0,0 +1,104 @@
+# Sankey chart
+
+Flows from left to right across two or three columns, such as traffic sources to pages to outcomes. Link width shows value; hover or focus highlights a path.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing how a quantity splits and recombines across stages, such as visits from sources to pages to outcomes.
+- Finding the largest flows into a loss, such as where people leave.
+
+## When not to use
+
+- For ordered stages where each is a subset of the last. Use the TwoUX Funnel.
+- For more than three columns or about 12 nodes; split it or use a table.
+
+## Structure
+
+1. Title and subtitle
+2. Columns of nodes
+3. Links, width by value
+4. Labels: name, value and share of column
+5. Highlighted path on hover or focus
+6. Tooltip: from, to, value, share of source
+
+## Guidelines
+
+- Keep to two or three columns and about 12 nodes.
+- Link width is proportional to value; links use one hue at low opacity so overlaps stay readable.
+- Hovering a node lights every flow through it; hovering a link lights that link.
+- Labels give name, value and share of the column when there is room; on narrow screens names only.
+- The Table view lists every flow as from, to and value.
+- 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 last column by outcome (Started trial, Left), not by page.
+- Shares are of the column, so each column adds to 100%.
+
+## 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: "Sankey chart showing visits from source to page to outcome, last 30 days."
+- 1.4.1 Use of Color: links are one hue; their values are in labels, tooltips and the table.
+
+## 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
+
+### pricing-traffic
+
+```tsx
+import { ChartFrame, SankeyChart, sankeyTable } from "@twoux/ui";
+
+export const meta = { title: "Visits to the pricing page", description: "Where visits came from, which page they reached, and what they did next. Hover a node to light every flow through it.", order: 1 };
+
+const NODES = [
+	{ id: "organic", label: "Organic search" },
+	{ id: "paid", label: "Paid search" },
+	{ id: "direct", label: "Direct" },
+	{ id: "referral", label: "Referral" },
+	{ id: "pricing", label: "Pricing page" },
+	{ id: "docs", label: "Docs" },
+	{ id: "trial", label: "Started trial" },
+	{ id: "demo", label: "Booked demo" },
+	{ id: "left", label: "Left" },
+];
+const LINKS = [
+	{ source: "organic", target: "pricing", value: 8_200 },
+	{ source: "organic", target: "docs", value: 4_100 },
+	{ source: "paid", target: "pricing", value: 5_600 },
+	{ source: "direct", target: "pricing", value: 3_900 },
+	{ source: "direct", target: "docs", value: 2_300 },
+	{ source: "referral", target: "pricing", value: 1_800 },
+	{ source: "pricing", target: "trial", value: 2_900 },
+	{ source: "pricing", target: "demo", value: 1_100 },
+	{ source: "pricing", target: "left", value: 15_500 },
+	{ source: "docs", target: "trial", value: 1_200 },
+	{ source: "docs", target: "left", value: 5_200 },
+];
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Visits to pricing and docs" description="Last 30 days" table={sankeyTable(NODES, LINKS)} height={280}>
+			<SankeyChart nodes={NODES} links={LINKS} aria-label="Visits from source to page to outcome, last 30 days" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Funnel
+- Bar chart
+- Breakdown table

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

@@ -0,0 +1,87 @@
+# Scatter chart
+
+One dot per record placed by two measures, such as each live listing by advertised salary and applications, for spotting relationships and outliers.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- When the question is whether two measures move together across records: salary and applications per listing, or days open and applications.
+- When outliers matter: a listing with a high salary and few applications is worth opening.
+
+## When not to use
+
+- For change over time. Use the Line chart card.
+- For fewer than about ten records. Use a Breakdown table; a scatter of five dots shows no pattern.
+- To compare candidates. Plotting people by scores invites ranking them; candidate decisions stay with the hiring team and are never made from a chart.
+- To encode a third measure as dot size. Use a second scatter or a table instead.
+
+## Structure
+
+1. Title and subtitle
+2. Plot: x-axis and y-axis, each with a title and unit
+3. Dots, one per record (up to three groups by colour and shape)
+4. Optional threshold lines with text labels
+5. Legend when there are two or more groups
+6. Details popover: the record's name and both values, with a link to it
+
+## Guidelines
+
+- Each axis has a title with its unit; axes may start above zero if the axis says so, because position, not length, carries the value.
+- Use at most three groups, coloured with categorical colours 1 to 3 and each with its own marker shape (circle, square, triangle), since any dot can touch any other.
+- Keep dots small (6px) with a 1px surface-colour outline so overlapping dots stay visible.
+- Selecting a dot opens the details popover with the listing's name, both values and a link to the record.
+- Do not draw a trend line unless the team asked for one and its method is named in the footer.
+
+## Content
+
+- Title names both measures: "Salary and applications by listing". Subtitle gives the scope: "Live listings, last 30 days".
+- Axis titles are short with units: "Salary (£k)", "Applications".
+- Popover reads as key and value pairs: "Junior Product Designer, Leeds", "Salary £32k", "Applications 46".
+
+## Accessibility
+
+- Description: "Scatter chart showing salary and applications for 38 live listings, last 30 days." The Table view lists every record with both values.
+- Groups differ by marker shape as well as colour.
+- Arrow keys move from dot to dot in x order and open each popover; a pinned popover stays until Esc.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the plot, then the legend |
+| ← → | Move to the previous or next dot along the x-axis |
+| Enter | Pin the popover and reach its link |
+| Esc | Close the popover |
+
+## Examples
+
+### salary-applicants
+
+```tsx
+import { ChartFrame, ScatterChart } from "@twoux/ui";
+
+export const meta = { title: "Salary against applicants", description: "One dot per listing, up to three teams, each with its own colour and shape. Arrow keys move along the x axis; Enter pins the details with a link to the listing.", order: 1 };
+
+const P = [
+	["Junior Product Designer", 30, 38, "Design"], ["Senior Product Designer", 58, 37, "Design"], ["Content Designer", 42, 21, "Design"],
+	["Frontend Engineer", 52, 112, "Engineering"], ["Backend Engineer", 60, 64, "Engineering"], ["QA Engineer", 40, 47, "Engineering"], ["Platform Engineer", 68, 29, "Engineering"],
+	["Data Analyst", 41, 64, "Data"], ["Analytics Engineer", 55, 33, "Data"], ["Data Scientist", 62, 41, "Data"],
+] as const;
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Salary and applicants" description="Open listings, salary from in £000s">
+			<ScatterChart aria-label="Salary against applicants by team" xTitle="Salary from (£000s)" yTitle="Applicants" points={P.map(([label, x, y, group], i) => ({ id: String(i), label, x, y, group, href: "#listing" }))} />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Line chart card
+- Breakdown table
+- Data visualisation colours
+- Chart drill-down
+- Data visualisation

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

@@ -0,0 +1,89 @@
+# Share bar
+
+One whole split into up to six parts in a single horizontal bar, with each part's name and share in a legend above. Smaller parts fold into a grey Other.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing how one total splits at one moment, read at a glance, such as recurring revenue by plan.
+- A card or table header has room for a line, not a chart: a thin bar takes 8px and the legend carries the numbers.
+
+## When not to use
+
+- To compare parts precisely or rank more than six of them. Use the TwoUX Bar chart, because bars on one baseline compare more exactly than segments end to end.
+- To show the split changing over time. Use the TwoUX Area chart.
+
+## Structure
+
+1. Title and subtitle
+2. Legend above the bar: swatch, name and share for each part
+3. Bar: one block per part with a 2px surface gap
+4. Other: the folded tail, in grey
+5. Tooltip: name, share and amount
+
+## Guidelines
+
+- Keep to six parts; the smallest fold into Other, which is always grey and always last.
+- Separate parts with a 2px gap in the surface colour, never a border.
+- Colours follow the order you pass, c1 first. Pass parts in a stable order so a part keeps its colour from one period to the next.
+- Thin bar: shares go in the legend above, not on the bar. Tall bar: the share prints inside each block only when it fits, and the legend gives names.
+- Use a share bar instead of a donut when space is a line, not a square.
+- 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
+
+- Shares to one decimal place in the legend, whole percentages inside a tall bar.
+- Name the part people know (Business, Team), not an internal code.
+
+## Accessibility
+
+- 1.4.1 Use of Color: every part is named in the legend and in the generated summary, so colour is not the only way to tell parts apart.
+- 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.
+
+## 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
+
+### plan-revenue
+
+```tsx
+import { ChartFrame, ShareBar, shareTable } from "@twoux/ui";
+
+export const meta = { title: "Recurring revenue by plan", description: "A thin bar under a legend that already gives each share. Eight plans arrive; the two smallest fold into Other so the bar keeps six parts.", order: 1 };
+
+const PLANS = [
+	{ id: "business", label: "Business", value: 1_284_000 },
+	{ id: "team", label: "Team", value: 612_000 },
+	{ id: "enterprise", label: "Enterprise", value: 498_000 },
+	{ id: "starter", label: "Starter", value: 231_000 },
+	{ id: "agency", label: "Agency", value: 104_000 },
+	{ id: "education", label: "Education", value: 46_000 },
+	{ id: "charity", label: "Charity", value: 21_000 },
+	{ id: "legacy", label: "Legacy", value: 9_000 },
+];
+const gbp = (n: number) => `£${(n / 1000).toLocaleString("en-GB", { maximumFractionDigits: 0 })}k`;
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Recurring revenue by plan" description="Annual run rate, 5 November 2026" table={shareTable(PLANS, gbp, "Plan")} height={60}>
+			<ShareBar parts={PLANS} format={gbp} aria-label="Recurring revenue by plan" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Donut chart
+- Bar chart
+- Treemap