@misoto22/design 0.7.0 → 0.9.0

package/dist/agent/DropdownMenu.md

@@ -4,7 +4,7 @@ A menu of actions.
 
 - Group: Overlays
 - Import: `import { DropdownMenu } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/dropdown-menu/
 - Related: dialog, select
 
@@ -12,10 +12,35 @@ A menu of actions.
 
 Actions. Items that navigate belong in a nav; items that set a value are a Select or a RadioGroup.
 
+## Anatomy
+
+- **Trigger** (required) — A passthrough to Radix, which renders its own bare button unless you pass asChild. It carries aria-haspopup and data-state, which is what lets a Button show that its menu is open.
+- **Panel** (required) — The portalled menu: at least 11rem wide, 6px off the trigger, colliding with 8px of padding against the viewport or the OverlayContainer frame. It has no max height, so it flips rather than scrolls.
+- **Item** — A row. icon takes either spelling — the Lucide component, sized to 16px here, or a rendered element, placed as given; destructive paints the row --danger; disabled drops pointer events and the opacity.
+- **Label** — A mono eyebrow, on its own. Visual only — Radix renders it as a plain div, and the arrow keys skip it. DropdownMenuGroup is the one that heads rows: it renders role="group" and points its aria-labelledby at this.
+- **Group** — A named section: role="group" around the rows, with label rendered inside it as the Label and named through aria-labelledby. The wiring is the component’s job because a caller doing it by hand has to invent an id.
+- **Separator** — A hairline between groups, and a real role="separator" — which a menu permits, unlike the listbox a Command palette is built on.
+
+## Best practices
+
+### Do
+
+- Pass icon the component — icon={Settings} — and let the row size it, so a menu of ten rows draws ten icons at one size rather than ten sizes. The element spelling is accepted too, and used to be the exact opposite of what CommandItem took one import away.
+- Give the trigger asChild and a real Button: without it Radix renders its own unstyled button, and the menu ends up hanging off a control that is not part of the system’s set.
+- Hold a dialog’s open state yourself and call event.preventDefault() in the item’s onSelect — selecting a row closes the menu, and Radix’s close moves focus back to the trigger, which arrives after the dialog has claimed it and pulls the reader straight back out.
+- Stop at about a dozen rows. There is no max height on the panel, so a longer menu grows until it hits the collision padding and flips above the trigger — SearchableMenu is the same list once it has outgrown this one.
+
+### Don’t
+
+- Radix defaults modal to true and nothing here overrides it, so while the menu is open the page behind is scroll-locked and its pointer events are off — a menu is not the place for something the reader is meant to consult the page while using.
+- A bare DropdownMenuLabel over rows is a picture of a heading: Radix’s MenuLabel is a plain div with no role and nothing tying it to what follows, so the sections a sighted reader sees arrive as one undivided list. DropdownMenuGroup renders both halves and wires them together.
+- There is no checkbox item, radio item or submenu in this package’s exports — a menu that needs a checked state has to import from @radix-ui/react-dropdown-menu directly, and that row arrives with none of this file’s styling on 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.
 - Highlight is driven by data-highlighted, which covers hover AND keyboard focus — styling :hover alone leaves the keyboard user unable to see where they are.
+- DropdownMenuGroup segments the menu for a screen reader as well as for the eye; a bare Label does it for the eye alone.
 
 ## Keyboard
 
@@ -32,7 +57,7 @@ Radix DropdownMenu root + trigger, re-exported as typed passthroughs.
 
 ## DropdownMenuContent
 
-A menu surface. A menu is a list of ACTIONS. If the items navigate somewhere, they belong in a nav; if they set a value, that is a `Select` or a `RadioGroup` — Radix has menu variants for both, and a plain item pretending to be a choice loses the checked state a screen reader needs.
+A menu surface. A menu is a list of ACTIONS. If the items navigate somewhere, they belong in a nav; if they set a value, that is a `Select` or a `RadioGroup` — this package ships no checkbox or radio menu item, and a plain item pretending to be a choice loses the checked state a screen reader needs.
 
 Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Content>`.
 
@@ -42,7 +67,7 @@ A menu row. Highlight is driven by Radix's `data-highlighted`, which covers both
 
 ### Props
 
-- `icon` — `LucideIcon`. Optional leading icon, rendered before the label.
+- `icon` — `LucideIcon | ReactNode`. Optional leading icon, rendered before the label. Either spelling: `icon={Settings}` passes the component and this sizes it, `icon={<Settings size={16} />}` passes the element and this places it. The two used to mean opposite things one import apart — `CommandItem.icon` took the element while this took the component — and the wrong one did not fail a type check into anything actionable, it failed at render.
 - `destructive` — `boolean` default `false`. Paints the row as destructive. Use for delete, revoke, disconnect.
 
 Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Item>`.
@@ -53,7 +78,17 @@ Hairline divider between menu groups.
 
 ## DropdownMenuLabel
 
-Mono eyebrow heading for a group of items.
+Mono eyebrow heading, on its own. Visual only: Radix renders it as a bare `<div>` with no role, so it segments the menu for a reader who can see it and for nobody else. Reach for `DropdownMenuGroup` when the eyebrow is a HEADING over rows; this is right for a line that heads nothing — the signed-in address at the top of an account menu.
+
+## DropdownMenuGroup
+
+A named section of a menu. The eyebrow alone was a picture of a heading. Radix's `MenuLabel` carries no role and no `aria-labelledby` wiring, and `MenuGroup` — which does carry `role="group"` — was not re-exported by this package at all, so a sighted reader saw three labelled sections and a screen-reader user got one undifferentiated list. This renders the group, renders the label inside it, and points the one at the other, which is the whole of the fix and not something a caller should have to remember.
+
+### Props
+
+- `label` — `ReactNode`. The eyebrow over the rows, and the group's accessible name.
+
+Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Group>`.
 
 ## Examples
 
