@misoto22/design 0.6.1 → 0.8.0

package/dist/agent/Progress.md

@@ -4,14 +4,37 @@ A bar that fills, or sweeps when the end is unknown.
 
 - Group: Feedback
 - Import: `import { Progress } from '@misoto22/design'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/progress/
 - Related: spinner
 
+## Anatomy
+
+- **Track** (required) — The Radix root: 4px of --stone at the pill radius, carrying role="progressbar" and aria-label from label. It is full width by default, so it takes the measure of whatever column it is dropped into.
+- **Fill** — The indicator, in --accent, sized by width rather than a translate so it grows from the inline start in a right-to-left document too. Present only when value is a number.
+- **Sweep** — What replaces the fill when value is null: a quarter-width --accent bar travelling the track on transform alone, mirrored under rtl so it never reads as progress running backwards. Under prefers-reduced-motion it stops where it is drawn rather than filling the track.
+- **Value row** — label on the left, a tabular-nums percentage on the right, above the track. It renders only when showValue is set and value is a number, which makes it the only place label is ever visible.
+- **Column** — The flex wrapper holding the row and the track. className lands here; every other prop is forwarded to the Radix root instead.
+
+## Best practices
+
+### Do
+
+- Pass showValue on any determinate bar. It is the only thing that puts label on screen — without it the name exists solely as aria-label, and a sighted reader is left with an unlabelled 4px rule and no number.
+- Switch value back to null the moment the estimate stops being real. The fill transitions its width over --duration-slow, so a number that revises downward animates backwards and the reader watches progress undo itself.
+- Set max to the real total rather than converting to a percentage yourself. The width and aria-valuemax come off the same number, so the picture and the announcement cannot drift — but a value past the ceiling still clamps, and an underestimated total parks the bar at full for the rest of the operation rather than admitting the estimate was wrong.
+
+### Don’t
+
+- Do not pass a max that is not a positive number. Radix refuses it, prints its own warning and falls back to 100, and the width falls back with it — so value={40} paints and announces forty per cent of a ceiling nobody chose.
+- Do not read the resting sweep as a position. Under prefers-reduced-motion it stops at a quarter of the track, which is what a determinate bar at 25% looks like — the announcement is the only thing that tells the two apart, and it is the reason omitting value matters.
+- className styles the column, not the track, so a height utility passed that way stretches the wrapper and leaves the 4px bar exactly where it was.
+
 ## Accessibility
 
 - Omitting value drops aria-valuenow, so a screen reader hears “indeterminate” rather than a number that is a guess.
 - label is required — a bare bar announces nothing.
+- The width is computed from value and max, the same pair Radix announces as aria-valuenow and aria-valuemax, so what is drawn and what is said cannot disagree.
 
 ## Progress
 
@@ -19,11 +42,12 @@ A bar that fills, or sweeps when the end is unknown. Flat: a track in `--stone`,
 
 ### Props
 
-- `value` — `number | null` default `null`. 0–100. Omit (or pass `null`) when the duration is genuinely unknown — the bar then sweeps instead of filling, and Radix drops `aria-valuenow` so a screen reader is told "indeterminate" rather than a number that is a guess.
+- `value` — `number | null` default `null`. 0 to `max`, which is 100 unless you say otherwise. Omit (or pass `null`) when the duration is genuinely unknown — the bar then sweeps instead of filling, and Radix drops `aria-valuenow` so a screen reader is told "indeterminate" rather than a number that is a guess.
+- `max` — `number`. What `value` is measured against. 100 by default. The width is computed from it as well as announced from it. It used to be only announced: `max` reached Radix through `...rest` while the width was `value` clamped to 100, so `max={500}` with `value={100}` painted a full bar and told a screen reader "100 of 500". A max that is not a positive number is refused the way Radix refuses it — Radix warns, and both fall back to 100 rather than drawing one picture and announcing another.
 - `label` (required) — `string`. Names what is progressing. Required: a bare bar announces nothing.
 - `showValue` — `boolean` default `false`. Prints the percentage above the bar. Only meaningful when `value` is set.
 
-Also accepts: `Omit<ComponentProps<typeof ProgressPrimitive.Root>, 'value'>`.
+Also accepts: `Omit<ComponentProps<typeof ProgressPrimitive.Root>, 'value' | 'max'>`.
 
 ## Examples
 

package/dist/agent/RadarChart.md

@@ -4,7 +4,7 @@ A profile across several named dimensions.
 
 - Group: Charts
 - Import: `import { RadarChart } from '@misoto22/design/charts'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/radar-chart/
 - Related: line-chart, pie-chart
 
@@ -12,6 +12,28 @@ A profile across several named dimensions.
 
 Recognising a silhouette. The area a radar encloses depends on the order its spokes happen to be in, so it is the wrong chart for comparing magnitudes.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with the polar plot inside one ChartContainer.
