@misoto22/design 0.7.0 → 0.8.0

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.7.0
+- 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.7.0
+- 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.7.0
+- 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.7.0
+- 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.7.0
+- 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.7.0
+- 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.7.0
+- 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

@@ -4,7 +4,7 @@ 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.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/sequence-figure/
 - Related: workflow-figure, architecture-figure
 
@@ -12,6 +12,28 @@ A call chain over time: who asks whom, in what order, and what comes back.
 
 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.

package/dist/agent/Sheet.md

@@ -4,7 +4,7 @@ A panel docked to an edge of the viewport.
 
 - Group: Overlays
 - Import: `import { Sheet } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/sheet/
 - Related: dialog, popover
 
@@ -12,6 +12,29 @@ A panel docked to an edge of the viewport.
 
 A modal that needs room — a filter panel, a detail view. It IS a Dialog, docked; the sides are named in reading order, so `end` is the right in English and the left in Arabic.
 
+## Anatomy
+
+- **Scrim** (required) — The same --scrim at --z-overlay that Dialog uses — the same component, in fact, so the page behind is inert and scroll-locked exactly as it is under a dialog.
+- **Panel** (required) — The docked box. start and end are a min(24rem, 92vw) column at full height; top and bottom are a full-width band capped at 85vh. A flex column that scrolls itself.
+- **Title** (required) — title, typed as required rather than optional — there is no unnamed-sheet path to fall into, only a hidden-title one via hideTitle.
+- **Description** — description, under the title, sharing the wrapper that hideTitle hides.
+- **Close** (required) — The X in the top-end corner. Unlike Dialog there is no showClose to turn it off, so every sheet has one whichever edge it is docked to.
+
+## Best practices
+
+### Do
+
+- Reach for a Sheet over a Dialog when the content is a list or a form long enough to scroll: it gets the full height of the viewport rather than Dialog’s 32rem by 85vh box, and the reader keeps the page edge as an anchor.
+- Use top or bottom when the content is wide and short — a filter bar, a date range. start and end are a 24rem column, and a table pushed into one wraps into a ribbon.
+- Name the sides start and end rather than reaching for left and right: each edge has its own literal class string carrying its own rtl: variant, so end arrives from the right in English and the left in Arabic with no second code path.
+- Wrap the cancelling control in SheetClose so the close runs through Radix — a sheet closed by your own state setter leaves focus inside a panel that is no longer on the page.
+
+### Don’t
+
+- Do not re-declare the travel in className. The panel carries data-m22-animated, which removes its transform outright under reduced motion; a second transform of your own only gets the universal floor, so it still arrives — a hundredth of a millisecond later, from wherever you put it.
+- An OverlayContainer whose element is not positioned docks the sheet to the wrong box: naming a container switches the panel from fixed to absolute, so an unpositioned container sends it to the nearest positioned ancestor rather than to the frame.
+- It is a modal dialog, so the page behind is scroll-locked and pointer-inert: this is not the home for a filter panel the reader is meant to work alongside. That is a Popover, or a column in the layout.
+
 ## Accessibility
 
 - Shares Dialog’s focus trap, Escape handling and scroll lock rather than reproducing them — a second focus trap is a second one to get wrong.
@@ -32,7 +55,7 @@ Radix Dialog root, trigger and close — a sheet IS a dialog, docked.
 
 ## SheetContent
 
-A panel docked to an edge of the viewport. It is a modal dialog — Radix's, so the focus trap, the escape key, the scroll lock and the `aria-modal` wiring are the same ones `Dialog` gets. The only differences are where it sits and which way it arrives, which is why this shares that implementation rather than reproducing it: a second focus trap is a second focus trap to get wrong. The title is required, visible or not. A modal with no accessible name drops a screen reader into an unnamed region with no way back out.
+A panel docked to an edge of the viewport. It is a modal dialog — Radix's, so the focus trap, the escape key, the scroll lock and the `aria-modal` wiring are the same ones `Dialog` gets. The only differences are where it sits and which way it arrives, which is why this shares that implementation rather than reproducing it: a second focus trap is a second focus trap to get wrong. The title is required, visible or not. A modal with no accessible name drops a screen reader into an unnamed region with no way back out. Portals into the element an enclosing `OverlayContainer` names, docking to that element's edge rather than the viewport's when there is one.
 
 ### Props
 

package/dist/agent/Skeleton.md

@@ -4,7 +4,7 @@ The shape of the page, before the page.
 
 - Group: Feedback
 - Import: `import { Skeleton } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/skeleton/
 - Related: spinner, empty-state
 