@@ -61,10 +96,14 @@ Mono eyebrow heading for a group of items.
 <DropdownMenu>
   <DropdownMenuTrigger asChild><Button variant="secondary">Menu</Button></DropdownMenuTrigger>
   <DropdownMenuContent>
-    <DropdownMenuLabel>Account</DropdownMenuLabel>
-    <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>
+    <DropdownMenuGroup label="Account">
+      <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>
+    </DropdownMenuGroup>
     <DropdownMenuSeparator />
     <DropdownMenuItem icon={LogOut}>Sign out</DropdownMenuItem>
   </DropdownMenuContent>
 </DropdownMenu>
+<DropdownMenuGroup label="Account">
+  <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>
+</DropdownMenuGroup>
 ```

package/dist/agent/EmptyState.md

@@ -4,7 +4,7 @@ A collection with nothing in it — yet.
 
 - Group: Feedback
 - Import: `import { EmptyState } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/empty-state/
 - Related: error-state, skeleton
 
@@ -12,6 +12,28 @@ A collection with nothing in it — yet.
 
 Nothing went wrong. The copy says what to do, not what failed.
 
+## Anatomy
+
+- **Frame** (required) — A centred column with 80px of padding above and below and --page-pad either side. View-scale, and carrying no role and no live region of its own.
+- **Medallion** — The optional lucide icon at 24px inside a 56px --stone circle, aria-hidden. Decoration that gives the column something to start from, never the message.
+- **Title** (required) — title in the heading face at --fs-sub, rendered through Heading. level picks the element and defaults to 2; the size does not follow it, so the title is --fs-sub at every level.
+- **Description** — description in --ink-3-aa, capped at 24rem so it stays a readable measure while the column stays centred.
+- **Action** — The one thing to do next, 32px below the description and the only interactive element the frame offers.
+
+## Best practices
+
+### Do
+
+- Announce the swap yourself. This component has no role and no live region, so replacing a SkeletonPage with it removes the region that said “Loading projects” and puts nothing in its place — a screen reader is left at the last thing it heard.
+- Say which kind of empty this is. The same component serves a collection that is new and one that a filter has emptied, and “No projects yet” shown over an active filter tells the reader their projects are gone.
+- Set level from the heading above it. The default of 2 is right directly under a page’s h1; inside a section that already has its own h2, pass 3. Get it wrong and the outline gains a hole a screen reader navigates by.
+
+### Don’t
+
+- Do not show it for a failed request. A reader told the collection is empty acts on it — creating the record they already have, or reporting a data loss that never happened — and the recovery from that costs more than the error page would have.
+- Do not put it inside a card or a panel. 160px of vertical padding is sized to stand in for a view, and in a bordered box it reads as a box with a hole in it.
+- Do not write a paragraph into description. It is capped at 24rem and centred, so long copy becomes a narrow ragged column that the eye returns from before the sentence that mattered.
+
 ## EmptyState
 
 A collection with nothing in it — yet. Distinct from `ErrorState`: nothing went wrong here, so the copy says what to do rather than what failed. The two are different components because the shared temptation — one component with a `variant` — produces error pages that read like empty folders.
@@ -22,6 +44,7 @@ A collection with nothing in it — yet. Distinct from `ErrorState`: nothing wen
 - `title` (required) — `ReactNode`.
 - `description` — `ReactNode`.
 - `action` — `ReactNode`. The one thing to do next. An empty state without an action is a dead end.
+- `level` — `HeadingLevel` default `2`. The heading level `title` opens, in the document the empty state lands in. Defaults to `2`, which is the placement this component is sized for: it stands in for a whole view inside a page that already has an `h1`, so the level below that one is the level that does not leave a hole in heading navigation. Under a section that already has its own `h2`, pass `3`. The default was `3` and fixed, which was wrong in the ordinary case and impossible to correct — the documentation could name the rule but a caller had no prop to follow it with. `2` is the common case rather than a compromise, and it is optional rather than required because the correct placement has one answer often enough that making every existing call site restate it would buy nothing. The size does not follow the level. `title` renders at `--fs-sub` at every level, because moving a state down the outline is a fact about the document and not a request for smaller type.
 
 Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.
 
@@ -34,4 +57,6 @@ Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.
   description="Create your first project to get started."
   action={<Button>New project</Button>}
 />
+// Inside a section that already has its own heading.
+<EmptyState level={3} title="No invoices yet" />
 ```

package/dist/agent/ErrorState.md

@@ -4,10 +4,32 @@ A page that could not be shown.
 
 - Group: Feedback
 - Import: `import { ErrorState } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/error-state/
 - Related: empty-state, alert
 
