@misoto22/design 0.7.0 → 0.9.0

package/dist/agent/AspectRatio.md

@@ -0,0 +1,57 @@
+# AspectRatio
+
+A box that keeps its shape whatever is inside it.
+
+- Group: Surfaces
+- Import: `import { AspectRatio } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/aspect-ratio/
+- Related: skeleton, card
+
+## When to reach for it
+
+The height has to be known before the content loads — a media grid that would otherwise reflow every time an image arrives.
+
+## Anatomy
+
+- **Box** (required) — A relative, full-width <div> carrying aspect-ratio as an inline style. A style and not a class because Tailwind can only generate what it reads verbatim in the source, and this value arrives at runtime.
+- **Children** (required) — Every DIRECT child, taken out of flow and stretched to fill the box. That is what guarantees the ratio holds: nothing inside can contribute a height, so content with no intrinsic size of its own still gets the whole box.
+- **Crop** — object-cover on a direct <img> or <video>, so media fills the box rather than being letterboxed inside it. Content that must not be cropped sets object-contain on itself.
+
+## Best practices
+
+### Do
+
+- Reach for it wherever a reflow would otherwise happen when an image lands. That reflow is the layout shift a Core Web Vitals score measures, and reserving the box is the whole fix.
+- Set object-contain on the child when the whole picture matters — a logo, a diagram, a screenshot. The default crops, which is right for a photograph and wrong for anything with an edge that means something.
+- Give it a width. It is w-full, so inside a container with no width of its own it has no height either, and a box with a ratio and no size is a box that is not there.
+
+### Don’t
+
+- Do not fall back to the padding-top percentage trick beside it. That percentage resolves against the WIDTH, which is why it works at all and also why it breaks as a flex child and eats the element’s own padding.
+- Do not put text in it and expect the box to grow. Every child is absolutely positioned, so a paragraph longer than the box is clipped by overflow-hidden rather than pushing it open.
+
+## Accessibility
+
+- A plain box with no role: it constrains geometry and says nothing, so an <img> inside keeps its own alt and nothing is added to the accessible tree.
+- Reserving the height before the content arrives is what stops the content under it moving out from under a pointer or a reader mid-tap.
+
+## AspectRatio
+
+A box that keeps its shape whatever is inside it. The one layout primitive that is genuinely hard to hand-roll. The `padding- top: 56.25%` trick everyone reaches for is a percentage of the WIDTH, which is why it works at all and also why it silently breaks the moment the box is a flex or grid child — and it takes the element's own padding with it. The modern `aspect-ratio` property does the same job in one line, and only holds if nothing inside forces a height, which is what the absolute positioning below guarantees. So: the box declares the ratio, and every direct child is stretched to fill it and taken out of flow. That means a child with no intrinsic size at all — an empty `<div>`, a map that measures its container, a skeleton — still gets the full box, and an `<img>` or `<video>` is cropped to cover it rather than letterboxed. Content that must not be cropped should set `object-contain` on itself. Reach for this when the height must be known before the content loads: a media grid that would otherwise reflow every time an image arrives is the usual case, and that reflow is the layout shift a Core Web Vitals score is measuring.
+
+### Props
+
+- `ratio` — `number | string` default `16 / 9`. Width over height. A number (`16 / 9`) or the CSS form (`'16 / 9'`). It is a style rather than a class because Tailwind can only generate what it can read verbatim in the source, and this value arrives at runtime.
+- `children` — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Examples
+
+```tsx
+<AspectRatio ratio={16 / 9}><img src={cover} alt="" /></AspectRatio>
+<AspectRatio ratio="1 / 1" className="rounded-(--radius) border border-(--rule-2)">
+  <Skeleton />
+</AspectRatio>
+```

package/dist/agent/Avatar.md

@@ -4,22 +4,42 @@ A person, as a circle, with initials until the image lands.
 
 - Group: Display
 - Import: `import { Avatar } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/avatar/
 
+## Anatomy
+
+- **Circle** (required) — The Radix root: a --rule hairline over --stone, overflow hidden, and one of three fixed squares — 28px, 36px or 48px. It carries role="img" and alt as its own name, because it is the one element in here that is always rendered.
+- **Image** — Rendered only when src is given, object-cover so a portrait crops to the circle instead of distorting. Its own alt is empty on purpose — the circle around it is what names the person, and a second name here is the same person read twice.
+- **Initials** — The Radix fallback: mono, uppercase, --ink-3-aa, and aria-hidden. Radix shows it while the image is loading and once it has failed, which is why it does not flash on every render the way a hand-rolled onError swap does.
+
+## Best practices
+
+### Do
+
+- Write alt for the person, not for the row: the circle carries it whether or not a photograph ever arrives, so a list where photographs are optional announces every person rather than every second one.
+- Pass initials that hold up on their own: fallback is required because the image is the optional half, and most rows of a real list render as this element rather than as a photograph.
+- Let Radix own the swap rather than reaching for onError — it flips to the fallback only once the image has actually failed, which is what keeps the initials from appearing for a frame before the cache answers.
+
+### Don’t
+
+- The avatar is not the control. sm is 28px and md is 36px, both under the 44px pointer-target floor (WCAG 2.5.8), and the root is a <span> nothing has made focusable — an account menu made by hanging onClick on it is unreachable and undersized at once.
+- children is deliberately omitted from the props: the image and the fallback are the only two things that go in the circle, and the root is overflow-hidden, so a presence dot placed inside it is clipped by the very border that makes it round.
+
 ## Accessibility
 