@@ -12,6 +12,28 @@ The shape of the page, before the page.
 
 A wait the reader would otherwise think was a broken page. A shape that describes what is coming beats a dot that describes nothing.
 
+## Anatomy
+
+- **Frame** (required) — SkeletonPage: the div carrying role="status", aria-busy="true" and the single pulse. It is the only part that speaks and the only part that moves — the shapes inside it do neither.
+- **Label** (required) — The sr-only sentence inside the frame, from the required label prop. Every shape is aria-hidden, so this one sentence is the entire loading state for a screen reader.
+- **Fill** — Skeleton itself: a --stone rectangle one line tall — h-3 — and, being a div, already full width. Height is the one dimension the element does not have on its own, so that is the one the base supplies; anything in className replaces it.
+- **Line, Block and Circle** — The three presets over that fill. SkeletonLine is a 12px pill and takes its width from the caller, SkeletonBlock only sets --radius-sm, and SkeletonCircle is a fixed 36px round.
+- **Paragraph** — SkeletonText: three lines by default, the last at 62% so it ends mid-measure the way prose does rather than squaring off into a table.
+
+## Best practices
+
+### Do
+
+- Wrap the shapes in SkeletonPage even when there is only one bar. The role, the aria-busy and the pulse all live on the frame, so parts used loose are aria-hidden, silent and completely still — a grey rectangle that never resolves.
+- Give every Skeleton the height of the thing it stands in for. The base falls back to one line, so a block left unsized is no longer invisible — it is a 12px bar where a 160px plate is about to land, and the page jumps by the difference.
+- Make whatever replaces the skeleton announce itself or take focus. aria-busy never flips to false here — the frame is unmounted, not updated — so the end of the wait is the disappearance of the only thing that was speaking.
+
+### Don’t
+
+- Do not add animate-pulse to a part. The frame already animates opacity and a second ramp on a child multiplies with it, so the part beats at a rate the shape around it does not. Reduced motion is not the reason it is wrong: the rule in keyframes.css is a universal floor on animation-duration and transition-duration, so a hand-written Tailwind animation is clamped along with everything else. data-m22-animated is a component asserting its motion is decorative, not the mechanism that does the cancelling.
+- Do not nest one SkeletonPage inside another. Each is a role="status" region with its own sr-only sentence, so a page assembled from two skeleton sections announces two loading messages and marks two regions busy for a single wait.
+- Do not carry a skeleton between screens unedited. SkeletonCircle is 36px and SkeletonLine is 12px tall whatever they stand in for, so a copied avatar mount and a copied heading are two guaranteed reflows the moment the real content lands.
+
 ## Accessibility
 
 - One live region on the wrapper; every shape inside it is aria-hidden.
@@ -19,7 +41,7 @@ A wait the reader would otherwise think was a broken page. A shape that describe
 
 ## Skeleton
 
-The fill every skeleton part is drawn from: `--stone`, and nothing else. Deliberately NOT a shimmer. A shimmer sweeps a highlight across the shape, which implies a light source; the White Reset has none, so the sweep reads as a bug rather than as loading. The whole page breathes together instead — see `SkeletonPage`, which owns the single pulse.
+The fill every skeleton part is drawn from: `--stone`, at the height of one line until something says otherwise. Deliberately NOT a shimmer. A shimmer sweeps a highlight across the shape, which implies a light source; the White Reset has none, so the sweep reads as a bug rather than as loading. The whole page breathes together instead — see `SkeletonPage`, which owns the single pulse. `h-3` is a default rather than a design. A `<div>` is already full width, so height was the one dimension a caller could omit and get nothing for — a bare `<Skeleton />` was a zero-height box, which is not a small skeleton but an absent one. Twelve pixels is the height `SkeletonLine` already chose, and any class the caller passes replaces it.
 
 Also accepts: `HTMLAttributes<HTMLDivElement>`.
 

