@misoto22/design 0.7.0 → 0.9.0

package/dist/agent/Checkbox.md

@@ -4,7 +4,7 @@ A choice that takes effect when the form is submitted.
 
 - Group: Forms
 - Import: `import { Checkbox } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/checkbox/
 - Related: switch, radio-group
 
@@ -12,6 +12,27 @@ A choice that takes effect when the form is submitted.
 
 A setting that applies immediately is a Switch.
 
+## Anatomy
+
+- **Box** (required) — An 18px <button role="checkbox"> on --radius-xs. It fills with --accent for BOTH checked and indeterminate, so the fill says “not off” rather than “on”.
+- **Tick** — The check glyph, aria-hidden — Radix shows the indicator, the state is carried by the role.
+- **Dash** — The minus that replaces the tick, chosen from the state the box is actually in — controlled or not, so defaultChecked="indeterminate" draws the dash it promised rather than a tick.
+- **Label** — Not rendered here. Unlike RadioGroupItem, nothing wraps the box in a <label>, so the words beside it and the click target they give it are the call site’s job.
+
+## Best practices
+
+### Do
+
+- Wrap it and its words in a <label>, or put it in a Field: the control renders no label of its own, so a bare Checkbox has no accessible name and an 18px box is the entire click target.
+- Hold an indeterminate box on controlled state. It is a report about OTHER rows, and clicking it hands you true — a “select all” header that keeps its own answer stops describing the list underneath it on the first click.
+- Default the value on the server. An unticked box sends no entry at all in a form submission, so the field a reader deliberately cleared and a field that was never rendered arrive identically as undefined.
+
+### Don’t
+
+- checked without onCheckedChange gives a box that never moves: Radix treats the prop as the source of truth, so the reader clicks a control that is neither broken nor working and gets no feedback either way.
+- There is no readOnly on a Radix checkbox. disabled is the only lock and it drops the box out of the tab order and out of the form, so a value that must be shown but not changed is better drawn as text.
+- Do not put the indeterminate state on a leaf. It means “some of the things under this one”, so a box with nothing under it that draws a dash is reporting a state its own value cannot hold.
+
 ## Accessibility
 
 - Supports the indeterminate state, which is what a “select all” header needs when only some rows are selected.
@@ -22,7 +43,7 @@ A setting that applies immediately is a Switch.
 
 ## Checkbox
 
-A choice that takes effect when the form is submitted. Supports the indeterminate state (`checked="indeterminate"`), which is what a "select all" header needs when only some rows are selected — a plain unchecked box there tells the reader the opposite of the truth. Pair with `Field`, or wrap it in a `<label>` at the call site so the words beside it are part of the click target.
+A choice that takes effect when the form is submitted. Supports the indeterminate state (`checked="indeterminate"`), which is what a "select all" header needs when only some rows are selected — a plain unchecked box there tells the reader the opposite of the truth. Controlled or not: the glyph follows the state the box is actually in, so an uncontrolled `defaultChecked="indeterminate"` draws the dash rather than the tick that says the opposite. Pair with `Field`, or wrap it in a `<label>` at the call site so the words beside it are part of the click target.
 
 Also accepts: `ComponentProps<typeof CheckboxPrimitive.Root>`.
 

package/dist/agent/Code.md

@@ -0,0 +1,50 @@
+# Code
+
+A function name or a flag, inside a sentence.
+
+- Group: Display
+- Import: `import { Code } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/code/
+- Related: code-block, kbd
+
+## When to reach for it
+
+Inline code within running text. A multi-line snippet is a CodeBlock.
+
+## Anatomy
+
+- **Chip** (required) — A real <code> on the --radius-sm corner, filled with --stone. Sized at 0.85em rather than in pixels, so the same token is proportionate in body copy, in a caption and in a table cell.
+
+## Best practices
+
+### Do
+
+- Use it for anything the reader would type or the machine would read: a flag, a path, a function, an env var name. The mono face is the signal that the string is literal.
+- Let it inherit its size. It is set in em on purpose — fixed at one pixel value, the identical token comes out three different sizes on one page depending on where it landed.
+
+### Don’t
+
+- Do not hand it a multi-line string. It keeps no whitespace and draws no plate, so the snippet collapses into one run — that is CodeBlock’s job.
+- Do not style a <span> to look like this instead. The element is the whole point: a mono span reads identically and tells a screen reader nothing, and "pass dash dash force" is not what the sentence said.
+
+## Accessibility
+
+- Renders <code>, which is what tells assistive tech the run is literal rather than prose.
+
+## Code
+
+A function name, a flag, a filename — inside a sentence. Renders a `<code>`, which is the element that means this. A `<span>` in a mono face looks identical and tells a screen reader nothing, and "pass dash dash force" is not what the sentence said. Sized in `em` rather than in pixels, so the chip tracks whatever type it sits beside — the same rule `Kbd` follows, and for the same reason: fixed at one value, the identical token came out three different sizes on one page depending on whether it landed in body copy, a caption or a table cell. The block form is `CodeBlock`. This one is inline by construction: it draws no plate, keeps no whitespace, and a multi-line string handed to it collapses into one run.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Examples
+
+```tsx
+Pass <Code>--force</Code> to overwrite the existing file.
+The helper lives in <Code>src/lib/cn.ts</Code>.
+```