+- **Polygons** (required) — <RadarChart.Radar>. variant="filled" is the default and paints at 2.2 times --chart-fill, because a radar’s fill IS the mark rather than a wash under a line and has to hold its shape where two of them overlap.
+- **Spoke labels** — <RadarChart.PolarAngleAxis>, the names around the perimeter. They are the only thing that says what a corner of the silhouette measures.
+- **Radial scale** — <RadarChart.PolarRadiusAxis>, and it is opt-in. Leave it out and the rings carry no numbers at all: the reader has a shape and no idea what one ring is worth.
+- **Grid** — <RadarChart.PolarGrid>, polygonal rather than circular by default, so the rings line up with the polygon the data draws over them.
+- **Legend** — <RadarChart.Legend>. Two overlapping outlines two steps apart on the grey ramp name nothing, and there is no axis here to name them instead.
+
+## Best practices
+
+### Do
+
+- Fix the spoke ORDER and keep it fixed across every radar on the page. The area a polygon encloses is a function of the order the dimensions happen to sit in, so re-ordering the spokes changes the silhouette without changing one number.
+- Put every dimension on a comparable scale first — a percentile, a score out of ten, an index. One radius serves all the spokes, so a spoke in milliseconds beside one in percent draws a spike that means nothing.
+- Switch to variant="lines" past two series. Filled polygons overlap, and judging areas through two layers of translucency is precisely what this form is worst at.
+
+### Don’t
+
+- Do not read magnitude off it. A radar is for recognising a silhouette — the same profile before and after — and which of two is bigger is a question a BarChart answers and this one only appears to.
+- Do not skip <RadarChart.PolarRadiusAxis> and call the chart finished. It renders, the rings render, and nothing on screen says whether the outer ring is 100 or 1,000; the sr-only table still has the figures, the sighted reader does not.
+
 ## Accessibility
 
 - title is required; the rows are also rendered as a visually hidden table.
@@ -31,12 +53,14 @@ A profile across several named dimensions — the shape for "what is this thing
 - `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
 - `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
 - `chartProps` — `ComponentProps<typeof RechartsRadarChart>`. Escape hatch onto the raw Recharts chart element.
-- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render. Selection dims every other series.
+- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
+- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
 - `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
 - `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
 - `loadingPoints` — `number`. How many points the skeleton draws.
 - `angleDataKey` — `keyof TData & string`. The row field naming each spoke. Used by the table view.
 - `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.
 
 ## Types
 

package/dist/agent/RadialChart.md

@@ -4,7 +4,7 @@ Values on an arc — a gauge, or a few totals against one scale.
 
 - Group: Charts
 - Import: `import { RadialChart } from '@misoto22/design/charts'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/radial-chart/
 - Related: pie-chart, bar-chart
 
@@ -12,6 +12,27 @@ Values on an arc — a gauge, or a few totals against one scale.
 
 A single value against a fixed total. Past about four bars a BarChart is the honest choice, because a radial bar’s radius is not its value.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero rows. Its hidden table needs a value field, which it takes from valueKey or, failing that, from the dataKey of the composed <RadialChart.RadialBar> — so a chart that names neither still has no table.
+- **Arcs** (required) — <RadialChart.RadialBar>, one per row, 14px thick with a 5px cap. variant="semi" drops the centre to 70% so a half arc sits in the middle of its own box rather than at the top of it.
+- **Track** — showTrack, on by default, painting the unfilled remainder behind each arc in --chart-track. It is what makes a gauge a gauge: without it there is no visible whole for the fill to be a part of.
+- **Scale** — The PolarAngleAxis the root inserts when max is set, with domain [0, max] and its ticks off. Leave max unset and the domain is taken from the data instead.
+- **Legend** — <RadialChart.Legend>. An arc has no category axis, so above one bar this is the only thing naming them.
+
+## Best practices
+
+### Do
+
+- Set max on anything that is a gauge. Without it the scale comes from the data, so the largest bar always fills the arc and 62% and 98% are drawn identically.
+- Pass valueKey when the arc is not the only mark. It names the field the hidden table prints and the field the LEGEND reports a selection from; without either it or a composed <RadialChart.RadialBar> there is no value field, and the table is not empty but absent.
+- Use variant="semi" for a single value. A half arc reads as a dial with a floor and a ceiling, where a full ring asks the reader to work out what a whole circle was worth.
+
+### Don’t
+
+- Do not compare bars across radii. A radial bar’s LENGTH is its value but its RADIUS is not, so an inner arc and an outer arc holding the same number are drawn different lengths — past about four bars a BarChart is the honest form.
+- Do not let a reader take an arc as a share of the ring when max is unset. A full sweep then means the biggest thing here, which is a different sentence from all of it.
+
 ## Accessibility
 
 - title is required; pass valueKey and the rows are also rendered as a visually hidden table.
@@ -37,11 +58,13 @@ Values on an arc — a gauge, or a small set of totals against one scale. The ca
 - `max` — `number`. What a full sweep is worth. Without it the scale comes from the data, so the largest bar always fills the arc — which is right for a comparison and wrong for a gauge. Set it (typically 100) whenever a single value has to read against a fixed total, or "62%" and "98%" will look identical.
 - `innerRadius` — `number | string` default `'30%'`. Where the arc starts, from the centre.
 - `outerRadius` — `number | string` default `'100%'`. Where the arc ends.