+## Anatomy
+
+- **Screen** (required) — A section at least one viewport tall, painting its own --paper ground and holding 96px of clearance for a header. It is a page, not a block.
+- **Code** (required) — code at the top of the type ladder, aria-hidden. The largest thing on the screen and the one thing a screen reader is never told.
+- **Heading** (required) — heading through Heading at --fs-heading, and the first thing said aloud. level defaults to 1 because this replaces the page; the size is fixed, so an error state demoted to an h2 is the same size it was.
+- **Message** (required) — message at --measure-record, which is where the explanation of what happened goes.
+- **Action** (required) — The way back. Required rather than optional, and the only focusable thing on the screen.
+
+## Best practices
+
+### Do
+
+- Render it instead of the page, not inside it. It is a full viewport with its own ground and its own top clearance, so nested in a layout that already has a header it adds a second screen of blank below the fold.
+- Announce it or move focus into it on a client-side failure. There is no role and no live region here, so a route that swaps the whole screen for this one changes everything a sighted reader can see and says nothing at all.
+- Point action at a real destination rather than at history. A reader often arrives at an error page cold or from a link, so going back returns them to the page that just failed, or to nothing.
+
+### Don’t
+
+- Do not leave level at 1 inside an app shell that already has an h1. Two h1s on one document leave a heading list that no longer says which one is the page — pass level={2} for a state rendered into a shell rather than instead of one.
+- Do not put a request id, a trace or a sentence into code. It is set at --fs-title with leading-none and it is aria-hidden, so anything long becomes the biggest object on the page and is simultaneously invisible to the reader most likely to have to quote it.
+- Do not use it when one panel failed and the rest of the page still works. Replacing the whole screen throws away the navigation the reader needed to get out; an Alert inside the panel keeps both the error and the way past it.
+
 ## Accessibility
 
 - The big status code is aria-hidden; the heading immediately after says the same thing in words.
@@ -25,7 +47,8 @@ A page that could not be shown. The code is set at the top of the type ladder an
 - `code` (required) — `ReactNode`. The status, set large — "404", "500". Decorative; the heading carries the meaning.
 - `heading` (required) — `ReactNode`.
 - `message` (required) — `ReactNode`.
-- `action` (required) — `ReactNode`. The way back. Render it with .
+- `action` (required) — `ReactNode`. The way back. Render it with ERROR_ACTION_CLASS.
+- `level` — `HeadingLevel` default `1`. The heading level `heading` opens, in the document the error state lands in. Defaults to `1`, and that is not a compromise: this component replaces the page rather than sitting inside one — its own ground, its own viewport, its own top clearance — so the page's single `h1` is the one it renders. Kept as the default, existing call sites render exactly the markup they did. The prop exists because the level was previously fixed, and the one piece of advice this component's documentation gives about headings — do not put it inside a shell that already has an `h1` — was advice a caller had no way to take. Now they do: inside a shell that owns the page heading, pass `2`. The size does not follow the level. `heading` renders at `--fs-heading` at every level; a failure demoted in the outline is the same failure.
 
 Also accepts: `HTMLAttributes<HTMLElement>`.
 
@@ -38,4 +61,6 @@ Also accepts: `HTMLAttributes<HTMLElement>`.
   message="The page you're looking for has moved, or never existed."
   action={<a href="/" className={ERROR_ACTION_CLASS}>Back home</a>}
 />
+// Inside a shell that already owns the page's h1.
+<ErrorState level={2} code="503" heading="Invoices could not be loaded" … />
 ```

package/dist/agent/Facet.md

@@ -4,7 +4,7 @@ The same chart once per group, on one shared scale.
 
 - Group: Charts
 - Import: `import { Facet } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/facet/
 - Related: line-chart, sparkline
 
@@ -12,6 +12,30 @@ The same chart once per group, on one shared scale.
 
 Eight series overplot into a hairball in one frame. Two or three series that genuinely need comparing point-for-point still belong in one chart.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure> around the whole grid, named by title. Its empty state has no false escape hatch, unlike a single chart’s: an empty pair of axes is at least a chart, and an empty grid is nothing.