package/dist/agent/CodeBlock.md

@@ -0,0 +1,74 @@
+# CodeBlock
+
+A multi-line snippet, on a plate, with a way to take it away.
+
+- Group: Display
+- Import: `import { CodeBlock } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/code-block/
+- Related: code, markdown, article
+
+## When to reach for it
+
+Any snippet longer than a word. Pass html when a build-time highlighter has already run; pass code alone when it has not.
+
+## Anatomy
+
+- **Plate** (required) — The --paper-2 box on the --radius-lg corner with a --rule hairline. One elevated step, not a second surface colour.
+- **Strip** — The bar along the top: title at the start, the language label at the end, the copy button after it. Present whenever there is anything to put in it, and never a hover-only affordance.
+- **Copy button** — A ghost iconOnly Button that puts code — the string, never the rendered markup — on the clipboard, and flips its own accessible name to “Copied” for 1.6 seconds.
+- **Body** (required) — A focusable, named role="group" that scrolls in both axes. Focusable because a scrollable box containing nothing focusable is unreachable by keyboard: there is nothing to Tab to, so the right-hand half of a long line does not exist without a mouse. A group and not a region, because a region is a landmark and a snippet is not one — three fenced blocks in an article would be three landmarks all called Code.
+- **Line row** — One <span data-line> per line on the plain path, carrying its own number and its own highlight band. The number is a child of the line it numbers, so the two cannot come apart.
+
+## Best practices
+
+### Do
+
+- Always pass code, even alongside html. It is what the copy button copies: a block that copies its rendered markup hands the reader a wall of spans, and one that scrapes textContent back out of the DOM is a non-breaking space away from pasting something that does not run.
+- Highlight at build time and pass html. A highlighter is a few hundred kilobytes of grammar shipped to re-derive spans that never change, which would be the largest thing on the page.
+- Give maxHeight to a long snippet rather than letting it run. The body scrolls and is focusable, so what is past the fold stays reachable by keyboard.
+
+### Don’t
+
+- lineNumbers and highlightLines are typed out of the html form and passing both is a compile error. They are a per-line structure, and html is one opaque string the component does not parse — which is why the type says so rather than the prop quietly rendering nothing.
+- html is dangerouslySetInnerHTML. It is for the output of your own highlighter over your own source; markdown a reader wrote goes to code as a string, where it renders as text and cannot be mis-executed.
+- Do not drop copyable to tidy the strip. The button is the reason a reader stops selecting a wrapped command by hand, and on a touch screen a manual selection is most of the interaction.
+
+## Accessibility
+
+- The scrolling body is tabbable and carries role="group" with a name, so its overflow is reachable with a keyboard and the tab stop announces what it is. Deliberately not role="region": that is a landmark, and a page with two code samples would put two of them in the landmark map under one name.
+- The copy button is an iconOnly Button with a required aria-label that becomes “Copied” on success — the state change is announced rather than only drawn.
+- The copy control clears the 44px pointer target on a coarse pointer, where the compact strip alone would not (WCAG 2.5.5).
+
+## CodeBlock
+
+A multi-line snippet, on a plate, with a way to take it away. The strip along the top carries the title, the language and the copy button, and it is there whenever there is anything to put in it. It is deliberately not a hover affordance: a control that appears on hover does not exist on a touch screen, which is where a reader is most likely to want the snippet and least able to select it by hand. Line numbers live INSIDE their own line's row rather than in a parallel gutter column. Two columns sharing a line-height align right up until one of them wraps, ships a different font, or scrolls on its own; a number that is a child of the line it numbers cannot come apart from it. The cost is that a number scrolls away with its line: it is inside the scrolling box, not in a gutter beside it. A gutter that stayed put would be a second column to keep in sync, which is the failure this avoids. The body is a focusable, named `role="group"`, and both halves of that are load-bearing. Focusable, because a scrollable box whose contents are not themselves focusable is unreachable by keyboard — there is nothing to Tab to and therefore no way to press an arrow key at it, so the right-hand half of a long line does not exist for anyone not using a mouse. Named, because a tab stop that announces nothing lands the reader in an anonymous box and leaves them to work out what they have arrived in. `group` rather than `region`, and that is the deliberate half. A region is a LANDMARK — one of the handful of major sections a reader navigates a whole page by — and a snippet is not one of those. Three fenced blocks in one article would put three landmarks called "Code" into that map, which is exactly the noise the `landmark-unique` rule exists to catch, and it would push the page's real landmarks down a list nobody can now skim. `group` carries the same accessible name to the same reader on the way in, and carries it nowhere else. For a function name inside a sentence, reach for `Code`.
+
+### Props
+
+- `code` (required) — `string`. The snippet, verbatim. Required even when `html` is supplied, and that is the point: this is what the copy button puts on the clipboard. A block that copies its own rendered markup hands the reader a wall of `<span>`s, and one that copies `textContent` scraped back out of the DOM is a single non-breaking space away from pasting something that does not run.
+- `title` — `string`. A filename or a caption, printed at the start of the strip.
+- `lang` — `string`. The language, printed at the end of the strip. Optional, and the omission is visible rather than silent: a block with no language gets no label instead of claiming a wrong one. A code block that does not say what it is written in makes the reader infer it from the syntax, which is the one thing they came to the block to learn.
+- `maxHeight` — `number | string`. Caps the block's height and scrolls past it. A number is pixels; a string is any CSS length (`'24rem'`, `'50vh'`). The body scrolls in both axes and is focusable, so what is past the fold stays reachable with a keyboard rather than merely present in the DOM.
+- `copyable` — `boolean` default `true`. Drops the copy button, for a block nobody is meant to run.
+- `label` — `string`. Names the scrollable body for a screen reader. Defaults to `title`, and to "Code" when there is not one.
+- `className` — `string`.
+- `html` — `undefined`. Absent on this form; `string` on the other. Pass pre-highlighted markup — Shiki's output, run at build time over this same `code` — and the block renders that instead of the plain text. Doing so takes `lineNumbers` and `highlightLines` away with it.
+- `lineNumbers` — `boolean` default `false`. Numbers every line, counting from one.
+- `highlightLines` — `number[]`. Lines to band, counting from one. A number past the end of the snippet is ignored rather than throwing — the usual cause is a snippet that got shorter while the annotation did not.
+
+## Examples
+
+```tsx
+<CodeBlock code="pnpm add
+<CodeBlock
+  title="cn.ts"
+  lang="ts"
+  lineNumbers
+  highlightLines={[2]}
+  maxHeight="24rem"
+  code={source}
+/>
+// Highlighted at build time by the site's own Shiki pass.
+<CodeBlock code={source} html={highlighted} lang="tsx" />
+```

package/dist/agent/Collapsible.md

@@ -4,7 +4,7 @@ One thing that opens, on its own.
 
 - Group: Navigation
 - Import: `import { Collapsible } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/collapsible/
 - Related: accordion
 