-- `defaultSelectedBar` — `string | null` default `null`. The bar lit on first render.
+- `defaultSelectedBar` — `string | null` default `null`. The bar lit on first render, when the chart keeps its own selection.
+- `selectedBar` — `string | null`. The selected bar, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedBar`.
 - `onSelectionChange` — `(selection: { name: string; value: number } | null) => void`. Fires when the selection changes, and with null when it is cleared.
 - `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
-- `valueKey` — `keyof TData & string`. The row field holding each bar's number. Used by the table view.
+- `valueKey` — `keyof TData & string`. The row field holding each bar's number, for the table view and for the selection the legend reports. Falls back to the `dataKey` of the composed `<RadialChart.RadialBar>`, so the usual call site needs neither.
 - `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.
 
 ## Types
 

package/dist/agent/RadioGroup.md

@@ -4,10 +4,31 @@ A set of mutually exclusive choices.
 
 - Group: Forms
 - Import: `import { RadioGroup } from '@misoto22/design'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/radio-group/
 - Related: checkbox, select
 
+## Anatomy
+
+- **Group** (required) — A <div role="radiogroup"> stacking its options. Being a div is why the label above it names the group by being pointed AT — aria-labelledby, not htmlFor — and why the words do not click through.
+- **Row** (required) — The <label> RadioGroupItem wraps around control and words. It is the click target — a bare 18px circle is below every pointer-target guideline — and it is the only source of the option’s accessible name.
+- **Circle** (required) — The 18px control itself, its border turning --accent when chosen.
+- **Dot** — The 10px --accent fill inside the circle, present only on the chosen option.
+
+## Best practices
+
+### Do
+
+- Name the group. Inside a Field its label does it, through aria-labelledby; standing alone it needs its own aria-label, and without either the group is announced as three unlabelled radios.
+- Set defaultValue or value. Selection follows focus here, so a group that starts empty commits an answer the moment anybody arrows into it — including a reader who was only passing through on the way to the next field.
+- Add an explicit “None” or “Any” option when the answer is genuinely optional: there is no way back to nothing once a radio is chosen, neither by clicking it again nor from the keyboard.
+
+### Don’t
+
+- Do not hang an expensive effect on onValueChange. Every arrow press commits, so a group whose options fetch or navigate fires once per key on the way past the ones nobody wanted.
+- Do not reach past RadioGroupItem to the Radix primitive or hand-roll the row: selection-follows-focus is implemented in this item’s own focus handler, not upstream, so a hand-rolled one moves the outline and selects nothing.
+- Do not disable one option to mean “not available here”: the roving focus skips it entirely, so a keyboard reader never learns the option exists. Say why in the Field’s hint and leave the option out.
+
 ## Accessibility
 
 - One tab stop for the whole group; the arrow keys move between options, per the ARIA radiogroup pattern.
@@ -20,7 +41,7 @@ A set of mutually exclusive choices.
 
 ## RadioGroup
 
-A set of mutually exclusive choices. Radix owns the roving tabindex, so the whole group is ONE tab stop and the arrow keys move between options — which is what the ARIA radiogroup pattern requires and what a stack of hand-rolled `<input type="radio">` wrappers usually gets wrong.
+A set of mutually exclusive choices. Radix owns the roving tabindex, so the whole group is ONE tab stop and the arrow keys move between options — which is what the ARIA radiogroup pattern requires and what a stack of hand-rolled `<input type="radio">` wrappers usually gets wrong. Inside a `Field` the group takes its name from that label, by pointing back at it: the root is a `<div role="radiogroup">` and `<label for>` does not bind to one, so the words above it click through no more than a `<legend>` does. Standing alone, it still needs an `aria-label` of its own — an unnamed group is three unlabelled radios.
 
 Also accepts: `ComponentProps<typeof RadioGroupPrimitive.Root>`.
 

package/dist/agent/SankeyChart.md