+- **Panel grid** (required) — A role="list" of <li> panels on a CSS auto-fit track. list-none strips the list role in Safari, so it is set back by hand — a grid of twelve plots that does not announce twelve items takes away the reader’s only cue for how far they have to go.
+- **Panel name** — A <p> above each plot. showPanelNames={false} makes it sr-only rather than removing it, because a grid whose panels a screen reader cannot tell apart is one figure with twelve anonymous plots in it.
+- **Shared domain** (required) — panel.domain, computed across the panels that survive the cap and handed to the render function. It is not applied for you: a panel that does not pass it to its own value axis has opted back into independent scales.
+- **Grid-level legend and axis labels** — legend, yLabel and xLabel, printed once above and below the grid. A legend inside every panel is the same three swatches twelve times, restating what the reader learned from the first one.
+- **Overflow note** — The line under a capped grid, saying how many groups were left out or folded. limit is 12 by default and nothing is ever dropped in silence.
+
+## Best practices
+
+### Do
+
+- Pass panel.domain to the panel chart’s value axis. That one line is what the component is for: on independent scales a group peaking at 40 and one peaking at 4,000 draw the same shape, so the comparison is not merely lost, it is inverted — and nothing on screen says so.
+- Name every plotted field in value. It is what the shared domain is measured over, so a panel that draws a series value does not mention can overflow its own axis while the rest of the grid looks correct.
+- Set hideDataTable when the panel charts carry their own. Every chart in the package renders its rows as an sr-only table, so a twelve-panel grid otherwise puts thirteen tables into the accessibility tree.
+- Keep sort="max" for a grid a reader scans and switch to "name" for one they look things up in. Reading order is what a reader takes as ranking, so it is a decision in either direction.
+
+### Don’t
+
+- overflow="fold" is not free. The folded panel is the SUM of the tail at each category and its statistics go into the shared domain, so folding twenty-eight small groups can produce one tall panel that squashes the twelve the reader came for. Use note when the tail is numerous rather than large.
+- Do not turn includeZero off under bars or areas. It is on by default for the same reason a bar axis is anchored at zero — a length read against a truncated baseline overstates every difference, and a grid exists to have its differences compared.
+- Do not reach for it at two or three series. Faceting buys back every individual shape and pays for it with the direct overlay, and crossovers, gaps and shares of one total are exactly what the overlay was for.
+
 ## Accessibility
 
 - The shared domain is the default and the whole point: on independent scales a group peaking at 40 and one peaking at 4,000 draw the same shape, and the comparison the reader came for is not merely lost but inverted.

package/dist/agent/Field.md

@@ -1,37 +1,78 @@
 # Field
 