package/dist/agent/Slider.md

@@ -4,14 +4,37 @@ A value chosen along a range.
 
 - Group: Forms
 - Import: `import { Slider } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/slider/
 - Related: progress
 
+## Anatomy
+
+- **Track** (required) — A 1px rule in --stone that thickens to 1.5 when the pointer is anywhere over the control, not only over the thumb.
+- **Range** — The --accent fill from the minimum to the thumb, or between the two thumbs of a range.
+- **Thumb** — One per entry in the value array — so the number of thumbs comes from the value, not from a prop, and a slider given neither value nor defaultValue falls back to the primitive’s own default of one thumb at the minimum. Each is a 16px circle with an invisible 44px hit area from a before pseudo-element.
+- **Value readout** — Only with showValue: a mono row above the track, the names on the start edge and the formatted values on the end, each joined by an en dash and in the thumbs’ own order — so a two-ended range reads “Minimum – Maximum” over “10 – 90”.
+
+## Best practices
+
+### Do
+
+- Pass defaultValue or value whenever there is more than one end to it. The thumb count comes from that array, so a price filter left to the default is a single thumb sitting at the minimum.
+- Pass an array of two names for a two-thumb range: every thumb after the first falls back to names[0], so both ends of a price filter otherwise announce themselves as “Minimum”.
+- Put an Input beside it when the exact number matters. A slider cannot be typed into, and someone who needs 37 rather than roughly 40 is dragging a 16px thumb across a hundred steps to get it.
+
+### Don’t
+
+- format becomes each thumb’s aria-valuetext, which REPLACES the number rather than decorating it — so a formatter that rounds hard or drops the unit is what a screen reader gets instead of the value.
+- Do not disable a slider to make it read-only: the whole control dims and stops taking the pointer, and Radix drops the thumb out of the tab order, so the value becomes unreachable rather than uneditable.
+- Do not pass two names to a one-thumb slider: the heading prints one name per THUMB, so the second is drawn nowhere and announced nowhere.
+- A Field’s label above it does not name it and does not click through: the role is on the THUMB and the root is a <span>, so the label prop here is the only name a reader hears. The hint and the error do reach the thumb.
+
 ## Accessibility
 
 - label is required. A thumb that announces "42" and nothing else leaves a screen reader user with a number and no idea what it measures.
 - A 44px hit area sits invisibly around the 16px thumb.
+- format is announced as aria-valuetext, so a thumb showing “$1,200” says that rather than 1200.
 - Arrows step, Page keys jump, Home and End reach the ends.
 
 ## Keyboard
@@ -22,13 +45,13 @@ A value chosen along a range.
 
 ## Slider
 
-A value chosen along a range. Radix owns the keyboard contract — arrows step, Page keys jump, Home and End reach the ends — and the ARIA that reports the value. What is here is the look, and the labelling, which is the part a slider most often gets wrong: a thumb that announces "42" and nothing else leaves a screen reader user with a number and no idea what it measures. A 44px hit area sits invisibly around the 16px thumb, because a thumb sized for the design is well under any pointer-target guideline.
+A value chosen along a range. Radix owns the keyboard contract — arrows step, Page keys jump, Home and End reach the ends — and the ARIA that reports the value. What is here is the look, and the labelling, which is the part a slider most often gets wrong: a thumb that announces "42" and nothing else leaves a screen reader user with a number and no idea what it measures. A 44px hit area sits invisibly around the 16px thumb, because a thumb sized for the design is well under any pointer-target guideline. Inside a `Field`, the hint, the error and the requirement land on the THUMB, which is the element carrying `role="slider"` — on the root they would sit on a `<span>` with no role and announce nothing. The NAME still comes from `label` here: a field's label above a slider points at that same roleless root, so it neither names the control nor clicks through to it.
 
 ### Props
 
 - `label` (required) — `string | [string, string]`. Names the control. Required: a slider with no name announces only a number, and a number with no noun is not information. A range slider (two thumbs) needs one name per thumb — pass an array.
-- `showValue` — `boolean` default `false`. Prints the current value beside the label.
-- `format` — `(value: number) => string` default `String`. Renders the value with a unit or a currency, e.g. `(n) => n + '%'`.
+- `showValue` — `boolean` default `false`. Prints the current value beside the label. A two-thumb range prints both names and both values, in the same order — the heading used to print the first name over a pair of numbers, which read as "Minimum" over "10 – 90".
+- `format` — `(value: number) => string`. Renders the value with a unit or a currency, e.g. `(n) => n + '%'`. Reaches assistive tech as well as the readout: it becomes each thumb's `aria-valuetext`, so a thumb showing "$1,200" announces that rather than the bare number. Left off, the platform announces the value itself.
 
 Also accepts: `ComponentProps<typeof SliderPrimitive.Root>`.
 

package/dist/agent/Sparkline.md

@@ -4,7 +4,7 @@ A run of numbers at the size of a word.
 
 - Group: Data
 - Import: `import { Sparkline } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/sparkline/
 - Related: line-chart, table
 