-- alt describes the person, not the picture. An empty string is correct when the name is already printed beside it.
-- The initials are aria-hidden — read aloud they are noise.
+- alt names the circle itself, as role="img", so an avatar with no photograph still says who it is.
+- An empty alt is correct when the name is already printed beside it: the circle then takes no role at all rather than an unnamed one, and leaves the tree entirely.
+- The initials are aria-hidden — read aloud beside a name the root already gives, they are noise.
 
 ## Avatar
 
-A person, as a circle. Wraps Radix so the fallback appears only after the image has actually failed or is still loading — a hand-rolled `onError` swap flashes the initials on every render before the cache answers.
+A person, as a circle. Wraps Radix so the fallback appears only after the image has actually failed or is still loading — a hand-rolled `onError` swap flashes the initials on every render before the cache answers. The ROOT carries the accessible name, not the image. `alt` on the image reaches the DOM only when `src` does, and the initials are aria-hidden, so an avatar with no photograph announced nothing at all however carefully `alt` was written — and a user list where photographs are optional is full of them.
 
 ### Props
 
 - `src` — `string`.
-- `alt` (required) — `string`. Describes the person, not the picture. Empty string is correct and deliberate when the name is already printed beside the avatar — repeating it makes a screen reader say it twice.
+- `alt` (required) — `string`. Describes the person, not the picture. It names the circle itself rather than the image inside it, because the image is the optional half and most rows of a real list render as initials. Empty string is correct and deliberate when the name is already printed beside the avatar: the circle then leaves the accessibility tree entirely, rather than repeating a name a screen reader has just read.
 - `fallback` (required) — `string`. Shown while the image loads and if it never does. Usually initials.
 - `size` — `'sm' | 'md' | 'lg'` default `'md'`.
 

package/dist/agent/Badge.md

@@ -4,7 +4,7 @@ A count or a state, set in mono so it reads as metadata.
 
 - Group: Display
 - Import: `import { Badge } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/badge/
 - Related: tag, status-pill
 
@@ -12,6 +12,27 @@ A count or a state, set in mono so it reads as metadata.
 
 One fact about one record. If it names what something is ABOUT, that is a Tag.
 
+## Anatomy
+
+- **Chip** (required) — The <span>: inline-flex on the --radius-sm corner, mono at 12px with wide tracking. The mono face is the whole signal — it is what tells a reader this is metadata rather than a word of the sentence it sits in.
+- **Ground** (required) — The tone’s fill — --stone for neutral, the soft tint of --ok, --warn or --danger for the three status tones, and nothing at all for outline.
+- **Border** (required) — Always drawn, and transparent for every tone but outline, so the box reserves the pixel either way and swapping tone at runtime moves nothing beside it.
+- **Content** (required) — children, with a 6px gap between them — so a StatusDot or a Kbd set beside the text spaces itself without a wrapper.
+
+## Best practices
+
+### Do
+
+- Leave tone at neutral unless the badge names a STATE: the three status tones are the only chroma this system spends, and a badge that is red because the page wanted red is the thing the scale exists to prevent.
+- Reach for outline when the badge sits on --stone already — every other tone fills its own ground, and a neutral badge on stone is a chip with no visible edge at all.
+- Keep it to a count, a word, or a short state. It is 12px mono sized for one line, so a phrase in it is prose set in the metadata face and wraps inside a box that was never given a second line.
+
+### Don’t
+
+- A row of them is a Tag list drawn in the wrong component: Badge has no active state, so the filter bar it turns into cannot show which facet is on.
+- A neutral Badge and an inactive Tag are the same corner, the same padding and the same 12px mono, separated by one ink step — so a row that mixes states and topics reads as one undifferentiated run of chips.
+- There is no dismiss affordance here. A × written into children is text inside the accessible name, so the badge is announced as “beta ×” and the close it advertises does not exist.
+
 ## Accessibility
 
 - Not interactive. A badge with an onClick is a control a keyboard cannot reach.

package/dist/agent/BarChart.md

@@ -4,7 +4,7 @@ Discrete categories compared by length.
 
 - Group: Charts
 - Import: `import { BarChart } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/bar-chart/
 - Related: area-chart, composed-chart, radial-chart
 
@@ -12,6 +12,32 @@ Discrete categories compared by length.
 
 The categories are buckets rather than a continuum. If the axis is time and the reader is following a trend, an AreaChart or LineChart reads it faster.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, named by title whether or not the page prints a heading above it.