-A labelled form row: label, control, and the one message below it.
+A labelled form row: label, control, and the one message below it — and, in row layout, the settings row.
 
 - Group: Forms
 - Import: `import { Field } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/field/
-- Related: input, select
+- Related: input, select, switch
+
+## When to reach for it
+
+Any labelled control. layout="row" is the settings row — label and description at the inline start, control at the inline end — which is a layout here rather than a second component, because the label wiring, the required marker and the message slot are the same three things either way.
+
+## Anatomy
+
+- **Label** — label, rendered as a Radix <Label> carrying htmlFor and an id. The id is what a trigger names itself from, alongside its own value, and what a group points back at — neither of which htmlFor can do.
+- **Required mark** — The --danger asterisk after the label when required. aria-hidden, but still inside the label’s text, so the accessible name ends “Email *”.
+- **Control slot** (required) — children — ONE element, which the field clones to add id, aria-describedby, aria-required and aria-invalid, and which each control forwards to whatever element carries its role: the trigger for Select, Combobox and DatePicker, the root for a group, the thumb for a Slider. This is the whole contract; everything else is layout.
+- **Description** — description, a second line under the LABEL explaining what the setting does — as distinct from hint, which sits under the control and belongs to the input. It has its own id and joins aria-describedby ahead of the message, so a row with both announces both.
+- **Message** — A single <p> below the control: error if there is one, hint otherwise, never both. It owns the id that aria-describedby points at, and it is --danger or --ink-3-aa accordingly.
+- **Row layout** — layout="row": the label and description in a column at the inline start, the control at the inline end, the message underneath both. The two columns are TOP-aligned — items-start on the block axis, not items-center — so a two-line description does not drag the switch down to the middle of the paragraph, and a column of settings rows keeps every control on the same line as the words that name it.
+
+## Best practices
+
+### Do
+
+- Make children the control itself, not a layout wrapper around it: the wiring is a cloneElement on the single child, so a <div> in between takes the id and the aria-describedby and the label ends up naming a box.
+- Let error carry the invalid state. The field sets aria-invalid on the control, and Input, Textarea, NativeSelect, Select and Combobox all read either spelling through isInvalid, so passing invalid as well states the same fact twice from two places that can disagree.
+- Pass htmlFor, and the same id on the control, whenever something outside the row has to address it — a form library, a scroll-to-first-error, a test. The generated id is a useId value nothing else can predict.
+- Build a settings screen out of layout="row" with description, not out of three hand-rolled divs. The label still reaches the control through the same wiring, so the switch on the far side of the row is named by the words on the near side.
+
+### Don’t
+
+- required here is aria-required and an asterisk, and nothing else: it never reaches the control’s own required attribute, so the browser will not block the submit and the row stays unmarked until you pass error yourself.
+- The words above a RadioGroup or a ToggleGroup name it but do not click through. Both roots are <div role="radiogroup">, which htmlFor does not bind to, so the label is pointed AT by the group instead — a reader who clicks it the way they click "Email" gets nothing, exactly as with a <legend>.
+- Do not reach for description as a second hint. It explains the SETTING and sits under the label; hint explains the INPUT and sits under the control. A row that uses one for the other reads correctly and lands in the wrong place.
+- required is announced on every control here except DatePicker, whose trigger is a plain <button> — a role with nowhere to put aria-required. There the asterisk is the whole of the marking, and a screen reader meets an ordinary optional field.
 
 ## Accessibility
 
 - Generates an id when none is given, so the label always points at something.
 - Wires aria-describedby, aria-required and aria-invalid onto the control, so validation is announced and not merely drawn.
 - hint and error are one slot: when a field is wrong, the thing to read is what is wrong with it.
+- description joins aria-describedby ahead of the message, so a settings row announces what the setting does and then what is wrong with it.
+- Every control forwards the wiring to the element that carries its role, so the hint under a Select or a Slider is announced and not merely drawn.
+- The row layout moves the label to the other side of the row and changes nothing about the association, so a settings row with a Switch or a Select in it is named by the words on the near side. Slider is the exception, and the layout cannot fix it: role="slider" is on the THUMB while the field’s label points at the roleless root, so there the label prop on the Slider is still the only name a reader hears.
 
 ## Field
 
-A labelled form row: label, control, and the one message below it. The visible message is only half of accessible validation — it must also reach the control. This wires `aria-describedby`, `aria-required` and `aria-invalid` onto the single control child so the requirement and the error are announced, not merely drawn (WCAG 1.3.1 / 3.3.1 / 4.1.2). An earlier version derived the message id from `htmlFor`, which meant a caller who left `htmlFor` off got a hint that was rendered and never announced — the failure was invisible in the browser and total for a screen reader. The id is now generated when it is not supplied. `hint` and `error` are one slot, not two stacked messages: when a field is wrong, the thing to read is what is wrong with it.
+A labelled form row: label, control, and the one message below it. The visible message is only half of accessible validation — it must also reach the control. This wires `aria-describedby`, `aria-required` and `aria-invalid` onto the single control child so the requirement and the error are announced, not merely drawn (WCAG 1.3.1 / 3.3.1 / 4.1.2). An earlier version derived the message id from `htmlFor`, which meant a caller who left `htmlFor` off got a hint that was rendered and never announced — the failure was invisible in the browser and total for a screen reader. The id is now generated when it is not supplied. `hint` and `error` are one slot, not two stacked messages: when a field is wrong, the thing to read is what is wrong with it. `description` is a different slot again — it explains the SETTING, not the input, and it is what `layout="row"` puts under the label to make a settings row. **How the wiring reaches the control.** `cloneElement` puts the four attributes on the single child, and each control forwards them to whatever element carries the role — which is the child itself for `Input`, `Textarea`, `NativeSelect`, `Checkbox`, `Switch` and any host element written by hand, and a trigger, a group or a thumb further down for `Select`, `Combobox`, `DatePicker`, `Slider`, `RadioGroup` and `ToggleGroup`. The composites used to drop them on the floor, which drew a hint under a control that never announced it; a wrapper that appears to wire things up and does not is worse than one that never claimed to. The label's own id travels separately, through context, because a name is the one thing a prop cannot carry: a trigger whose text is its VALUE is named by the label AND by itself, so `<Field label="Region"><Select/></Field>` announces "Region, Australia" rather than either half. Three things stay out of reach, and each of them is the control's own markup rather than a gap in this wiring. A `<label for>` binds only to a labellable element, so the words do not click through to a `RadioGroup`, a `ToggleGroup` or a `Slider`: the first two are a `role="radiogroup"` named by pointing back at the label instead, exactly as a `<legend>` is, and the third carries `role="slider"` on a thumb below a roleless root. `required` reaches a control as `aria-required`, which `DatePicker`'s plain `<button>` trigger and a multiple-value `ToggleGroup`'s `role="toolbar"` have nowhere to put; there the asterisk is the only marker. And `aria-invalid` reaches `Slider`'s root rather than its thumb, so an errored slider is drawn wrong without being announced wrong. Each composite still takes its own `label` prop — that is what names it standing outside a field, and `Select`, `Combobox` and `DatePicker` warn when it is blank. It is no longer used INSTEAD of this one's. What no wiring can reach, the field says out loud in development rather than failing silently: `FIELD_CONTROL_NOT_LABELLABLE` when the child is a host element a label cannot bind to — the `<div>` wrapper that takes the id and leaves the control inside it with nothing — and `FIELD_CONTROL_NOT_WIRED` when there is no single element to wire at all.
 
 ### Props
 
 - `label` — `ReactNode`. Visible label text; renders a `--danger` asterisk when `required`.
 - `htmlFor` — `string`. The control's `id`. Optional: when omitted, the field generates one and puts it on the control child itself, so the label still points at something. Pass it explicitly when the id has to be stable across renders — a form library referencing it by name, say.
+- `description` — `ReactNode`. A second line under the LABEL, explaining what the setting does. Distinct from `hint`, which sits under the control and belongs to the input — "We never share it". This belongs to the thing being switched on, and it is what makes a settings row a settings row. Both reach the control through `aria-describedby`, so a row that has a description and an error announces both.
 - `hint` — `ReactNode`. Helper copy shown below the control when there is no `error`.
 - `error` — `ReactNode`. Validation message; takes precedence over `hint` when present.
 - `required` — `boolean`.
+- `layout` — `FieldLayout` default `'stacked'`. Where the control sits relative to its label. See FieldLayout.
 - `children` (required) — `ReactNode`.
 
 Also accepts: `HTMLAttributes<HTMLDivElement>`.
 
+## Types
+
+- `FieldLayout` = `'stacked' | 'row'`
+
 ## Examples
 
 ```tsx
 <Field label="Email" required hint="We never share it."><Input type="email" /></Field>
 <Field label="Name" error="Name is required."><Input /></Field>