@@ -12,6 +12,27 @@ One thing that opens, on its own.
 
 The difference from Accordion is arithmetic: an accordion is a SET and can coordinate. An accordion of one manages a value nobody reads.
 
+## Anatomy
+
+- **Root** (required) — Collapsible — Radix’s root, holding open or defaultOpen and drawing nothing. CollapsibleSection is the same root with the trigger and panel already composed, and is what most call sites want.
+- **Trigger** (required) — A plain <button> carrying aria-expanded and aria-controls — and, unlike an accordion row, wrapped in no heading at all. Nothing here appears in a document outline.
+- **Marker** (required) — A chevron rotating 180°, chosen against the accordion’s plus on purpose: this reveals more of the same thing, where an accordion row opens a distinct answer.
+- **Panel** — Radix’s Content, unmounted while closed and animating on the measured --radix-collapsible-content-height, so a long group and a short one take the same time. A bare div: no region role and no name of its own, again unlike an accordion’s. Both this and the loose CollapsibleContent carry data-m22-animated, so the two agree under prefers-reduced-motion rather than only one of them honouring it.
+
+## Best practices
+
+### Do
+
+- Give the trigger a heading of your own when the section is a section: Accordion wraps every trigger in an <h3> and this deliberately wraps none, so a page built from CollapsibleSections has nothing for heading navigation to stop at.
+- Reach for the loose CollapsibleTrigger and CollapsibleContent only when the header has to hold more than a title — a count on one side, a switch on the other. They exist so that call site does not go to Radix and re-derive aria-expanded by hand.
+- Set defaultOpen when what it hides is why the reader came: the closed panel is unmounted rather than hidden, so its text is not in the page for find-in-page, for a print, or for anything reading the rendered DOM.
+- Control it with open and onOpenChange when something outside has to open it — a sidebar group that must expand for the route living inside it cannot be told to from a component that owns its own state.
+
+### Don’t
+
+- Do not build a set out of these: two sections cannot close each other, so the reader ends with every one open and a column to scroll past. That coordination is the whole of what Accordion’s single value buys.
+- Do not flip the title between “Show more” and “Show less”: aria-expanded on the trigger already carries the state, so the row is announced with its state twice and with a new name each time it is pressed.
+
 ## Keyboard
 
 - Enter / Space — Opens or closes it.