+- **Bars** (required) — <BarChart.Bar>, drawn through a custom shape: a transparent rectangle for the hit area, then the painted bar three pixels shorter than its slot so a stacked segment keeps a hairline of page between it and the one above. A bar shorter than that trim is floored at one pixel rather than taken to nothing, so a small count is never pixel-identical to an absent one.
+- **Axes** — <BarChart.XAxis> and <BarChart.YAxis>, both flat by default — no tick line, no axis line. Every Recharts prop passes straight through, domain included, which is the door a truncated baseline comes in through.
+- **Legend** — <BarChart.Legend>. With isClickable each entry is a real <button> carrying aria-pressed rather than a div with a handler, which is the difference between a filter a keyboard can reach and one it cannot.
+- **Value labels** — <BarChart.Values>, a slot composed inside a bar. show defaults to last; all is for five or six bars where the exact figures are the point, and past that it is a table wearing a chart.
+- **Hidden data table** — The sr-only table of the FULL data rather than of the brushed window, so a reader on the table is never shown less than the CSV export holds. hideDataTable removes it, and zero rows render nothing.
+- **Empty state** — ChartEmpty, rendered in place of the plot when data is empty — a title, a reason and an optional action, so a filter that matched nothing is told apart from a load that failed. empty={false} keeps the bare axes instead.
+
+## Best practices
+
+### Do
+
+- Reach for buffer on a period still open. It hatches the last ROW rather than the last bar on screen, so brushing back into the middle of the range hatches nothing — a month that closed in March is never drawn as still being counted.
+- Leave the value axis anchored at zero. A bar encodes by LENGTH from the baseline, so a domain of ["dataMin", "dataMax"] passed through <BarChart.YAxis> turns a two percent gap into a doubled bar. This is the distortion a bar chart cannot survive and a LineChart can: a line encodes by slope, so clipping its domain rescales the reading rather than inventing one.
+- Reach for orientation="horizontal" when the category names are long. The alternative is a tick label rotated under every column, and a rotated label is slower to read than the bar it names.
+- Pass a tickFormatter to <BarChart.YAxis> under stackType="percent". Unlike AreaChart’s expanded stack, which swaps in percentTick itself, the bar chart’s axis keeps defaultTick — so a normalised chart reads 0 to 1 instead of 0% to 100%.
+- Put the series that has to be compared across categories at the BASELINE of a stack. Only the bottom segment starts at zero; every band above it floats on the ones below, and reading a third band across twelve months is a comparison the eye cannot make. When that comparison is the point, group the bars instead.
+
+### Don’t
+
+- hideDataTable leaves no exact figure anywhere. defaultTick compacts at ten thousand and above, so the axis says 1.2M and so do the <BarChart.Values> labels; the sr-only table, where every cell is a full toLocaleString, was the only place the real number was written.
+- Twenty bars at variant="default" is a wall rather than twenty values. stripped draws a 2px cap over a wash and stays countable at that density, which is the density it exists for.
+- Do not close barCategoryGap up. The space between groups is the only thing telling a reader that two adjacent bars are two series rather than two categories, so a grouped chart with no category gap reads as a stacked one.
+
 ## Accessibility
 
 - title is required; the rows are also rendered as a visually hidden table.
@@ -39,7 +65,8 @@ Discrete categories compared by length — the shape for "how much, per thing".
 - `animationType` — `ChartRevealType` default `'forward'`. The grow-in order every `<BarChart.Bar>` inherits.
 - `barGap` — `number`. Gap between bars inside one category.
 - `barCategoryGap` — `number`. Gap between categories.
-- `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.
 - `loadingBars` — `number`. How many bars the skeleton draws.

package/dist/agent/BarList.md

@@ -4,7 +4,7 @@ A ranked list, with the bar behind the name rather than beside it.
 
 - Group: Data
 - Import: `import { BarList } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/bar-list/
 - Related: bar-chart, table
 
@@ -12,6 +12,31 @@ A ranked list, with the bar behind the name rather than beside it.
 
 Top referrers, slowest endpoints, biggest accounts. A horizontal BarChart spends a third of its width on an axis repeating labels the rows could simply contain.
 
+## Anatomy
+
+- **Caption** (required) — label, as the table’s real caption — sr-only unless showLabel prints it as an eyebrow above the rows. It is what names the list for a screen reader.
+- **Header row** (required) — An sr-only thead of two th scope="col" cells, Name and Value, so both columns are named even though the list never shows a header.
+- **Name cell** (required) — A th scope="row" holding the row’s name truncated to one line, with item.icon before it as aria-hidden decoration and item.href turning the name itself into the link.
+- **Bar** (required) — Not an element: a linear-gradient on the name cell’s inner span, a hard stop at the row’s share of the ceiling. Drawn as a sibling div it would be one more empty thing in the accessibility tree saying nothing.
+- **Value cell** (required) — A td at the end edge in mono tabular figures at --ink-2, written by formatValue — the same compact default the axes use unless the call site replaces it.
+- **Other row** — What limit adds: one final row named Other carrying the summed tail, so the rows shown still account for the whole they were cut from.
+- **Empty state** — ChartEmpty under the label when there is nothing to rank. A caption over an empty tbody is a list that failed to load as far as the reader can tell, and reloading does not change it.
+
+## Best practices
+
+### Do
+
+- Pin max when rows arrive over time. The ceiling is the largest row currently shown, so one new leader rescales every bar under it — a track that was two thirds full yesterday is a quarter full today with exactly the same number in it, and the movement the reader sees happened to a different row.
+- Reach for limit rather than slicing items at the call site. The tail is summed into the Other row instead of being dropped, so the five rows shown still add up to the whole; a top five cut by hand discards the other forty silently, and nothing in the list says so.
+- Keep names short enough to survive the truncation. The name is a single truncated line sharing its width with the value column, so two endpoints that differ only past the fortieth character render as the same row with the same ellipsis.
+- Pass sort={false} when the order is the point — a funnel, a set of steps, a fixed set of regions. sort defaults to true and orders descending, which turns a sequence into a ranking without saying that it did.
+
+### Don’t
+
+- The bar is the row over the largest row, never a share of a total: the leading row always fills its track, so five rows that make up 3 percent of traffic look exactly like five that make up all of it. Where the whole matters, the caption is where it goes.
+- Do not mix number shapes down the value column. It is end-aligned mono with tabular figures, which lines digits up only while the strings are the same shape — and the default formatter switches to the compact form at 10,000, so a list spanning that threshold puts 9,400 under 1.2M and there is nothing left to compare down.
+- Two rows cannot share a name. It is the row’s label and its React key at once, so a list built from a query that can repeat a label renders duplicate keys, which React warns about and reconciles wrongly the moment the list updates.
+
 ## Accessibility
 
 - A real <table> with two columns and one row per thing, because that is what a ranked list is. The bar is a background on the name cell, so it is never a second element a screen reader has to walk past.