@@ -4,7 +4,7 @@ Where a quantity goes as it moves through stages.
 
 - Group: Charts
 - Import: `import { SankeyChart } from '@misoto22/design/charts'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/sankey-chart/
 - Related: bar-chart
 
@@ -12,6 +12,27 @@ Where a quantity goes as it moves through stages.
 
 A funnel, a budget, an energy or traffic breakdown. The only chart here whose data is a graph rather than a table.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, named by title, with the diagram inside one ChartContainer.
+- **Node rectangles** (required) — The root’s own node renderer. A node whose name is in config is painted from its gradient; one that is not falls back to currentColor, so it is drawn plainly rather than lost.
+- **Node labels** — <SankeyChart.NodeLabel>, composed inside <SankeyChart.Node>, and entirely opt-in. Leave it out and NOTHING on the diagram is named — there is no legend here, so the names exist only in the tooltip and in the hidden table.
+- **Flow bands** — <SankeyChart.Link>. gradient fades the source’s colour into the target’s and is the variant that actually reads as flow; solid gives up colour entirely and lets the node rectangles carry identity.
+- **Hidden data table** (required) — The sr-only table lists the LINKS — from, to, value — rather than the nodes, because a table of node totals loses every from-and-to the diagram exists to state.
+
+## Best practices
+
+### Do
+
+- Treat the nodes array as an addressing table. A link’s source and target are INDEXES into it, so inserting a node at the front silently re-points every link at a different pair — and the layout still renders, which is why this belongs in a test rather than in an eyeball.
+- Compose <SankeyChart.Node> with a <SankeyChart.NodeLabel> inside it. Names are opt-in and there is no legend to fall back on, so a sankey without labels is a set of anonymous grey bands.
+- Keep the flows conserved, or give the shortfall a node of its own with a name. Band width is the only arithmetic on screen, and a node that quietly loses eight percent simply reads as a smaller node.
+
+### Don’t
+
+- Do not reach for it when the quantity only narrows along one path. That is a FunnelChart; a sankey spends its whole layout budget on splits that are not there.
+- Do not put twenty nodes in one column. nodePadding is 10px and the layout distributes what is left, so past a dozen a node rectangle is a few pixels tall and a label centred on it has nowhere to sit.
+
 ## Accessibility
 
 - title is required. The hidden table lists the FLOWS rather than the nodes — a table of node totals would lose every “from → to” the diagram exists to show.
@@ -38,10 +59,12 @@ Where a quantity goes as it moves through stages — the shape for a funnel, a b
 - `sort` — `boolean` default `true`. Lets the layout reorder nodes for the fewest crossings.
 - `align` — `'left' | 'justify'` default `'justify'`. How nodes are placed along the flow axis.
 - `verticalAlign` — `'justify' | 'top'` default `'justify'`. How nodes are distributed within a column.
-- `defaultSelectedNode` — `string | null` default `null`. The node lit on first render. Selecting one dims every flow it does not touch.
+- `defaultSelectedNode` — `string | null` default `null`. The node lit on first render, when the chart keeps its own selection. Selecting one dims every flow it does not touch.
+- `selectedNode` — `string | null`. The selected node, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedNode`.
 - `onSelectionChange` — `(selection: { name: string; value: number } | null) => void`. Fires when the selection changes, and with null when it is cleared.
 - `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
 - `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.
 
 ## Types
 

package/dist/agent/ScatterChart.md

@@ -4,7 +4,7 @@ Two measures against each other, one mark per observation.
 
 - Group: Charts
 - Import: `import { ScatterChart } from '@misoto22/design/charts'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/scatter-chart/
 - Related: line-chart, heatmap
 
@@ -12,6 +12,28 @@ Two measures against each other, one mark per observation.
 
 Correlation, clustering, outliers — the questions that do not survive being bucketed into a bar. The only chart here whose x axis is a number rather than a category.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with isLoading and an empty state. Emptiness is read from the declared table rows, for the same reason the table is declared at all: the observations live on each <Scatter>, and the root cannot see them.
+- **Numeric axes** (required) — <ScatterChart.XAxis> and <ScatterChart.YAxis>, both type="number" by default. The only chart in the group whose horizontal axis is a measurement rather than a category.
+- **Clouds** (required) — <ScatterChart.Scatter>, one per series, each carrying its OWN data array rather than reading the root’s. Six mark shapes, and a solid mark takes a 1px --chart-surface ring so two coincident observations stay countable.
+- **Size channel** — <ScatterChart.ZAxis>, range [40, 400] by default. That range is in AREA, not radius: doubling a radius quadruples the ink, which is how a bubble chart usually lies.
+- **Crosshair** — The tooltip’s cursor, a pair of rules rather than one band. A scatter point is located by two coordinates and a single vertical cursor answers half of that.
+- **Declared table** — table is a PROP here, not inferred. Scatter data lives on each series, so there are no rows on the root to read off — and passing nothing ships a figure with no table at all.
+
+## Best practices
+
+### Do
+
+- Declare table. It is the one chart in the group whose hidden table cannot be derived, so omitting it fails silently: the figure renders, is named, and has no numbers behind it.
+- Separate series by shape before anything else. Circle against cross stays legible where two steps of grey do not, and shape survives overprinting and forced colours — where every --series-* token becomes CanvasText and a lightness step is gone.
+- Reach for variant="outline" or shape="ring" on a dense cloud. A hollow mark shows what is under it; a solid one at two thousand points is a silhouette of the densest region and nothing else.
+
+### Don’t
+
+- Do not vary size between series to mean something. size is a flat radius in pixels, so it encodes nothing while looking exactly as if it does; <ScatterChart.ZAxis> is the only path that maps a value to a mark’s area.
+- Past three series shape stops separating them — circle, cross and triangle are distinct, and a fourth glyph is a diamond most readers see as a rotated square. Small multiples on shared axes is the answer, not a fourth mark.
+
 ## Accessibility
 
 - title is required. The table view is declared rather than inferred: scatter data lives on each series, so there is no single set of rows to read off the root.
@@ -32,9 +54,12 @@ Two measures against each other, one mark per observation — the shape for "is
 - `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
 - `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
 - `chartProps` — `ComponentProps<typeof RechartsScatterChart>`. Escape hatch onto the raw Recharts chart element.
-- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render. Selection dims every other series.
+- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
+- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
 - `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
 - `table` — `ScatterTable | false`. The rows behind the hidden table view, with the fields to print. Scatter data lives on each `<Scatter>` rather than on the root, so unlike every other chart here the table cannot be inferred — it is declared.
+- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading. Read from the declared `table` rows, for the same reason the table is declared: the observations live on each `<Scatter>`, and the root cannot see them.
 
 ## Types
 

package/dist/agent/ScrollArea.md

@@ -4,7 +4,7 @@ A box that scrolls, with a scrollbar that looks the same everywhere.
 
 - Group: Surfaces
 - Import: `import { ScrollArea } from '@misoto22/design'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/scroll-area/
 - Related: table
 
@@ -12,10 +12,31 @@ A box that scrolls, with a scrollbar that looks the same everywhere.
 
 A bounded panel — a long option list, a log. For page-level or prose scroll the scroll-slim utility is lighter and needs no component.
 
+## Anatomy
+
+- **Root** (required) — The bounded box, and where className lands. It is overflow-hidden and has no size of its own, so the height you give it here is the only thing that decides whether anything scrolls at all.
+- **Viewport** (required) — The element that actually scrolls, and the one carrying role="region", tabIndex 0 and label. Radix hides the platform’s scrollbar on it and sets the axis WITHOUT a bar to overflow: hidden. It is positioned, so an absolutely-positioned descendant travels with the content instead of hanging still over it.
+- **Bar** — One per orientation: an 8px track with a pill thumb at --rule-2, and touch-none — a finger scrolls the content, not the bar. It is drawn only while the pointer is inside the region and fades some 600ms after scrolling stops.
+- **Corner** — The square where two bars meet, which exists only at orientation="both" — the default.
+
+## Best practices
+
+### Do
+
+- Give it a height. With none, the root is as tall as its content, nothing ever overflows, and all the component added to the page was a keyboard stop.
+- Narrow orientation only when clipping the other axis is the thing you meant. Both axes scroll by default, because the axis without a bar is set to overflow: hidden — what is past that edge is not merely unmarked, it is unreachable by every key and every gesture, with the content perfectly well rendered.
+- Pass type="always" when the content ends flush at the boundary: the platform scrollbar is hidden and ours is not drawn until the pointer is inside, so at rest nothing on the screen says the box scrolls.
+
+### Don’t
+
+- Do not build a drag-to-scroll affordance over it — the thumb is deliberately touch-none and the viewport is a real overflow container, so touch dragging, momentum and the wheel are already the platform’s and behave as the reader expects.
+- Do not nest one inside another on the same axis: the inner viewport consumes the wheel until it reaches its own end, so a reader aiming at the outer list moves the inner one instead.
+
 ## Accessibility
 
 - The viewport stays focusable. A scrollable region whose contents are not focusable has nothing to Tab to, so everything past the fold does not exist without a mouse.
 - label is required, because an unnamed keyboard stop announces "group" and nothing else.
+- Both axes scroll unless a caller narrows orientation, so content wider than the box stays reachable rather than being clipped without a bar.
 
 ## Keyboard
 
@@ -24,12 +45,12 @@ A bounded panel — a long option list, a log. For page-level or prose scroll th
 
 ## ScrollArea
 
-A box that scrolls, with a scrollbar that looks the same on every platform. The reason to reach for this over `overflow-auto` is not the scrollbar — it is that Radix keeps the viewport focusable and the bar operable, which a bare overflow container does not. A scrollable region whose contents are not themselves focusable is unreachable by keyboard: there is nothing to Tab to, so everything past the fold does not exist without a mouse. For a page-level or prose scroll, the `scroll-slim` utility is lighter and needs no component. This is for a bounded panel: a long option list, a log, a sidebar that outgrows its column.
+A box that scrolls, with a scrollbar that looks the same on every platform. The reason to reach for this over `overflow-auto` is not the scrollbar — it is that Radix keeps the viewport focusable and the bar operable, which a bare overflow container does not. A scrollable region whose contents are not themselves focusable is unreachable by keyboard: there is nothing to Tab to, so everything past the fold does not exist without a mouse. For a page-level or prose scroll, the `scroll-slim` utility is lighter and needs no component. This is for a bounded panel: a long option list, a log, a sidebar that outgrows its column. Both axes scroll unless a caller says otherwise. The old vertical default read as a statement about which bar to draw and was in fact a statement about which half of the content existed: Radix sets the viewport's overflow from the mounted bars, so the axis without one was `hidden` and everything past it was unreachable — silently, and with the content perfectly well rendered.
 
 ### Props
 
 - `label` (required) — `string`. Names the region. Required, and not decoration: a scroll container is a keyboard stop, and an unnamed stop announces "group" and nothing else.
-- `orientation` — `'vertical' | 'horizontal' | 'both'` default `'vertical'`.
+- `orientation` — `'vertical' | 'horizontal' | 'both'` default `'both'`. Which axes get a bar — and therefore which axes scroll at all. Radix sets the viewport's overflow from the bars that are mounted, so an axis without one is `hidden`: what is past that edge is not merely unmarked, it is unreachable by every key and every gesture. `both` is the default for that reason. Narrow it only when clipping the other axis is the thing you meant.
 
 Also accepts: `ComponentProps<typeof ScrollAreaPrimitive.Root>`.
 

package/dist/agent/SearchableMenu.md

@@ -4,7 +4,7 @@ A menu of actions you can type into.
 
 - Group: Overlays
 - Import: `import { SearchableMenu } from '@misoto22/design'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/searchable-menu/
 - Related: dropdown-menu, command, combobox
 