package/dist/agent/ColorPicker.md

@@ -0,0 +1,75 @@
+# ColorPicker
+
+A colour, chosen or typed.
+
+- Group: Forms
+- Import: `import { ColorPicker } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/color-picker/
+- Related: field, input, popover
+
+## When to reach for it
+
+A person is choosing the colour. A colour that is merely being SHOWN is a swatch, and a set of fixed brand colours is a RadioGroup — a picker offers sixteen million answers to a question with six.
+
+## Anatomy
+
+- **Trigger** (required) — The closed control: a swatch, then the value as text, in the same box as Input and Select. Named by its label AND by its own value, so a reader hears “Brand colour, #a78bfa” rather than either half.
+- **Swatch** — The colour over a checkerboard, so a half-transparent value reads as transparent rather than as a paler colour.
+- **Notation strip** — Hex, OKLCH and Display P3, as a single-value ToggleGroup. It changes what onValueChange emits, not what the colour is — and hex and P3 are bounded, so switching to one of them fits the colour to that gamut on the way out.
+- **Field** (required) — The plane: chroma across, lightness up. Each ROW is normalised to the most chroma that exists at that lightness and hue, so the whole surface is reachable instead of a lens of colour inside bands of clipped duplicates. Underneath it are two real sliders rather than key handlers on a canvas, which is what gives it arrows, Home, End and an announced position.
+- **Hue track** — A ramp taken at the lightness and chroma already chosen, not a generic rainbow — so the strip shows the hues of THIS colour rather than of some other one.
+- **Opacity track** — Transparent to the current colour, over the same checkerboard as the swatch.
+- **CSS box** — The value as text. Accepts hex, rgb(), hsl(), oklch() and color(display-p3 …) in both syntaxes, and paints itself invalid on anything else.
+
+## Best practices
+
+### Do
+
+- Wrap it in a Field. The trigger is a button, which a label binds to and clicks through — one of the few composites where that works without help.
+- Pass the notation you want back. The panel emits in whatever notation the value arrived in until somebody changes it in the strip, so a defaultValue of "#a78bfa" keeps a consumer in hex.
+- Reach for this over <input type="color"> when the colours are being TUNED. The native picker works in HSV, where a row of constant lightness visibly darkens as it saturates — so a reader building a palette is fighting the instrument. OKLCH is the space where two colours at the same height genuinely match.
+
+### Don’t
+
+- Do not pass a named colour. Hex, rgb(), hsl(), oklch() and color(display-p3 …) parse; "rebeccapurple" does not, and the box will show it as invalid. Resolving names needs a table of every CSS keyword or a live DOM, and a picker that takes some names and not others is worse than one that takes none.
+- Do not read the emitted string as a fixed notation. It is whatever the strip is set to, so a consumer that slices a "#" off the front breaks the first time a reader picks OKLCH.
+- Do not use it to pick text or background colour and call the result accessible. Nothing here measures contrast; a picker that lets a reader choose #eeeeee for body copy is doing exactly what it was asked.
+
+## Accessibility
+
+- label is required. The trigger shows a value, and a value is not a name.
+- The plane is a group of two real sliders — Chroma and Lightness — each announced with a percentage, so the 2D surface is operable and reported rather than merely clickable.
+- The focus ring is drawn on the plane, because the sliders that take the focus are visually hidden and the browser’s own ring is clipped away with them.
+- Alpha is doubled by a checkerboard everywhere it is shown, so transparency is not carried by lightness alone.
+
+## Keyboard
+
+- Enter / Space — Opens the panel.
+- ← / → — Moves the focused axis or track by one step.
+- Home / End — Jumps that axis or track to its ends.
+- Escape — Closes the panel; focus returns to the trigger.
+
+## ColorPicker
+
+A colour, chosen or typed. The panel works in OKLCH, and that is the reason to reach for this rather than `<input type="color">`. In HSV — which is what the native picker and most libraries use — dragging along a row of constant "lightness" walks through colours the eye reads as getting darker, so a reader tuning a palette is fighting the instrument. OKLCH's lightness is the one a person sees, so two colours at the same height on the plane genuinely match, and the hue strip stays at the lightness already chosen instead of showing a rainbow that belongs to some other colour. The plane is normalised to the gamut ROW BY ROW: its right edge is the most chroma that exists at that lightness and hue, so the whole surface is reachable rather than a lens of colour inside a field of clipped duplicates. **What it accepts.** Hex, `rgb()`, `hsl()`, `oklch()` and `color(display-p3 …)`, in both syntaxes. Named colours are not accepted: resolving them needs a table of every CSS name or a live DOM, and a box that takes "rebeccapurple" but not "papayawhip" is worse than one that takes neither. **Keyboard.** The plane is a group of two real sliders — chroma across, lightness up — so the arrows move it and a screen reader announces where it is. That is the part a 2D canvas usually leaves out, and leaving it out makes the control unusable rather than merely awkward.
+
+### Props
+
+- `label` (required) — `string`. Names the control. Required — the trigger shows a colour, and a colour is not a name. Announced together with the value, the way `Select`'s is: a reader hears "Brand colour, #a78bfa". Inside a `Field` with a label, that label is used and this one is not repeated.
+- `value` — `string`. The colour, as any absolute CSS colour string.
+- `defaultValue` — `string` default `'#000000'`.
+- `onValueChange` — `(value: string) => void`. Fires with a CSS colour string in whichever notation the panel is set to — so the notation a caller passes in is the notation they get back until somebody changes it in the panel.
+- `disabled` — `boolean`.
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `className` — `string`.
+- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
+- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
+- `aria-invalid` — `boolean | 'true' | 'false'`. The spelling a form library sets; read together with `invalid`.
+- `aria-required` — `boolean`. Announced on the trigger. A `Field` sets it from `required`.
+
+## Examples
+
+```tsx
+<Field label="Brand colour"><ColorPicker label="Brand colour" defaultValue="#a78bfa" /></Field>
+```

package/dist/agent/Combobox.md

@@ -4,7 +4,7 @@ A select you can type into.
 
 - Group: Forms
 - Import: `import { Combobox } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/combobox/
 - Related: select, command
 