@@ -32,6 +57,7 @@ A ranked list, with the bar behind the name rather than beside it. The answer to
 - `max` — `number`. The scale's ceiling. Derived from the largest row when omitted. Pin it to compare two lists side by side — on independent scales the leading row of each fills its track, and two very different numbers look identical.
 - `sort` — `boolean` default `true`. Sorts descending before rendering.
 - `className` — `string`.
+- `empty` — `ChartEmptyProps`. What the list shows when it has nothing to rank. A caption over an empty `<tbody>` is a list that failed to load as far as the reader can tell, and the reader's next move is to reload the page.
 
 ## Examples
 

package/dist/agent/BigNumber.md

@@ -4,7 +4,7 @@ One number, at the size of a headline.
 
 - Group: Data
 - Import: `import { BigNumber } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/big-number/
 - Related: sparkline, figure-band
 
@@ -12,6 +12,29 @@ One number, at the size of a headline.
 
 There is exactly one figure to report. A plot of a single value is a plot whose shape carries nothing, and the reader has to decode an axis to recover a number that could simply have been printed.
 
+## Anatomy
+
+- **Label** (required) — What the number counts, as an eyebrow at --ink-3-aa above it. Nothing binds it to the value programmatically — no aria-labelledby, no role — so document order is the whole association.
+- **Value** (required) — The number itself, in the editorial face at --fs-lead with tabular figures. Rendered exactly as handed over: no unit, currency or locale is guessed on its behalf.
+- **Delta** — The line under the number, from delta: the change through format — a signed percentage unless replaced — and delta.label at --ink-3-aa saying what it is a change from.
+- **Direction mark** — Inside the delta: an aria-hidden arrow, up, down or flat at zero, and the status tint, --ok or --danger, or --ink-2 while nothing has been judged. Two carriers, so the reading survives greyscale and forced colours.
+- **Verdict** — The sr-only words beside the arrow — up or down, then better or worse once intent has been set. It is what a screen reader gets in place of the tint.
+- **Note slot** — children, under the number with a margin: where a Sparkline, a denominator or a caveat goes.
+
+## Best practices
+
+### Do
+
+- Give the figure something to be judged against. On its own a number cannot be read — 48,210 is neither good nor bad until it is beside last month — and this component carries exactly two places for that: delta for one comparison, children for the Sparkline or the denominator under it.
+- Pass delta.value as a ratio. The default formatter multiplies by a hundred and prefixes the sign, so 0.124 prints as +12.4% and 12.4 prints as +1240%. A change already expressed in points needs its own format handed over with it.
+- Set intent on any delta meant to be coloured. It defaults to neutral, which renders the change at --ink-2 and says only which way it moved — correct for a figure nobody has judged, and rarely what the author of a revenue card thought they had written.
+- Let value be null when there is no reading. It prints an em dash at --ink-3-aa with an sr-only “No data” behind it, which is a number nobody has; a blank line under a label is a broken layout as far as the reader can tell. emptyValue changes what the dash is.
+
+### Don’t
+
+- Do not expect a delta of exactly zero to carry the intent’s verdict. There is no direction for an intent to judge, so the tone, the arrow and the announced words all say “no change” and stop — a zero under up-is-good used to be announced as “no change, worse” while the page showed no judgement at all.
+- Do not separate the label from the number. The value is text in a span rather than a labelled element, and the label is a sibling read before it, so a layout that moves the figure into its own column — or reuses one label over two figures — hands a screen reader a bare number with nothing naming it.
+
 ## Accessibility
 
 - The delta’s direction is stated by the call site through intent, never inferred from the sign: “errors down 12%” is good news and “revenue down 12%” is not, and no component can tell which it is holding.
@@ -25,7 +48,8 @@ One number, at the size of a headline. The form most dashboards need most often
 ### Props
 
 - `label` (required) — `ReactNode`. What the number counts.
-- `value` (required) — `ReactNode`. The number, already formatted — this component does not guess a unit.
+- `value` (required) — `ReactNode`. The number, already formatted — this component does not guess a unit. `null` and `undefined` are the empty state rather than a blank space: a headline with nothing under it reads as a figure that failed to load, and the reader's next move is to reload a page that will look the same.
+- `emptyValue` — `ReactNode` default `'—'`. What stands in for the number when there is none.
 - `delta` — `BigNumberDelta`.
 - `children` — `ReactNode`. A sparkline, a note, a caveat. Sits under the number.
 - `className` — `string`.

package/dist/agent/BoxPlot.md

@@ -4,7 +4,7 @@ The spread of a measurement, per category.
 
 - Group: Charts
 - Import: `import { BoxPlot } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/box-plot/
 - Related: histogram, scatter-chart
 