+<Field layout="row" label="Email notifications" description="A digest every Monday.">
+  <Switch defaultChecked />
+</Field>
 ```

package/dist/agent/FigureBand.md

@@ -4,10 +4,33 @@ A row of counted facts, divided by hairlines and nothing else.
 
 - Group: Display
 - Import: `import { FigureBand } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/figure-band/
 - Related: table
 
+## Anatomy
+
+- **Query wrapper** (required) — A plain <div> around the list, and it has to be: a container query resolves against an ANCESTOR container, never against the element declaring one. Its w-full is load-bearing too — contain: inline-size computes width without looking at the contents, so as a shrink-to-fit flex item it resolved to zero and the band rendered as two 0px columns.
+- **Band** (required) — The <dl>: ruled top and bottom in --rule, two columns until the wrapper reaches @3xl and four after — a decision about how wide THIS band is, not how wide the window is.
+- **Cell** (required) — One <div> per figure. Each divider width names the cells that do NOT open a row rather than adding a rule and taking it back, so no edge is ever painted past the last column.
+- **Label** (required) — The <dt>: the mono uppercase kicker over the value.
+- **Value** (required) — The <dd>, set in the heading face at --fs-lead or --fs-sub depending on scale.
+- **Note** — A second <dd> under the same term — a trend, a qualifier, a second fact.
+
+## Best practices
+
+### Do
+
+- Give it two or four figures. The grid is two columns until @3xl and four after, so three leaves a hole in both arrangements and five leaves three holes once the band goes four across.
+- Use scale="sub" for a band that supports the page rather than being it: --fs-lead is the band-heading step, so a supporting figure set at lead is competing with the page’s own subject.
+- Key each figure by the fact it counts — id is required rather than optional, because it is the React key and an index puts the next render’s number under the previous label as soon as the list reorders.
+
+### Don’t
+
+- Do not put a sentence in note. The value and the note are two <dd>s under one <dt>, so a screen reader reads them as two values of the same term: “Posts: 48, +6 this year” works, a clause does not.
+- Do not set the column count with a viewport breakpoint through className. The band reads a container query, so a sm:grid-cols-4 written on it is wrong in a 390px sidebar of a 1440px window — which is the arrangement this replaced.
+- figures={[]} renders null, so a band fed a filtered-empty array leaves no rules behind and no zero state either — if the absence is the news, the call site has to say so.
+
 ## Accessibility
 
 - A <dl>: each cell is a term and its value, which a grid of divs cannot express.

package/dist/agent/FloatingIconButton.md

@@ -4,7 +4,7 @@ A round action pinned to a screen corner.
 
 - Group: Actions
 - Import: `import { FloatingIconButton } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/floating-icon-button/
 - Related: button
 
@@ -12,6 +12,28 @@ A round action pinned to a screen corner.
 
 A page-level affordance that must stay reachable while the reader scrolls — back to top, a mobile table of contents.
 
+## Anatomy
+
+- **Control box** (required) — A real <button type="button">, --control-h-md square with a pill radius, position: fixed to a bottom corner at --z-drawer. There is no asChild and no href here: it cannot become a link.
+- **Icon** (required) — children, and the only thing in the box. Nothing text-shaped renders, so the control is as wide as the square and no wider.
+- **Ground** (required) — A 90% --paper fill over a backdrop blur, with a --rule-2 hairline. The White Reset has no elevation ramp, so the blur and the hairline are what lift it off the page — not a shadow.
+- **Name** (required) — label, set as aria-label. It never renders, so a screen reader has the name and a sighted reader has the glyph alone.
+
+## Best practices
+
+### Do
+
+- Spell out position — it is required and has no default, and the values are start and end in reading order. The component’s own doc example says position="right", which is not one of them and does not type-check.
+- Wrap it in a Tooltip when the glyph is not universal: label is aria-label only, so it names the control for a screen reader and for nobody else — and a tooltip does not open on touch, which is where a floating control is most often the only affordance on screen.
+- Keep it to two. start is deliberately raised to 5rem while end sits at 1.5rem, which is exactly enough clearance for a pair; a third has nowhere left to go, and the corners already compete with a cookie bar and a chat launcher.
+- Move it with className when the page has a fixed footer — the classes go through tailwind-merge, so className="bottom-24" REPLACES the corner offset rather than losing to it.
+
+### Don’t
+
+- --control-h-md is 44px at the default density and 36px under data-density="compact", so a compact page ships the one control a thumb reaches for without looking at eight pixels under the WCAG 2.5.5 floor.
+- It is position: fixed, so any ancestor with a transform, filter or backdrop-filter becomes its containing block — put one inside a DialogContent, which centres itself with a translate, and it pins to the panel’s corner instead of the screen’s.
+- It sits at --z-drawer, 100, and every rank that can appear over it is higher: a scrim is 200, a modal 210, an anchored panel 220 — --z-dropdown now resolves to --z-anchored, not to this rank. So a menu opening into the same corner covers the button outright rather than tying with it, and a dialog covers it too. Nothing here is settled by document order; move the button with className if it must stay reachable beside something else.
+
 ## Accessibility
 
 - label is the only name the control has; it is required rather than optional.

package/dist/agent/FunnelChart.md

@@ -4,7 +4,7 @@ Stages that only ever narrow.
 
 - Group: Charts
 - Import: `import { FunnelChart } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/funnel-chart/
 - Related: sankey-chart, bar-chart
 