@@ -12,10 +12,32 @@ A select you can type into.
 
 Past roughly a dozen options. Below that a native Select is better: the platform picker on a phone, typeahead for free, no JavaScript.
 
+## Anatomy
+
+- **Trigger** (required) — A <button role="combobox"> named by the label and its own summary together, carrying aria-expanded. Its text truncates rather than wrapping, so the field keeps its height whatever is chosen.
+- **Summary** — The trigger’s text: the placeholder, or up to two chosen labels joined by commas, then “n selected”. Counting past two is what stops a multiple picker reflowing the form on every choice.
+- **Clear** — A <span role="button"> beside the chevron, on multiple with something chosen. A span rather than a nested <button>, which is invalid inside the trigger and which browsers reparent out of the field.
+- **Filter field** — cmdk’s input inside the panel. It is named through the Command wrapper as “label: searchPlaceholder”, because aria-labelledby beats aria-label and naming the input directly did nothing.
+- **Option row** — A tick for single, a fillable box for multiple, then the label. emptyMessage takes the list’s place when the filter matches nothing.
+
+## Best practices
+
+### Do
+
+- Spell “nothing chosen” as an empty string when the value is controlled. value={undefined} is precisely how this component decides it is UNCONTROLLED, so clearing that way hands it back its own state and it stops following the parent.
+- Put readable text in label and anything else worth matching in keywords: cmdk scores against the option’s value too, so a list keyed by UUID is being ranked on a string no reader will ever type.
+- Say what WOULD match in emptyMessage. The default tells a reader the filter ran and nothing about which of the four hundred options they should have typed instead.
+
+### Don’t
+
+- Past two choices the trigger stops naming them — it announces “Tags, 3 selected”, and WHICH three is only in the panel. Print them beside the field when the choice has to be checkable without opening it.
+- Do not hand it thousands of options. Nothing here virtualises: every option in the array renders into the panel on open and stays there behind the filter, so the list length is a DOM cost, not a search cost.
+- A disabled option is not a hidden one — it still renders and still matches the filter, so a reader can type its exact name, watch it come up, and be unable to pick it with no reason offered.
+
 ## Accessibility
 
 - The highlight moves through aria-activedescendant while focus stays in the input — the ARIA combobox pattern. Hand-rolled comboboxes move focus into the list, and the typed text stops being editable.
-- label is required: the trigger prints a value, and a value is not a name.
+- label is required, and it is announced with the summary rather than instead of it: the trigger reads “Tags, 3 selected”. Inside a Field the FIELD’s label supplies the name half and the label prop is neither rendered nor announced on the trigger — it still names the clear control, as “Clear Tags”, so it has to stay truthful even where the trigger no longer says it.
 
 ## Keyboard
 
@@ -35,12 +57,16 @@ A select you can type into, choosing one or several. The line against `Select` i
 - `defaultValue` — `string`.
 - `onValueChange` — `(value: string) => void`.
 - `options` (required) — `ComboboxOption[]`.