@@ -12,6 +12,29 @@ The spread of a measurement, per category.
 
 How variable is this, across six things at once. When the shape of ONE distribution is the question it wants a Histogram; when there are few enough observations to draw them all, a ScatterChart.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state when no category survives resolving. empty={false} keeps the axes for a chart whose emptiness is itself the reading.
+- **Boxes** (required) — <BoxPlot.Boxes>: one range bar per category spanning min to max, entirely unpainted, with the glyph drawn over it. Recharts supplies the category band and the scale; the box, the median rule, the whiskers and the outlier dots are the package’s own.
+- **Value axis** — <BoxPlot.YAxis>, and it is deliberately NOT anchored at zero — a box plot compares distributions, and dragging the domain to zero to be honest about bar length flattens every box into the same band of pixels. The honesty it owes is a labelled axis, which it has.
+- **Notch** — notch pinches the box in at the median by 1.58 times IQR over the square root of n — a confidence interval drawn inside the shape it belongs to. It needs count on every box; a box without one is drawn square and says nothing about it.
+- **Outlier dots** — showOutliers, on by default. Points past Tukey’s 1.5 IQR fences are drawn one dot each, and the whiskers then stop at the most extreme observation still INSIDE the fence rather than at the fence itself, so no whisker claims a reading the data does not contain.
+- **Hidden data table** (required) — The sr-only table carries all five numbers per category plus the outlier count, so the figure is fully readable without seeing the glyph.
+
+## Best practices
+
+### Do
+
+- Carry count on every box. A box over six observations and a box over six thousand are drawn identically, and count is also what a notch reads — without it, notch is accepted and quietly does nothing.
+- Say which quantile rule produced a pre-computed summary. This component uses R type 7 when it summarises raw values, and on [1, 2, 3, 4] that puts the lower quartile at 1.75 where the median-of-the-lower-half rule puts it at 1.5 — the same data under two rules is two different pictures.
+- Hand it the raw values rather than a summary when you have them. One pass applies Tukey’s fences, splits the outliers out and fills count in, so the five numbers and the dots cannot drift apart.
+
+### Don’t
+
+- A box cannot tell one hump from two. A latency series with a cache path and a database path in it draws exactly the box a smooth distribution centred in the same place draws, and the middle of that box is a value almost nothing takes. When the SHAPE is the question it is a Histogram.
+- A category whose values array is empty is dropped outright — no box, no tick, no table row — because summarising it yields nothing to draw. The chart renders six boxes where seven were asked for and says nothing about the seventh.
+- One observation draws a box with no box: q1, the median and q3 are the same number, the IQR is zero, and the glyph collapses to a single rule. It is not an error and it is not a distribution, so guard it at the call site.
+
 ## Accessibility
 
 - A box is five numbers, and five numbers cannot tell one hump from two. A bimodal distribution draws exactly the same box as a smooth one centred in the same place — the component says so in its own description rather than in a footnote.

package/dist/agent/Breadcrumb.md

@@ -4,18 +4,40 @@ Where you are, as a path.
 
 - Group: Navigation
 - Import: `import { Breadcrumb } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/breadcrumb/
 - Related: pagination
 
+## Anatomy
+
+- **Trail** (required) — A <nav> named by label, which defaults to “Breadcrumb”. It is a landmark whether or not the page wanted another one, set in mono-meta at --ink-3-aa.
+- **List** (required) — An <ol> — the order is the hierarchy, not the reader’s history. It wraps rather than truncating, so a deep path takes a second line instead of losing a level.
+- **Crumb link** — An <a> for every item that has an href and is not the last. The label is a ReactNode, so whatever you put in it becomes part of the link’s accessible name.
+- **Current crumb** (required) — The last item, always: plain text at full --ink with aria-current="page", whether or not it was given an href.
+- **Separator** — A slash by default, in its own <li aria-hidden> between crumbs. Decorative by construction — it is never part of what is read out.
+
+## Best practices
+
+### Do
+
+- Pass label when a page can hold two trails: both nav landmarks are named “Breadcrumb” otherwise, and two landmarks with one name are two entries a reader cannot choose between.
+- Give every crumb but the last an href — one without renders as plain text in the same colour as the links beside it, with no destination and no aria-current, so it reads as the page the reader is on when it is not. Development names the crumb rather than leaving an omission that is invisible in the browser and in review.
+- Start the trail above the current page: a one-item Breadcrumb renders that item as the current crumb with no path at all, which is a landmark announcing a journey of length one.
+
+### Don’t
+
+- Leave the href off the last item rather than passing one it ignores: the last crumb is text whatever you hand it, so an href there reads as a link in review and is not one at run time.
+- Do not hide it on a phone to save a line. That is the layout where the sidebar is behind a drawer, which makes the trail the only way up a level that is on the screen.
+
 ## Accessibility
 
 - The last crumb is text with aria-current="page", never a link to itself.
 - Separators are aria-hidden, so the trail is not read as “home slash work slash”.
+- A middle crumb with no href takes no aria-current and no colour of its own, which is why the omission is reported in development instead of shipped as a crumb that impersonates the current page.
 
 ## Breadcrumb
 
-Where you are, as a path. The last crumb is plain text with `aria-current="page"` rather than a link to itself — a self-link is the most common breadcrumb bug, and it makes a screen reader offer a navigation that goes nowhere. Separators live in `<li aria-hidden>` so the trail is read as its items and not as "home slash work slash".
+Where you are, as a path. The last crumb is plain text with `aria-current="page"` rather than a link to itself — a self-link is the most common breadcrumb bug, and it makes a screen reader offer a navigation that goes nowhere. Separators live in `<li aria-hidden>` so the trail is read as its items and not as "home slash work slash". A middle crumb with no `href` is a defect that is invisible twice over: it renders as plain text in the same `--ink-3-aa` as the links beside it, and it carries no `aria-current` either — so it reads as the page the reader is on when it is not, and neither the browser nor a review says a word. The console does, in development.
 
 ### Props
 

package/dist/agent/BulletChart.md

@@ -4,7 +4,7 @@ A measure, its target, and the bands that say whether it is any good.
 
 - Group: Data
 - Import: `import { BulletChart } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/bullet-chart/
 - Related: bar-list, big-number
 