@@ -12,6 +12,28 @@ A menu of actions you can type into.
 
 A DropdownMenu past about a dozen rows stops being scannable, and nesting submenus makes it worse. This is the same list with a filter over it. Not a Command palette: that is page-level and modal; this is anchored to a control.
 
+## Anatomy
+
+- **Trigger** (required) — A pill button built here rather than a Button: --control-h-sm tall, hairline bordered, with a chevron. Its accessible name is label, not the children you passed as its text.
+- **Panel** (required) — A Popover with its padding removed and a flat 16rem width, so the filter and the list run edge to edge inside it. Not modal — this is a Popover, not a Dialog.
+- **Filter** (required) — The Command input. Focus lands here on open and stays there; the highlight moves under it through aria-activedescendant.
+- **Rows** — One per MenuAction, as listbox options. shortcut prints as a Kbd at the end of the row, destructive paints it --danger, and selecting one closes the menu before running onSelect.
+- **Empty state** — emptyMessage, shown when the filter matches nothing. Say what would match rather than “no results”.
+
+## Best practices
+
+### Do
+
+- Give an action keywords for the word a reader reaches for that the label does not print — “download” for Export, “bin” for Delete. The label’s own text is lifted into the filter for you; a label built only from elements prints none, and development warns SEARCHABLE_MENU_LABEL_UNREADABLE rather than shipping a row nothing matches.
+- Make label the trigger’s visible text. It is set as aria-label on the trigger and overrides the children, so a button reading “Status” under a label of “Row actions” is announced as something the reader cannot say aloud (WCAG 2.5.3).
+- Keep actions that share a group next to each other in the array: groups are built by walking the list and extending only the LAST one, so the same group name appearing again after other rows produces a second heading with identical text.
+
+### Don’t
+
+- It is a Popover underneath, so it is not modal: the page behind still scrolls while the filter is open and the panel is re-anchored as it does. A surface that should hold the page still is CommandDialog.
+- className lands on the TRIGGER, not on the panel — the panel is a flat 16rem with no prop that widens it, so a long label wraps to a second line instead of the box growing to take it.
+- The trigger is --control-h-sm — 36px comfortable, 30px under data-density="compact" — which is below the 44px pointer target (WCAG 2.5.5), and it is not the system Button, so variant and size do not reach it.
+
 ## Accessibility
 
 - Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.

package/dist/agent/Select.md

@@ -4,7 +4,7 @@ A choice from a list, styled the whole way down.
 
 - Group: Forms
 - Import: `import { Select } from '@misoto22/design'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/select/
 - Related: combobox, native-select, field
 
@@ -12,12 +12,34 @@ A choice from a list, styled the whole way down.
 
 Up to roughly a dozen options. Past that a Combobox wins, because a list nobody can filter is slower to scan than one you can type into.
 
+## Anatomy
+
+- **Trigger** (required) — A <button role="combobox"> on CONTROL_BASE, so it matches the Input beside it exactly. It is named by the label and by its own value together, and carries the chevron that turns over while the panel is open.
+- **Value** — The chosen item’s text, or placeholder in --ink-3-aa when nothing is chosen. It truncates, and it is the half of the accessible name that says what was picked.
+- **Panel** — Portalled, at least as wide as the trigger and at most 18rem tall, with a scroll chevron appearing at each end once the list is longer than that.
+- **Item** — One option. The 3.5 tick box is always drawn and only the tick inside it appears, so choosing does not shunt every label sideways; data-highlighted is the fill, the tick is the chosen one.
+- **Group heading** — SelectLabel — a mono eyebrow inside a SelectGroup. It is a heading, not an option, which is the difference between it and a disabled item used as a divider.
+
+## Best practices
+
+### Do
+
+- Pass name when the value has to survive a submit. The trigger is a <button>; Radix renders the hidden native <select> that carries the value only when the control is inside a <form>, and only a named one sends anything.
+- Pick one spelling of invalid. The trigger reads the invalid prop and aria-invalid alike, including the one a Field sets from error, so setting both is two sources of truth for one border.
+- Divide long lists with SelectGroup and SelectLabel rather than a disabled item used as a heading: a disabled item is still an option, so a screen reader counts it and announces the list as one longer than it is.
+
+### Don’t
+
+- Inside a Field with a label, the label prop here is not announced — the field’s words name the trigger — so a label that disagrees with the one above it is dead text nobody will ever hear.
+- Do not lean on the closed trigger to show a long option: it truncates to keep the field’s height, so the end of the value is only readable with the panel open.
+- Do not point contentClassName at the trigger. className is the trigger; contentClassName is the panel, and confusing them is how a select gets a 18rem-wide dropdown over the thing it is choosing for.
+
 ## Accessibility
 
 - Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.
 - The option list is ours, so it does not change typeface, spacing and selection colour the moment it opens — which is what a native select does.
 - The keyboard contract is the platform's: typeahead, arrows, Home and End, Escape to close without choosing.
-- label is required. The trigger shows a value, and a value is not a name.
+- label is required, and it is announced WITH the value: the trigger reads "Region, Australia", because a value is not a name and a name without the value is not the answer. Inside a Field the FIELD’s label supplies the name half — the trigger’s aria-labelledby points at that label and at the value — and the label prop here is neither rendered nor announced, so one that disagrees with the words above it is text nobody will hear.
 
 ## Keyboard
 
@@ -40,11 +62,15 @@ A choice from a list, styled the whole way down. The option list is ours — dra
 ### Props
 
 - `contentClassName` — `string`. Classes for the option PANEL, not the trigger. `className` styles the trigger, which is the common case. This exists for the uncommon one: a select inside a bounded surface, where the default 18rem of list would cover the thing the reader is choosing for — a year picker over its own calendar, say.
-- `label` (required) — `string`. Names the control. Required — the trigger shows a value, and a value is not a name.
+- `label` (required) — `string`. Names the control. Required — the trigger shows a value, and a value is not a name. It is announced together with the value, not instead of it: the trigger is named by the label and by its own text, so a reader hears "Region, Australia". Inside a `Field` with a label, that label is used and this one is not repeated.
 - `placeholder` — `string` default `'Select…'`.
 - `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
 - `disabled` — `boolean`.
 - `className` — `string`.
+- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
+- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
+- `aria-invalid` — `boolean | 'true' | 'false'`. The spelling a form library sets; read together with `invalid`.
+- `aria-required` — `boolean`. Announced on the trigger. A `Field` sets it from `required`.
 - `children` (required) — `ReactNode`. `SelectItem`s, optionally wrapped in `SelectGroup` with a `SelectLabel`.
 
 Also accepts: `ComponentProps<typeof SelectPrimitive.Root>`.

package/dist/agent/Separator.md

@@ -1,29 +1,52 @@
 # Separator
 
-A rule, in the three weights a monochrome page needs.
+A rule, in the three weights a monochrome page needs — with words in it when the break has something to say.
 
 - Group: Display
 - Import: `import { Separator } from '@misoto22/design'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/separator/
 
 ## When to reach for it
 
-Hairline between rows, edge between blocks, hard under a masthead.
+Hairline between rows, edge between blocks, hard under a masthead. label puts words in the break: "or continue with", "Older".
+
+## Anatomy
+
+- **Rule** (required) — One <div>. A pixel on its cross axis and 100% on its main axis, so it takes the width — or the height — of whatever contains it, and nothing else.
+- **Ink** (required) — The only thing weight changes: --rule inside a block, --rule-2 between blocks, --rule-hard under a masthead. The hard one is not a darker grey, it is --ink itself.
+- **Label** — label, horizontal only. It changes the construction rather than the styling: the rule is drawn TWICE, one aria-hidden piece either side of the words in mono-meta at --ink-3-aa, and the gap between them is a gap.
+
+## Best practices
+
+### Do
+
+- Give a vertical separator a height. It is h-full, which against a parent with no height of its own resolves to zero — the element renders, occupies nothing, and reads as a component that failed to load.
+- Pass decorative={false} when the rule is the only thing dividing two sections a screen reader should hear as distinct: that is what swaps role="none" for role="separator" and sets aria-orientation with it.
+- Use label rather than building "or continue with" out of two Separators and a span. The two rules are drawn for you and neither of them needs to know the ground it is on.
+
+### Don’t
+
+- Do not pick the weight by eye. The three are ordered, so a hard rule between two table rows tells the reader the table ended there.
+- Do not hand-tune a fourth grey through className. Three named weights are the whole set, and the names exist because a monochrome page drifts into five slightly different rules the moment one of them is chosen by feel.
+- Do not lay the label over a single rule with a background colour to punch a hole in it. That version has to be told the ground it is sitting on, and a --paper notch on a --stone card reads as a rendering bug.
 
 ## Accessibility
 
 - role="none" by default. A rule that only groups things visually must not be announced.
+- With a label, the words are the content and the two rules are aria-hidden decoration — so decorative no longer applies, and nothing announces a separator over the top of the text.
+- A label on a vertical rule is ignored rather than silently redrawn as a horizontal bar: there is no sensible place for words inside a one-pixel column.
 
 ## Separator
 
-A rule. In a monochrome system the rule does the work colour would otherwise do, so it has three weights rather than one: hairline between rows, edge between blocks, hard under a masthead. Picking by name keeps a page from drifting into five hand-tuned greys.
+A rule, with or without words in it. In a monochrome system the rule does the work colour would otherwise do, so it has three weights rather than one: hairline between rows, edge between blocks, hard under a masthead. Picking by name keeps a page from drifting into five hand-tuned greys. **On the label.** "or continue with" was two Separators and a span at every call site, and the usual one-element version — text laid over a single rule with a background to punch a hole in it — needs to know the ground it is sitting on. Get that wrong and the notch is `--paper` on a card that is `--stone`, which reads as a rendering bug. So there is no ground: the rule is drawn twice, one piece either side of the label, and the gap is a gap. It is correct on any surface without being told which one it is on.
 
 ### Props
 
 - `orientation` — `'horizontal' | 'vertical'` default `'horizontal'`.
 - `weight` — `'hairline' | 'edge' | 'hard'` default `'hairline'`. `hairline` divides rows inside one block; `edge` divides one block from the next.
 - `decorative` — `boolean` default `true`. A rule that only groups things visually is decoration and must not be announced. Set `false` when the rule genuinely separates two sections a screen reader should hear as distinct.
+- `label` — `ReactNode`. Words in the break — "or continue with", "Older". Horizontal only, and it changes the construction rather than the styling: see the note on the component. `decorative` no longer applies, because the label is content and the two rules beside it are decoration either way.
 
 Also accepts: `HTMLAttributes<HTMLDivElement>`.
 
@@ -32,4 +55,5 @@ Also accepts: `HTMLAttributes<HTMLDivElement>`.
 ```tsx
 <Separator weight="hard" />
 <Separator orientation="vertical" className="h-4" />