-- `label` (required) — `string`. Names the control. Required — the trigger's text is a value, not a label.
+- `label` (required) — `string`. Names the control. Required — the trigger's text is a value, not a label. Announced together with the summary rather than instead of it, so a reader hears "Tags, 3 selected". Inside a `Field` with a label, that label names the trigger and this one is not repeated.
 - `placeholder` — `string` default `'Select…'`. Shown on the trigger when nothing is chosen.
 - `searchPlaceholder` — `string` default `'Search…'`. Placeholder inside the filter field.
 - `emptyMessage` — `string` default `'Nothing matches.'`. Shown when the filter matches nothing. Say what WOULD match.
 - `disabled` — `boolean` default `false`.
 - `className` — `string`.
+- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
+- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
+- `aria-invalid` — `boolean | 'true' | 'false'`. Paints the resting border with `--danger` and is announced. A `Field` sets it from `error`.
+- `aria-required` — `boolean`. Announced on the trigger. A `Field` sets it from `required`.
 
 ## Examples
 

package/dist/agent/Command.md

@@ -4,10 +4,33 @@ A filterable list of actions — the ⌘K surface.
 
 - Group: Overlays
 - Import: `import { Command } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/command/
 - Related: combobox, dialog
 
+## Anatomy
+
+- **Input** (required) — CommandInput, the combobox, with the search glyph and a hairline under it. A hard 52px tall rather than a --control-h token, so it does not move with data-density.
+- **List** (required) — CommandList, capped at 18rem inline and raised to 26rem inside CommandDialog, scrolling on its own six-pixel hairline bar.
+- **Item** — A row: an icon ELEMENT, the label, an optional meta note and a shortcut printed as a Kbd. The highlighted row takes --accent-muted and a leading accent rule, because a fill alone is hard to catch while scrolling.
+- **Empty** — CommandEmpty. cmdk renders an empty state only if one exists in the tree, so without it an unmatched filter leaves the input over a blank strip.
+- **Footer** — CommandFooter and its CommandHint rows. A palette is a keyboard surface whose keys are invisible; this is the only place they get printed.
+
+## Best practices
+
+### Do
+
+- Reach for CommandDialog, not the bare Command. The root is an inline bordered box with no scrim, no focus trap and no Escape handling of its own, so a palette built from it alone stays open until something else closes it.
+- Always render CommandEmpty. cmdk shows an empty state only when one is present, so the palette that omits it answers a filter matching nothing with an input above a blank strip and no explanation.
+- Pass CommandItem an icon element — icon={<Search size={16} />} — when the glyph needs its own size or colour, and the component — icon={Search} — when it does not. Both spellings work here and in DropdownMenuItem; they used to be the reverse of each other one import apart.
+- Bind ⌘K yourself and then print it: nothing in this component listens for a key, so the palette has no shortcut until the app adds a keydown handler, and a CommandFooter is where the reader finds out it exists.
+
+### Don’t
+
+- Do not pass value to CommandItem unless the value is what a reader would type — cmdk filters on value first and only falls back to the row’s own text when there is none, so an id passed as the value makes the visible label unsearchable. Pass the label’s words as keywords when the id has to stay the value, which is what SearchableMenu does.
+- CommandDialog renders with hideTitle and showClose={false}, so the palette has no visible heading and no visible close: Escape and the scrim are the only exits and neither announces itself. Print Escape in a CommandFooter rather than assuming it is known.
+- Do not expect the palette to follow data-density — CommandInput is a hard 52px, not a --control-h token, so its field stays put while every other control in the app shrinks under compact.
+
 ## Accessibility
 
 - The list filters as you type, the highlight moves with the arrow keys, and focus stays in the input. That last part is the ARIA combobox pattern and the part a home-made palette gets wrong.
@@ -58,7 +81,7 @@ A divider between groups. Marked presentational, because ARIA permits a `listbox
 ### Props
 
 - `shortcut` — `string`. A shortcut printed at the end of the row.
-- `icon` — `ReactNode`. A leading glyph. Pass the icon element, sized 16. It is what makes a long list scannable — the eye sorts by shape before it reads, and forty identical rows of text defeat that.
+- `icon` — `LucideIcon | ReactNode`. A leading glyph. Either spelling — `icon={<Settings size={16} />}` passes the element, `icon={Settings}` passes the component and this sizes it. It is what makes a long list scannable — the eye sorts by shape before it reads, and forty identical rows of text defeat that.
 - `meta` — `ReactNode`. A quiet note at the end of the row — what kind of thing this is, or its current state. Not a description: a palette that prints a sentence per row stops being scannable at about six of them.
 
 Also accepts: `ComponentProps<typeof CommandPrimitive.Item>`.

package/dist/agent/ComposedChart.md