@@ -12,6 +12,28 @@ A measure, its target, and the bands that say whether it is any good.
 
 A status page of ten tracked numbers. Stephen Few designed it to replace the dashboard gauge, which spends a whole card saying one number badly.
 
+## Anatomy
+
+- **Figure caption** (required) — title on the shared chart figure, referenced by aria-labelledby rather than left to be inferred from the figcaption, and hidden from sight unless showTitle prints it with description beneath.
+- **Measure line** (required) — The row above each track: the measure’s name with its optional detail at the start, the formatted value at the end, and the target after a slash where there is one. This line is the reading a screen reader gets, because the graphic under it is not in the accessibility tree at all.
+- **Track** (required) — The 24px aria-hidden box holding the bands, the bar and the target rule, laid out with inline-axis offsets rather than in SVG user space — which is what makes the whole chart mirror correctly in a right-to-left document.
+- **Bands** — The qualitative ground, built from ranges as ascending upper bounds: heaviest at the low end of the scale and lightening as it rises, so the solid bar stands out most where performance is best.
+- **Measure bar** (required) — The value, solid --series-1 at a third of the track’s height, running from the start of the scale. The one mark here that is a measurement rather than a judgement, and the only one drawn at full weight.
+- **Target rule** — target, as a 2px rule of --ink straight across the bar rather than a second bar beside it — so which number was achieved and which was asked for is a glance rather than a comparison.
+
+## Best practices
+
+### Do
+
+- Keep every range bound inside the domain. Bounds at or outside the two ends have no boundary to draw and are dropped before the bands are built, so ranges of 60 and 80 on a domain of 0 to 50 draws one flat band — the row LOOKS evaluated and is not. They stay in the table’s range-bounds cell, which is the only place the mismatch is visible.
+- Hold to five bands. The weights are spread evenly from the full --chart-fill down to three tenths of it across however many bands are passed, so a sixth and a seventh boundary only slice that same span thinner and the ground stops having edges a reader can read a threshold off.
+- Leave hideDataTable off unless the page prints the measures itself. The whole graphic is aria-hidden — bands, bar and target alike — so the generated sr-only table of value, target and range bounds is the only account of the chart a screen reader ever reaches.
+
+### Don’t
+
+- A value past the end of the scale is clamped, not overflowed: 130 on a domain of 0 to 100 fills the track exactly as 100 does. A notch at the end of the track says it happened and the figure printed above says by how much — but the track itself cannot, so pin domain wide enough for the overshoot you expect rather than reading the row that blew through its target as one that merely finished.
+- Do not put a range bound on the target. Both are placed by the same scale, so the rule lands exactly on a band edge and the one mark that says what was ASKED for disappears into the ground it was meant to be read against.
+
 ## Accessibility
 
 - Plain HTML with logical properties — no rendering engine, server-renderable, and correct in a right-to-left document. Usable with recharts absent.

package/dist/agent/Button.md