@@ -12,6 +12,28 @@ A run of numbers at the size of a word.
 
 In a table cell, beside a figure, at the end of a row. When the trend needs reading precisely it wants a LineChart and its own space.
 
+## Anatomy
+
+- **Inline row** (required) — An inline-flex span, full width with 8px of gap, so the run sits in a table cell or beside a figure without breaking the line it is on.
+- **Plot** (required) — One svg role="img" over a 0–100 by 0–100 viewBox with preserveAspectRatio="none", so it stretches to whatever width the container gives it. height, 28px by default, is the only fixed dimension.
+- **Mark** (required) — The path, its area fill, or the bars — variant picks one. The stroke is drawn with non-scaling-stroke, which is what keeps the line the same weight in a narrow cell and a wide one after the box has been stretched to fit.
+- **Last point** — A 2px dot on the final reading, from showLast, on the line and area variants. The bars variant carries the end of the run in its own last bar and draws no dot.
+- **Printed value** — value, in mono tabular figures after the plot. It is also what the accessible name says after the label, and it is the only figure this component ever prints.
+- **Too-short state** — What renders in place of the whole plot when fewer than two finite numbers survive: the label and “not enough data”, as one line of mono meta text.
+
+## Best practices
+
+### Do
+
+- Pass value whenever a figure matters. The plot has no axis and no scale, so it carries shape and nothing else, and value is both the one number printed and the reading appended to the accessible name. Left out, that name falls back to the last point through toLocaleString — the raw number, without the unit, the currency or the rounding the row beside it uses.
+- Pin domain across any two that will be read against each other. Each run is normalised into the same fixed box from its OWN min and max, so the highest point always touches the top edge and the lowest always the floor: a series moving between 4 and 6 and a series moving between 400 and 900 draw the same silhouette, and the difference between them is drawn nowhere.
+- Downsample a long run before handing it over. The x step is 100 divided by one less than the number of points, spread across whatever width the cell has, so four hundred readings in a 200px cell land half a pixel apart and the path fills in as a band.
+- Read a flat line through the middle as “unchanged”, not as “at its floor”. A run whose min equals its max has a scale with no width, so no position on it is truer than another and every point sits at the centre — the same answer Heatmap and BulletChart give a zero span, and the one that keeps “unchanged” and “pinned at its worst” apart in a column of them.
+
+### Don’t
+
+- Do not assume something chart-shaped always renders. Non-finite entries are filtered out first, and anything left under two points returns a line of text instead of an SVG, so the new account’s row is a sentence where every other row in the column is a chart.
+
 ## Accessibility
 
 - label is required and is the whole accessible name: a sparkline has no axes and no legend, so nothing else describes it.