@@ -4,7 +4,7 @@ Bars and lines over one axis — the volume, and the rate it moved at.
 
 - Group: Charts
 - Import: `import { ComposedChart } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/composed-chart/
 - Related: bar-chart, line-chart
 
@@ -12,6 +12,29 @@ Bars and lines over one axis — the volume, and the rate it moved at.
 
 Two measures that share a scale. Two that do NOT share one belong in two charts or indexed to a common base: there is no second y-axis here, on purpose.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, named by title, with the composed marks inside one measured ChartContainer.
+- **The single value axis** (required) — <ComposedChart.YAxis>. One of them is the entire design: there is no dual-axis affordance and no second scale to configure, so the two measures are read against the same numbers.
+- **Bars** — <ComposedChart.Bar>, the volume. Custom-shaped like BarChart’s, with the same transparent hit rectangle and the same grow-in anchored to the chart’s start rather than to each bar’s mount, so a hover cannot replay it.
+- **Lines** — <ComposedChart.Line>, the rate. It inherits the chart’s curveType and reveal, so bars and line arrive as one figure rather than as two animations on two clocks.
+- **Column highlight** — enableHoverHighlight dims every mark outside the hovered column, driven by the chart’s own onMouseMove index rather than by each mark’s hover — which is what makes a bar and a line in the same column light together.
+- **Brush and toolbar** — <ComposedChart.Brush> in the container footer and <ComposedChart.Toolbar> above the plot. They drive one window, so a brushed range and a zoomed range cannot disagree about what is on screen.
+- **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.
+
+## Best practices
+
+### Do
+
+- Index two measures to a common base — both as a percentage of January, say — when they do not share a scale. That is the substitute for the second axis this component deliberately does not have.
+- Compose <ComposedChart.Legend> above two marks. A bar and a line at --series-1 and --series-2 differ by one step of grey and a shape, and only the shape is self-describing.
+- Set enableHoverHighlight on every mark or on none. Set on one, the hovered column dims half of itself, which reads as a rendering fault rather than as emphasis.
+
+### Don’t
+
+- Do not smuggle a second y-axis in through chartProps or a yAxisId on <ComposedChart.YAxis>. Recharts allows it; the component’s claim is that it does not. Two scales chosen independently let the author decide where the lines cross, which is the single most misleading thing a chart can do — and it always works, on any two series.
+- Do not assume the audio reading is here. AreaChart, BarChart and LineChart each carry a Sonify slot and this one does not, so a reader who has been listening across a dashboard falls back to the sr-only table — which is why hideDataTable is the prop not to set on this chart.
+
 ## Accessibility
 
 - title is required; the rows are also rendered as a visually hidden table.
@@ -36,7 +59,8 @@ Bars and lines over one axis — the shape for "the volume, and the rate it move
 - `animationType` — `ChartRevealType` default `'forward'`.
 - `barGap` — `number`.
 - `barCategoryGap` — `number`.
-- `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/ContextMenu.md