@@ -4,7 +4,7 @@ The system’s action, on the same corner as the field beside it.
 
 - Group: Actions
 - Import: `import { Button } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/button/
 - Related: floating-icon-button, spinner
 
@@ -12,6 +12,30 @@ The system’s action, on the same corner as the field beside it.
 
 Anything that DOES something. If it navigates and looks like text, it is a link, not a ghost button.
 
+## Anatomy
+
+- **Control box** (required) — The <button>, the <a> it becomes when given href, or whatever asChild slots in. It carries the variant, the size, and the same --radius corner as the field beside it.
+- **Label** — children, and the accessible name of a text button. It stays put while loading, so the width does not move under the pointer.
+- **Icon** — The same children slot on an iconOnly button: the box goes square, the padding to zero, and nothing text-shaped is left behind for a screen reader.
+- **Keycap** — keycap, after the label — a mono glyph in a bordered box at reduced opacity. Real text, not decoration hidden from assistive tech.
+- **Spinner** — loading, before the label — a Spinner toned to the ground it sits on and passed label={null}, so it is aria-hidden and aria-busy on the control carries the state instead.
+
+## Best practices
+
+### Do
+
+- Spell out type="submit" on a form’s submit control: the default here is type="button", so the button at the foot of a form looks right and submits nothing.
+- Keep one primary to a view. variant defaults to primary, so a row written without the prop is a row in which every button claims to be the one thing the screen wants.
+- Reach for loading rather than swapping the label by hand: it holds the label, sets aria-busy and disables the control in one move, so the box does not collapse under the pointer that just clicked it.
+- Use href when it navigates and asChild when a router owns the navigation — a <button> whose onClick calls router.push cannot be opened in a new tab, and is announced as a button that goes nowhere.
+
+### Don’t
+
+- asChild passes the styling to the child and nothing else: keycap and loading never reach it, so a loading state written that way shows no spinner and blocks no clicks.
+- sm is 36px at the default density, under the 44px md clears on its own — a toolbar built out of sm is a row of targets a thumb misses (WCAG 2.5.5).
+- danger is a state, not emphasis. Spent on the merely important action, nothing is left that reads as destructive when one actually is.
+- The keycap is not hidden from assistive tech, so the glyph joins the accessible name — the control is read out as “Save S”, and a keycap for a shortcut nothing binds announces a promise the page never keeps.
+
 ## Accessibility
 
 - A native <button> by default, so Enter and Space both fire it.

package/dist/agent/Calendar.md

@@ -4,7 +4,7 @@ A month, as a grid of days.
 
 - Group: Surfaces
 - Import: `import { Calendar } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/calendar/
 - Related: date-picker
 
@@ -12,11 +12,36 @@ A month, as a grid of days.
 
 On its own for a range view or an availability grid; inside a DatePicker for choosing one.
 
+## Anatomy
+
+- **Day grid** (required) — The month: a mono weekday row over one 36px pill-cornered button per day, five rows in most months and six in some. Days from the neighbouring months are shown and dimmed rather than left as holes.
+- **Caption** (required) — “September 2026” as ONE button carrying aria-expanded, not two dropdowns — that is how the date is said, and splitting it put four controls in a 250px row that also has to hold two arrows.
+- **Month arrows** (required) — The library’s nav, lifted out of the flow and laid across the caption at the same 36px height so the two sit at either end of the month name. Both step away while the picker is open: two ways to change the month, one of them behind a panel, is one too many.
+- **Month and year picker** — A role="dialog" drawn IN PLACE of the day grid rather than over it — twelve months in a 3×4 and up to twenty-four years in a 4×6, at exactly the size of the grid they replace. Focus moves in when it opens and Tab wraps inside it; Escape closes it and puts focus back on the caption.
+- **Day marks** (required) — Today is a ring and selected is a fill. In a range the wash lives on the CELL and the fill on the ends’ BUTTONS, which is what lets a range read as one band with round ends — and lets a one-day range, which is both ends at once, stay round.
+
+## Best practices
+
+### Do
+
+- Pass locale rather than trusting the page’s lang: the caption is formatted by Intl from locale.code and falls back to en-US, so a French calendar says “September” until the prop is set.
+- Re-add the library’s own class when you override a slot through classNames — yours REPLACES ours, and ours carries the .rdp-* hook every downstream selector depends on. Overriding root without rdp-root took that hook off the tree.
+- Mark availability through the classNames slots rather than by styling the day button: the wash belongs to the cell and the mark to the button, and a background put on the button flattens the round end of a range.
+- Know what widening the span costs: the year grid pages 24 at a time, so the default ten either side is one page and no paging, and a range wide enough for a birth date is a reader stepping through pages to reach 1974.
+- Translate the picker’s chrome alongside locale. locale reaches the month names and stops there, so a French calendar with the prop set still names its two panels and its four chevrons “Month and year”, “Previous year” and “Earlier years” until the CalendarLabels props are passed.
+
+### Don’t
+
+- Do not stretch it with a width class: it is w-fit and lays out fixed 36px columns, so w-full only replaces w-fit and leaves the same grid sitting at the start edge of a wider box.
+- Do not cut it to a fixed height. The grid is five weeks in most months and six in some, and the picker panel is sized against the grid rather than given a height of its own — a box measured on a five-week month clips the sixth.
+- Do not replace MonthCaption through components: the month-and-year picker lives inside ours, so a custom caption leaves the reader with two arrows and no way to move more than one month at a time.
+
 ## Accessibility
 
 - Arrows move a day, Page keys move a month, Home and End reach the week’s ends.
 - “Today” is an outline and “selected” is a fill — one is a fact about the calendar, the other a choice the reader made, and they must not look alike.
-- Month and year are the system’s own Select, not the platform’s: a native list of a hundred years is a scroll rather than a choice, and it arrives styled by the operating system.
+- Month and year are one panel of buttons, not a native select: a platform list of a hundred years is a scroll rather than a choice, and it arrives styled by the operating system.
+- Tab wraps inside the open panel. It is opaque and the day grid is still mounted under it, so a Tab that left would put the reader on a day they cannot see — and past the caption that owns the Escape handler.
 - The default span is ten years either side. A birth date needs a wider one, and asks for it with startMonth.
 
 ## Keyboard