@@ -12,6 +12,27 @@ Stages that only ever narrow.
 
 A signup flow, a hiring pipeline, a checkout. When the flow can SPLIT rather than only shrink, it is a SankeyChart — a funnel has one path through it by construction.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero stages. There is still no loading skeleton, so that state remains the call site’s job.
+- **Stages** (required) — <FunnelChart.Funnel>. The rows are drawn in the order given and never sorted, and each stage is cut from the next by a --chart-surface stroke gap pixels wide rather than by a transparent gap, so the stages still touch.
+- **Stage labels** — <FunnelChart.Label>, positioned right by default. Its dataKey defaults to the NAME field, not the value — printing the numbers means pointing it at the value key yourself.
+- **Tooltip** — <FunnelChart.Tooltip>, heading suppressed and cursor off. There is no axis here for a crosshair to run along.
+- **Hidden data table** — The sr-only table, one row per stage. It is the only exact reading this form offers, because a funnel has no axis and no ticks anywhere on it.
+
+## Best practices
+
+### Do
+
+- Point <FunnelChart.Label> at the value field. With no dataKey it prints the stage NAME, which the reader already has, and the number — the one thing the taper cannot be read for — goes unprinted.
+- Order the rows widest first yourself. The component draws them in the order it is handed and does not sort, so a stage out of place renders a funnel that widens, which a reader will read as a data error.
+- Keep variant="stepped" unless the stages are also a sequence of kinds. ramp walks the series ramp stage by stage, which encodes the drop a second time when the taper has already said it.
+
+### Don’t
+
+- Do not use it for a flow that splits. A funnel has one path through it by construction; where a stage divides into two outcomes the honest form is a SankeyChart, which can draw both branches.
+- Do not read the fall-off off the shape. The taper is a ratio between neighbours and the eye reads the enclosed AREA, so a shallow drop is exaggerated and a steep one flattened, with no axis anywhere to check it against.
+
 ## Accessibility
 
 - title is required; the stages are also rendered as a visually hidden table.
@@ -35,6 +56,7 @@ Stages that only ever narrow — a signup flow, a hiring pipeline, a checkout. T
 - `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
 - `chartProps` — `ComponentProps<typeof RechartsFunnelChart>`. Escape hatch onto the raw Recharts chart element.
 - `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/Heading.md

@@ -0,0 +1,64 @@
+# Heading
+
+A heading whose element and whose size are two decisions.
+
+- Group: Display
+- Import: `import { Heading } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/heading/
+- Related: text, article, markdown
+
+## When to reach for it
+
+Any heading. level follows the document outline; size follows the design, and defaults from level.
+
+## Anatomy
+
+- **Element** (required) — level, 1 to 6, rendered as the matching <h1>–<h6>. This is the document outline — what a screen reader navigates by — so it follows the section the heading opens, never the size it wants to be.
+- **Step** (required) — size, one of title, lead, heading, sub, item and label. Defaults from level through the system ladder, so writing only level is correct.
+- **Anchor offset** (required) — scroll-margin-top: var(--scroll-offset), carried by every heading, so one given an id and linked from a table of contents comes to rest below the masthead instead of under it.
+
+## Best practices
+
+### Do
+
+- Write level alone unless the outline and the design genuinely disagree. The default ladder is 1→title, 2→heading, 3→sub, 4→item, 5 and 6→label — the same map article.css applies to rendered Markdown, which is what makes a post and a component page read as one publication.
+- Notice that the default ladder SKIPS lead between levels 1 and 2, and skip a step yourself when you set size by hand: --fs-lead over --fs-heading is a ratio of 1.14 and reads as a rendering accident, where --fs-title over --fs-heading is 1.86 and reads as a hierarchy.
+- Give a heading an id when anything links to it. The component already carries the scroll offset the anchor needs; nothing else on the page does.
+
+### Don’t
+
+- Do not raise level to get a bigger heading. Two <h1>s on a page make its outline unnavigable, and size is one prop away.
+- Do not reach past size="title". The ladder ends there because a page has exactly one thing larger than its own records; a bigger heading is className territory and it is the moment the page stopped being in the system.
+- size="label" is the mono kicker at 11px and --ink-3-aa, not a small serif heading — it is what levels 5 and 6 should look like, and setting it on an <h2> makes the section title read as metadata.
+
+## Accessibility
+
+- level renders the real heading element, so the outline is navigable rather than merely visible.
+- The two decisions are separate props, which is what lets a semantically-correct h3 look like a page title without bending the outline.
+- Carries scroll-margin-top so an anchored heading is not hidden under a fixed masthead (WCAG 2.4.7 in practice).
+
+## Heading
+
+A heading, with its element and its size decided separately. Every heading component that takes one number gets this wrong in one of two directions: either the outline is bent to reach a size (an `<h1>` in the middle of a page because the design wanted big type), or the size is bent to keep the outline (a section title set at 20px because it is the fourth level down). Both are one prop away from being right, so there are two. `level` is the document. `size` is the page. The default binds them through the system's ladder, so writing only `level` is correct — and the moment they come apart, the call site says so. Set in the editorial serif at weight 400, like every heading in the system. It also carries `scroll-margin-top`, so a heading given an `id` and linked from a table of contents comes to rest below the masthead rather than under it.
+
+### Props
+
+- `children` — `ReactNode`.
+- `level` (required) — `HeadingLevel`. The element: `1` renders `<h1>`, `6` renders `<h6>`. This is the document outline and nothing else — it is what a screen reader navigates by, so it follows the section the heading opens, never the size it wants to be. A heading two levels down inside an `<h2>` section is an `<h3>` even when the design calls for something enormous.
+- `size` — `HeadingSize`. The size, when the outline and the design genuinely disagree. Defaults from `level` through the ladder above, which is the answer nearly always. Reach for this when a semantically-correct `h3` opens a page and has to look like one — not to squeeze a fourth step between two that are already only 14% apart.
+
+Also accepts: `HTMLAttributes<HTMLHeadingElement>`.
+
+## Types
+
+- `HeadingLevel` = `1 | 2 | 3 | 4 | 5 | 6`
+- `HeadingSize` = `'title' | 'lead' | 'heading' | 'sub' | 'item' | 'label'`
+
+## Examples
+
+```tsx
+<Heading level={1}>The White Reset</Heading>
+// Third level in the outline, page-title sized.
+<Heading level={3} size="title">Colour</Heading>
+```

package/dist/agent/Heatmap.md

@@ -4,7 +4,7 @@ A grid of values read by weight.
 
 - Group: Data
 - Import: `import { Heatmap } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/heatmap/
 - Related: table, scatter-chart
 