@@ -4,7 +4,7 @@ The menu a right-click opens.
 
 - Group: Overlays
 - Import: `import { ContextMenu } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/context-menu/
 - Related: dropdown-menu
 
@@ -12,6 +12,29 @@ The menu a right-click opens.
 
 Never as the only way to reach an action. Touch users, trackpad users and keyboard users may have no way to open it.
 
+## Anatomy
+
+- **Trigger** (required) — The region a secondary click opens the menu over. Radix wraps children in its own inline span unless you pass asChild, and sets -webkit-touch-callout: none on it so the OS text callout does not fire first.
+- **Panel** (required) — The portalled menu, placed at the POINTER rather than against the trigger — there is no side or align to set here, only the 8px collision padding that keeps it inside the viewport or the OverlayContainer frame.
+- **Item** — A row, taking the same icon, destructive and disabled props as DropdownMenuItem — icon in either spelling — and highlighting on the same data-highlighted.
+- **Label** — A mono eyebrow, on its own, and visual only. ContextMenuGroup 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.
+- **Separator** — A hairline between groups, as a real role="separator".
+
+## Best practices
+
+### Do
+
+- Pass asChild and hand it the element itself: without it Radix inserts a span between you and your child, and that span becomes the flex or grid item while your card is laid out inside it as inline content.
+- Build the same array of actions into a DropdownMenu behind an overflow button — the two take identical icon, destructive and disabled props, so one list feeds both and the right-click becomes the shortcut rather than the only door.
+- Wrap the subtree in OverlayContainer when the right-clickable region lives in a scrolling or bounded frame: this is the one panel whose position the reader personally chose, and a flip against a viewport edge they cannot see lands it somewhere they did not point.
+
+### Don’t
+
+- Do not read “no touch support” as the whole story: Radix opens the menu on a 700ms long press for touch and pen, but cancels the moment the pointer moves — so on a scrollable list the long press and the scroll gesture compete and the scroll usually wins.
+- A bare ContextMenuLabel 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. ContextMenuGroup renders both halves and wires them together.
+- Radix defaults modal to true here too, so the page behind is scroll-locked and pointer-inert while the menu is open — a right-click menu over a long list stops the list moving under it, which is right for a short action list and wrong for anything the reader must scroll to answer.
+
 ## Keyboard
 
 - Shift / F10 — Opens the menu from the keyboard, where the platform supports it.
@@ -34,8 +57,8 @@ A row. Highlight follows `data-highlighted`, which covers hover and keyboard.
 
 ### Props
 
-- `icon` — `LucideIcon`.
-- `destructive` — `boolean` default `false`.
+- `icon` — `LucideIcon | ReactNode`. Optional leading icon. Either spelling — `icon={Copy}` passes the component and this sizes it, `icon={<Copy size={16} />}` passes the element and this places it.
+- `destructive` — `boolean` default `false`. Paints the row as destructive. Use for delete, revoke, disconnect.
 
 Also accepts: `ComponentProps<typeof ContextMenuPrimitive.Item>`.
 
@@ -45,7 +68,17 @@ Hairline divider between groups.
 
 ## ContextMenuLabel
 
-Mono eyebrow heading for a group.
+Mono eyebrow heading, on its own. Visual only: Radix renders it as a bare `<div>` with no role. Reach for `ContextMenuGroup` when the eyebrow is a HEADING over rows; this is right for a line that heads nothing.
+
+## ContextMenuGroup
+
+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, so a sighted reader saw 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.
+
+### Props
+
+- `label` — `ReactNode`. The eyebrow over the rows, and the group's accessible name.
+
+Also accepts: `ComponentProps<typeof ContextMenuPrimitive.Group>`.
 
 ## Examples
 

package/dist/agent/DataflowFigure.md

@@ -4,7 +4,7 @@ A pipeline: where data comes from, what happens to it, and who ends up with it.
 
 - Group: Diagrams
 - Import: `import { DataflowFigure } from '@misoto22/design/diagrams'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/dataflow-figure/
 - Related: architecture-figure, lifecycle-figure
 
@@ -12,6 +12,27 @@ A pipeline: where data comes from, what happens to it, and who ends up with it.
 
 Structurally close to an architecture map, read for a different question. classification gets its own chip because a governance reviewer is looking for exactly that.
 
+## Anatomy
+
+- **Figure shell** (required) — The frame around the picture. What a pipeline hands it is a flow list with the classification folded in — "clickstream — PII touch" — so the fact the diagram was opened for reaches a reader who never sees the chip.
+- **Stage heading** (required) — One mono caption per stage on a rule across the top. It is the axis: a node’s stage is how far along the pipeline it sits, so "has this been aggregated yet" is answered by looking up rather than by tracing arrows.
+- **Node plate** (required) — One box per node, placed by stage across and row down. The row pitch leaves a clear band between two boxes in the same column, which is where a line and its wording go.
+- **Flow** — A routed line with a single arrowhead, at its to end. It is the direction claim the whole figure is read for.
+- **Classification chip** — classification, printed in mono under the wording rather than inside it. "clickstream" and "clickstream / PII touch" are two different facts, and only one of them is what a governance review came for.
+
+## Best practices
+
+### Do
+
+- Put the governance fact in classification rather than in the label. It prints as its own chip on the line and is appended to the flow’s summary line, so it survives both a reader who is scanning the picture and one who only has the text.
+- Keep stage inside the stages you declared. A node’s x is computed from its own stage index rather than looked up, so a node at stage 5 beside four stages is drawn a full column past the last heading, under no heading at all — development prints DIAGRAM_STAGE_OUT_OF_RANGE, and the summary files it under a band called outside the declared stages rather than beside the nodes the axis does label.
+- Write a two-way exchange as two flows. Every line carries a head at its to end only, so one flow between a service and its cache says data moves one way, whatever the label claims about the round trip.
+
+### Don’t
+
+- via, channelX and channelY are never honoured here — a data-flow node is always placed by stage and row, so an author’s waypoints refer to a grid this renderer did not build. They are dropped and every line is routed from scratch: the specification still typechecks and the picture is not the one it drew.
+- Watch the fan-in. Lines sharing a face are spread evenly across it, and an arrowhead is 11 user units wide against a plate about 55 units tall — so four lines into one face is where the heads meet, and the fifth and sixth arrive as one thick mark. A pipeline at that density wants splitting, not more edges.
+
 ## Accessibility
 
 - A flow’s classification is folded into its summary line, so "clickstream — PII touch" reaches a reader who cannot see the chip.