@@ -29,7 +54,16 @@ On its own for a range view or an availability grid; inside a DatePicker for cho
 
 ## Calendar
 
-A month, as a grid of days. Wraps react-day-picker rather than building a calendar, and the reason is the long tail: a month grid is easy, and everything around it is not — the keyboard contract (arrows move a day, Page moves a month, Home and End reach the week's ends), the `aria-live` announcement when the month changes, week numbering, the first day of the week varying by locale, and the fact that "today" and "selected" are different states a screen reader must hear apart. Every class is replaced rather than layered over the library's stylesheet, so nothing here depends on a CSS file this package does not control — but the library's OWN class is kept on each slot, because passing a class REPLACES it and every `.rdp-*` selector downstream depends on those.
+A month, as a grid of days. Wraps react-day-picker rather than building a calendar, and the reason is the long tail: a month grid is easy, and everything around it is not — the keyboard contract (arrows move a day, Page moves a month, Home and End reach the week's ends), the `aria-live` announcement when the month changes, week numbering, the first day of the week varying by locale, and the fact that "today" and "selected" are different states a screen reader must hear apart. Every class is replaced rather than layered over the library's stylesheet, so nothing here depends on a CSS file this package does not control — but the library's OWN class is kept on each slot, because passing a class REPLACES it and every `.rdp-*` selector downstream depends on those. The month names follow `locale`. The picker's own chrome — the two panels and the four chevrons that browse them — follows `CalendarLabels`, because `locale` cannot supply strings this package invented.
+
+### Props
+
+- `monthPanelLabel` — `string`. Names the panel showing twelve months.
+- `yearPanelLabel` — `string`. Names the panel showing a page of years.
+- `previousYearLabel` — `string`. The two chevrons that browse a year at a time, inside the month panel.
+- `nextYearLabel` — `string`.
+- `earlierYearsLabel` — `string`. The two chevrons that page the year grid, twenty-four at a time.
+- `laterYearsLabel` — `string`.
 
 Also accepts: `DayPickerProps`.
 

package/dist/agent/Card.md

@@ -4,7 +4,7 @@ A bounded surface, with no shadow under it.
 
 - Group: Surfaces
 - Import: `import { Card } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/card/
 - Related: table, figure-band
 
@@ -12,9 +12,31 @@ A bounded surface, with no shadow under it.
 
 A card that needs to read as raised is a plate, which separates by reversal instead of by blur.
 
+## Anatomy
+
+- **Box** (required) — A <div> with the --radius-lg corner and one of three grounds: outline, a hairline on the page ground and the default; plate, the one reversed feature surface; flat, no border at all, for a card whose grid already draws the rules between cells. It brings no padding, and it clips to its own corner.
+- **Header** — CardHeader — a space-between row above a hairline, px-5 py-4: title against the start edge, one marker or action against the end.
+- **Title** — CardTitle, in the editorial serif at --fs-item. An <h3> unless as says otherwise, and it reads --card-title rather than --ink directly, which is what keeps it legible when plate re-points that variable.
+- **Body** — CardBody — the content well at p-5, --ink-2, relaxed leading.
+- **Footer** — CardFooter — a quiet strip under a hairline, mono-meta at --ink-3-aa, for metadata or a secondary action.
+
+## Best practices
+
+### Do
+
+- Pass as on CardTitle: h3 is right inside a section that owns an h2 and wrong nearly everywhere else, and a grid of twelve cards is otherwise twelve h3s with no heading above them to belong to.
+- Use CardTitle inside a plate rather than your own heading — plate re-points --card-title to --on-feature, and a title that reads --ink directly came out at 1.25:1 on that ground: invisible, and invisible only on the one variant whose job is to look different.
+- Add the padding yourself when you skip the sub-parts: the box has none of its own, so children dropped straight in sit against the border.
+- Pass overflow-visible for the card that deliberately overhangs — a marker pinned to its edge, a control that breaks the outline. The box clips by default, because a card that rounds and does not clip lays a full-bleed image’s square corners over its round ones.
+
+### Don’t
+
+- A Card with an onClick is a div with an onClick — not focusable, not announced, unreachable by keyboard. Put a real control inside and let it stretch, so what is announced is a button and the whole card is still the target.
+- Do not spend plate more than once on a screen: it is the system’s single reversed surface, and a band of plates is a band with no ground left to reverse against.
+
 ## Card
 
-A bounded surface. No shadow, by law: depth in this system is a hairline and a change of ground, never a blur. A card that needs to read as raised is a `plate`, which separates by reversal instead. Compose with the named sub-parts, or drop children straight in when the card has no header or footer to speak of.
+A bounded surface. No shadow, by law: depth in this system is a hairline and a change of ground, never a blur. A card that needs to read as raised is a `plate`, which separates by reversal instead. It clips to its own corner. A card that rounds and does not clip lays a full-bleed image's square corners over its round ones at all four corners, and the same goes for a filled first child — a defect that is invisible until the first card with an image at the top of it. Pass `overflow-visible` for the rarer card that deliberately overhangs. Compose with the named sub-parts, or drop children straight in when the card has no header or footer to speak of.
 
 ### Props