@@ -12,6 +12,29 @@ A grid of values read by weight.
 
 A calendar of activity, a confusion matrix, an hour-by-weekday load. The one form a monochrome system renders better than a chromatic one.
 
+## Anatomy
+
+- **Figure caption** (required) — title in a figcaption, hidden from sight unless showTitle prints it above the grid with description under it. The same string is also the table’s own sr-only caption, so the grid is named on the way in and again from the table.
+- **Column headers** (required) — One th scope="col" per entry in columns, in the order given, preceded by an sr-only corner cell reading “Row” so the header line has something standing over the row labels.
+- **Row headers** (required) — One th scope="row" per entry in rows — end-aligned mono at --chart-axis, so every cell can be traced back to the pair of labels that names it.
+- **Cell** (required) — A td whose background is a color-mix of --series-1 into --chart-surface at the value’s position in the domain. Continuous rather than stepped, because banding a ramp invents boundaries the data does not have, and 2px of border-spacing between cells is what makes two neighbouring weights countable.
+- **Missing cell** — What a null draws — and what a row and column pair absent from cells draws too: a dashed --rule outline over the page, announcing “no data” instead of a number.
+- **Printed value** — formatValue inside the cell. Visible with showValues, otherwise sr-only and un-hidden again under forced colours, where the wash that WAS the encoding has been remapped away.
+
+## Best practices
+
+### Do
+
+- Switch scale to diverging the moment the values cross zero. sequential ramps on POSITION in the domain, so on a grid of changes the deepest fall is the palest cell and the biggest rise the darkest; diverging ramps on distance from the midpoint instead, which is the read a delta actually wants.
+- Pin domain when one cell is an order of magnitude clear of the rest. The derived domain runs from zero — or the lowest value, when that is negative — to the highest, so a single 10,000 among readings of 5 to 40 puts every other cell inside the first half percent of the ramp, and forty distinct numbers render as one dark square on a blank grid.
+- Spell a cell’s row and column exactly as they appear in rows and columns: cells are looked up by that pair, so an unmatched entry draws nothing at all. It no longer counts toward the derived domain either — a typo used to stretch the ramp with a value that appeared nowhere on the grid, pushing every drawn cell into the first fraction of it.
+- Take the contrast trade knowingly when showValues goes on. The wash is capped at 35 percent of the ramp so one ink colour clears 4.5:1 on every cell — the ORDER of the cells survives untouched, the spread between them narrows, and the printed numbers become the thing carrying the detail.
+
+### Don’t
+
+- Do not let a pipeline fill gaps with zero before the grid sees them. A null is drawn as a dashed outline and announced as no data, and a zero is drawn as the palest cell on the ramp — so substituting one for the other turns an outage into a quiet hour, and nothing on the grid says which it was.
+- Do not expect a reader to recover a figure from the wash. There is no legend and no step: weight orders the cells and never states one. The forced-colours fallback un-hides the numbers because the background has stopped existing there, which is a rescue for a remapped ground rather than a substitute for showValues on a grid whose exact figures matter.
+
 ## Accessibility
 
 - A real <table>, not an SVG: the structure a screen reader walks is the structure the eye reads, and every cell announces its own row, column and value.
@@ -36,6 +59,7 @@ A grid of values read by weight — a calendar of activity, a confusion matrix,
 - `formatValue` — `(value: number) => string` default `(value) => value.toLocaleString()`. Formats a value for the cell's announcement and its printed label.
 - `showValues` — `boolean` default `false`. Prints the number inside each cell. Only legible on a coarse grid.
 - `className` — `string`.
+- `empty` — `ChartEmptyProps`. What the grid shows when it has no rows or no columns to draw. A heatmap with no headers renders as a caption over nothing, which reads as a grid that failed to load rather than as one with nothing in it.
 
 ## Types