+<Separator label="or continue with" />
 ```

package/dist/agent/SequenceFigure.md

@@ -0,0 +1,50 @@
+# SequenceFigure
+
+A call chain over time: who asks whom, in what order, and what comes back.
+
+- Group: Diagrams
+- Import: `import { SequenceFigure } from '@misoto22/design/diagrams'`
+- Version: 0.8.0
+- Docs: https://ui.misoto22.com/components/sequence-figure/
+- Related: workflow-figure, architecture-figure
+
+## When to reach for it
+
+The only figure whose vertical axis means something. A message carries an explicit y, so two calls eight units apart happened together and two two hundred apart did not.
+
+## Anatomy
+
+- **Figure shell** (required) — The frame around the picture. What a trace hands it is a message list, and it is published in the order the messages array is written — which is the only ordering a reader who cannot see the axis is given.
+- **Participant head** (required) — A 148-unit plate per participant at the top of its column, in the order the participants array puts them. meta.column_fit: "spread" widens every column to the widest name instead of holding the fixed width.
+- **Lifeline** (required) — A hairline dropped from each head to below the last thing on the axis. A hairline and not a rule, because it is the axis: seven lifelines at message weight is seven vertical lines competing with twelve horizontal ones.
+- **Message** (required) — A horizontal line at its own y, inset from both lifelines so the arrowhead lands clear of the axis, with the wording on a mask above it. A return is dashed AND takes an open head — two signals, because the reply is what a reader picks out of a dense trace.
+- **Activation bar** — A narrow bar on a lifeline from one y to another: who is BUSY. It is the fact a sequence diagram carries that a list of calls does not, and one bar overlapping another is the reason to draw the picture at all.
+- **Segment band** — A dashed rule across the whole figure with a mono caption on a masked patch — request, fallback, response. A caption rather than a tinted panel, because a second ground inside the figure would sit under every message label’s mask.
+
+## Best practices
+
+### Do
+
+- Author the messages in ascending y. The picture reads the axis and the summary list beside it iterates the array, so a message written out of order is drawn at one point in the exchange and read aloud at another.
+- Reach for meta.column_fit: "spread" when a participant’s name is longer than the fixed column. The plate wraps to two lines and ellipsises whatever still does not fit, and shortening the name to make it fit is not a repair — the name is the data.
+- Space the messages by what actually happened. Nothing normalises y, so eight units between two calls reads as together and two hundred reads as a wait; an evenly spaced list is tidier and says something the trace does not.
+
+### Don’t
+
+- A message naming a participant that participants does not declare leaves the picture and the summary list together — there is no column to draw it between, and a text equivalent reporting a call the picture cannot show is two halves of one figure disagreeing. Development prints DIAGRAM_EDGE_DANGLING with both ends, which is now the only place that message is reported at all.
+- This figure ASSERTS order. Three calls a service makes concurrently, given three y values because they had to be given something, are a picture claiming the second waited for the first — an activation bar or a segment caption is where "these overlap" belongs.
+
+## Accessibility
+
+- Return messages are dashed AND take an open arrowhead — two signals, because the reply is what a reader most often needs to pick out of a dense trace.
+- The message list beside the picture reads in order, which is the same order the axis is drawn in.
+
+## SequenceFigure
+
+A call chain over time: who asks whom, in what order, and what comes back. The one diagram type here whose vertical axis MEANS something. Every other figure's y is layout; a sequence's y is time, which is why a message carries an explicit `y` rather than an index — two calls 8 units apart happened together, and two 200 apart did not, and an evenly spaced list of messages would erase that distinction while looking tidier. **Lifelines** are hairlines, not solid rules, because they are the axis rather than the content. A lifeline drawn at the weight of a message is a diagram where seven vertical lines compete with twelve horizontal ones. **Activation bars** say who is BUSY, which is the fact a sequence diagram carries that a list of calls does not — the third participant's bar overlapping the second's is the reason to draw them at all. **Segments** band the axis into phases — request, fallback, response — printed as a rule with a mono caption rather than as a tinted panel, for the same reason architecture boundaries are: a second ground inside the figure would sit under every message label's mask. A `return` message is dashed AND takes an open arrowhead. Two signals rather than one, because the reply is the thing a reader most often needs to pick out of a dense trace, and a dash alone is doing the same work as `dashed` already does for an asynchronous call.
+
+### Props
+
+- `spec` (required) — `SequenceSpec`.
+
+Also accepts: `FigureChrome`.