@misoto22/design 0.7.0 → 0.9.0

package/dist/agent/Table.md

@@ -4,7 +4,7 @@ A ruled data table — alignment, sorting and rules all per column.
 
 - Group: Data
 - Import: `import { Table } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/table/
 - Related: card, figure-band
 
@@ -12,6 +12,28 @@ A ruled data table — alignment, sorting and rules all per column.
 
 Alignment is per column and numbers belong at the end edge, so digits line up. Sorting is opt-in per column: a table where every header is a button invites sorting a column the data cannot be ordered by.
 
+## Anatomy
+
+- **Scroll region** (required) — The focusable <div role="region"> around the table, named by caption. It carries the border setting and the density attribute, and it is what scrolls sideways — so the table exceeds the measure and the page does not. It is also positioned, which is what keeps an sr-only label inside a cell from resolving against the document and dragging the page sideways with it.
+- **Caption** (required) — A real <caption>, visually hidden unless showCaption prints it as an eyebrow above the table. The same string is the scroll region’s accessible name, so it is heard on the way in and again from the table.
+- **Column label** (required) — TH — mono and uppercase so it never reads as data, aligned per column, and always emitting scope="col" unless a call site overrides it.
+- **Sort control** — On a sortable header only: a <button> INSIDE the th, with ArrowUp, ArrowDown or a dimmed ChevronsUpDown beside the label, and aria-sort on the th set from sortDirection.
+- **Cells** (required) — TD — top-aligned at --ink-2, sharing --table-pad-x with the header so the columns line up, and taking their row height from --table-pad-y, which density halves from 14px to 8px.
+
+## Best practices
+
+### Do
+
+- Bound the height from outside for stickyHeader: className and every other prop land on the <table>, not on the scrolling div around it, so only a constraining parent — a flex column with a height — gives that div something to stick within. A max-height on a plain wrapper does not, and the header simply travels with the page.
+- Pass scope="row" on a row’s first cell — TH writes scope="col" and your props are spread after it, so the override lands; without it every row header claims to head a column and a cell traced back reaches the wrong label.
+- Reset the other columns to sortDirection="none" when the sort moves: each header carries its own aria-sort and nothing coordinates them, so a table can end up announcing two columns as sorted at once.
+- Give TD the same align as its TH — alignment is per cell, not inherited down the column, and end-aligned numbers under a start-aligned label is a column whose digits stop lining up with their own heading.
+
+### Don’t
+
+- aria-sort tells a reader how the table is ordered once they reach the header; it announces nothing at the moment the button is pressed. A table that re-orders under a screen reader has to say so somewhere the reader already is, or every row silently changes and nothing is said.
+- Do not expect it to reflow on a phone: nothing stacks, the region scrolls sideways behind a hairline scrollbar, and a column past the fold is reachable only by a reader who works out that it scrolls. Eight columns at 375px wants a different presentation, not a smaller font.
+
 ## Accessibility
 
 - caption is required: an unnamed table on a page with three tables is unnavigable.
@@ -19,6 +41,7 @@ Alignment is per column and numbers belong at the end edge, so digits line up. S
 - A sortable header is a button INSIDE the th, not a click handler on the cell — a cell with an onClick is not focusable and not announced, so the sort would exist only for a mouse.
 - aria-sort is set from sortDirection, which is the only way a screen reader learns the table is ordered at all.
 - No zebra striping at any border setting: in a monochrome system a striped row is a second surface competing with the page ground.
+- The scroll region is a containing block, so a visually-hidden label in a cell stays inside the table rather than escaping it and widening the page.
 
 ## Keyboard
 
@@ -27,14 +50,14 @@ Alignment is per column and numbers belong at the end edge, so digits line up. S
 
 ## Table
 
-A ruled data table. Wrapped in its own horizontally scrolling container, because a table is the one block that legitimately exceeds the measure — and a page that scrolls sideways as a whole is a layout bug, while a table that does is a table. That container is focusable, and it has to be. A scrollable region whose contents are not themselves focusable is unreachable by keyboard: there is no element to Tab to and therefore no way to press an arrow key at it, so the columns past the fold simply do not exist for anyone not using a mouse. No zebra striping at any border setting. In a monochrome system a striped row is a second surface competing with the page ground, and the hairline between rows is already enough to track a line across.
+A ruled data table. Wrapped in its own horizontally scrolling container, because a table is the one block that legitimately exceeds the measure — and a page that scrolls sideways as a whole is a layout bug, while a table that does is a table. That container is focusable, and it has to be. A scrollable region whose contents are not themselves focusable is unreachable by keyboard: there is no element to Tab to and therefore no way to press an arrow key at it, so the columns past the fold simply do not exist for anyone not using a mouse. It is also POSITIONED, which is not decoration. `sr-only` is `position: absolute`, so a visually-hidden label in a cell resolves against the nearest positioned ancestor — and with none between it and the document, it escapes the scroll container and every `overflow-hidden` around it, and widens the page by however far the table happens to be scrolled. No zebra striping at any border setting. In a monochrome system a striped row is a second surface competing with the page ground, and the hairline between rows is already enough to track a line across.
 
 ### Props
 
 - `caption` (required) — `string`. Describes the table for a screen reader, which cannot see the heading above it. Rendered as a visually-hidden `<caption>` — required, because an unnamed table in a page with three tables is unnavigable.
 - `showCaption` — `boolean` default `false`. Prints the caption instead of hiding it.
 - `stickyHeader` — `boolean` default `false`. Pins the header row while the body scrolls. Needs a bounded height on the container — otherwise the page scrolls, not the table, and nothing sticks.
-- `borders` — `TableBorders` default `'rows'`. Which rules to draw. See .
+- `borders` — `TableBorders` default `'rows'`. Which rules to draw. See TableBorders.
 - `density` — `'comfortable' | 'compact'` default `'comfortable'`. Tightens the row padding, for a table that is mostly numbers.
 
 Also accepts: `TableHTMLAttributes<HTMLTableElement>`.
@@ -62,6 +85,8 @@ Also accepts: `Omit<ThHTMLAttributes<HTMLTableCellElement>, 'align'>`.
 
 ## TD
 
+A body cell. TOP-aligned, and that is a choice about which kind of table is the common one here: a cell holding a paragraph. Top is what lines the first lines of a row up with each other, and centring a two-word term against a four-line description puts the term in the middle of nothing. It is the wrong default for the other kind — a row of one-line values with a control in it. A 36px button next to 16px of text makes a 52px row, and every other cell then hangs at the top of it with twenty pixels of nothing underneath, which reads as a column that has slipped. Pass `className="align-middle"` on those rows; the data-table template does.
+
 ### Props
 
 - `align` — `TableAlign` default `'start'`. Which edge the cell's contents sit against. Match the column's header.

package/dist/agent/Tabs.md

@@ -4,10 +4,32 @@ One strip, several panels.
 
 - Group: Navigation
 - Import: `import { Tabs } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/tabs/
 - Related: accordion
 
+## Anatomy
+
+- **Root** (required) — Tabs — Radix’s root, re-exported. It draws nothing and owns everything: value or defaultValue, and activationMode. With neither value nor defaultValue no tab is selected and no panel is mounted.
+- **Tab strip** (required) — TabsList — the role="tablist" row, sitting on one hairline rule and scrolling on its own axis with scroll-slim. It has no accessible name unless you give it one.
+- **Tab** (required) — TabsTrigger, at the md control height with its label on one line. Every tab carries the 2px active marker, transparent until it is the selected one; the marker is pulled onto the strip’s own border with -mb-px so the two share a line rather than stacking into a 3px edge.
+- **Panel** — TabsContent, paired to its tab by matching value. Mounted only while it is the selected one, and marked data-m22-animated so its entrance is dropped for a reader who asked for less motion.
+
+## Best practices
+
+### Do
+
+- Give the root a defaultValue or a value: with neither, nothing matches, every panel stays unmounted, and the page renders a strip above an empty space with nothing to say what is missing.
+- Match each trigger’s value to a panel’s value exactly — the pairing is string equality, and a typo is not an error but a tab that opens onto nothing.
+- Pass activationMode="manual" when a panel fetches or renders something expensive: the default is automatic, so ← and → select as they move and arrowing across four tabs starts four loads before the reader has stopped.
+- Give TabsList an aria-label on a page with more than one set: Radix names the tablist after nothing, and two unnamed tablists are two “tab list”s a reader cannot tell apart.
+
+### Don’t
+
+- An unselected panel is unmounted, not hidden — find-in-page cannot reach its text, a print takes only the panel that was open, and a half-filled form in another tab has lost what was typed into it by the time the reader comes back.
+- The selected tab lives in React state, not in the URL: a reader who reloads or shares the page lands on the first panel, so anything worth linking to needs value lifted into a query parameter.
+- Tabs are not a way to fit more in: the strip scrolls silently, and a sixth tab past the fold looks exactly like a page that only has five.
+
 ## Accessibility
 
 - The strip scrolls rather than wrapping: a wrapped second row moves every tab below it and the reader loses the one they were about to click.
@@ -33,7 +55,7 @@ One tab. The active marker is a 2px ink rule pulled onto the strip's own border
 
 ## TabsContent
 
-The panel paired to a  by matching `value`.
+The panel paired to a TabsTrigger by matching `value`.
 
 ## Examples
 

package/dist/agent/Tag.md

@@ -1,35 +1,66 @@
 # Tag
 
-A subject label — a topic, a technology, a filter facet.
+A subject label — a topic, a technology, a filter facet — that filters with onClick and is dismissed with onRemove.
 
 - Group: Display
 - Import: `import { Tag } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/tag/
-- Related: badge
+- Related: badge, status-pill
 
 ## When to reach for it
 
-Several sit together and the reader scans them. One fact about one record is a Badge.
+Several sit together and the reader scans them. One fact about one record is a Badge. A chip the reader can toggle or dismiss is this one with onClick or onRemove, not a fourth component.
+
+## Anatomy
+
+- **Chip** (required) — The <span>: the same --radius-sm corner, the same 10px by 4px padding and the same 12px mono as a Badge, with no border of its own.
+- **Ground** (required) — --stone at rest, --accent once active, cross-fading over --duration-fast. The accent is the system’s one pointer at a choice, which is why it is what selection is drawn in.
+- **Label** (required) — children, in --ink-3-aa — the AA floor rather than a light grey — and in --accent-foreground once active.
+- **Remove button** — On onRemove only: a real <button type="button"> after the label, holding a 12px X and named by removeLabel. The drawn box is 16px, under the 24px WCAG 2.5.8 floor, so an inset pseudo-element takes the hit area out to 24 without changing the drawing or pushing the chips apart.
+- **Filter control** — On onClick only: the chip itself becomes the <button>, carrying aria-pressed from active. Given onRemove as well, the label splits into its own button beside the X — two siblings, never one inside the other — and takes the leading padding with it so the target is the chip up to the X rather than just the words.
+
+## Best practices
+
+### Do
+
+- Filter with onClick, not with a wrapper. The chip becomes the button itself, so the padding is part of the target and the focus ring is drawn around what the reader sees — and a removable chip does not end up with a button inside a button.
+- Pass active on a chip that toggles, and leave it off one that does not. aria-pressed is read off that same value, so the accent fill and the state assistive tech hears cannot drift apart; omitted, nothing is announced, which is the right answer for a chip that navigates rather than toggles.
+- Give a filter row an off state to come back to — active is the accent, and a row in which every tag is active spends the mark that means “this one” on all of them.
+- Name the subject in removeLabel — "Remove Rust filter", not "Remove". It is required alongside onRemove because eight chips whose controls are all called Remove is eight controls a screen reader cannot tell apart.
+
+### Don’t
+
+- It carries no tone at all, so a tag cannot say success or danger. Colouring one in through className puts a hue into the system by hand and leaves the accent as the only thing that still reads as selected.
+- One tag on its own is a Badge that lost its tone. The component is built to be scanned in a row, and a single chip beside a record is one fact about one record.
+- Do not wrap it in a button of your own. Around a removable chip that is a button inside a button — invalid markup a parser splits into siblings, leaving a DOM neither the author nor the accessibility tree expects. onClick is what that wrapper was for.
 
 ## Accessibility
 
-- Presentational. To filter with it, wrap it in a button and pass active, so the focus ring and the pressed state stay with the element that owns them.
+- Presentational until it is given a handler. onClick makes the chip a real button carrying aria-pressed from active, so the focus ring and the pressed state stay on the element that draws them.
+- Both controls are real <button type="button">s and siblings, so Tab reaches each, Enter and Space fire each, and neither submits the form it happens to sit in.
+- removeLabel is required with onRemove and is the button’s whole accessible name — the X itself is aria-hidden.
 
 ## Tag
 
-A subject label — a topic, a technology, a filter facet. Distinct from `Badge`, which carries a state or a count. A tag names what something is ABOUT, so several sit together in a row and the reader scans them; a badge is one fact about one record. Presentational on purpose. To make a tag filter a list, wrap it in a button or a link at the call site and pass `active` — that keeps the focus ring, the pressed state and the keyboard handling with the element that actually owns them.
+A subject label — a topic, a technology, a filter facet — that can filter with `onClick` and be dismissed with `onRemove`. Distinct from `Badge`, which carries a state or a count. A tag names what something is ABOUT, so several sit together in a row and the reader scans them; a badge is one fact about one record. This is where a `Token` component would have gone. It was not built: a token is a tag with a remove button, and the difference between the two is one prop, not one component. The system already ships three things that look alike — `Badge`, `Tag`, `StatusPill` — and a fourth whose whole distinction is an X on the end would be the one a call site picks by coin toss. Presentational until it is given a handler, and the component owns both interactive cases rather than leaving one to a wrapper at the call site. That is not a convenience: a wrapping `<button>` around a chip that already holds the remove `<button>` is a button inside a button, which no parser keeps and no accessibility tree reports the way it was written. Given both, the chip renders the label and the X as SIBLING buttons — the label takes the leading padding with it, so it is the whole of the chip up to the X rather than the words with dead padding around them.
 
 ### Props
 
 - `children` (required) — `ReactNode`.
-- `active` — `boolean` default `false`. Renders the pressed/selected look. Pair with `aria-pressed` on a wrapper button.
+- `active` — `boolean`. Renders the pressed/selected look, and declares the chip a toggle. An interactive chip reads `aria-pressed` off this same value, so the accent fill and the state a screen reader hears cannot drift apart. Leave it off for a chip whose `onClick` navigates or opens something: a control that is neither pressed nor unpressed is better announced as neither than as "not pressed".
+- `onClick` — `() => void`. Makes the chip ITSELF the filter control. This prop exists because the alternative did not survive contact with `onRemove`. The advice used to be to wrap the tag in a button at the call site, which is fine on its own and invalid the moment the chip is also removable: the remove control is a real `<button>`, so the wrapper puts a button inside a button — markup the parser splits into siblings, leaving a DOM neither the author nor the accessibility tree expects. With this the wrapper is never written. The chip carries the click, the focus ring and the pressed state on the element that draws them, and a removable filter chip renders its two controls side by side instead of one inside the other.
+- `onRemove` — `() => void`. Called when the reader dismisses the chip.
+- `removeLabel` — `string`. The remove button's accessible name. Name the subject, not the action.
 
-Also accepts: `HTMLAttributes<HTMLSpanElement>`.
+Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'onClick'>`.
 
 ## Examples
 
 ```tsx
 <Tag>TypeScript</Tag>
-<button type="button" aria-pressed={on} onClick={toggle}><Tag active={on}>Rust</Tag></button>
+<Tag active={on} onClick={toggle}>Rust</Tag>
+<Tag onRemove={() => drop('rust')} removeLabel="Remove Rust filter">Rust</Tag>
+// Both: a filter the reader can toggle and also take out of the row.
+<Tag active={on} onClick={toggle} onRemove={drop} removeLabel="Remove Rust filter">Rust</Tag>
 ```

package/dist/agent/Text.md

@@ -0,0 +1,65 @@
+# Text
+
+The system’s paragraph, on the second rung of the ink ladder.
+
+- Group: Display
+- Import: `import { Text } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/text/
+- Related: heading, article, markdown
+
+## When to reach for it
+
+One paragraph, or one run of text, outside a reading column. A whole column of prose is an Article.
+
+## Anatomy
+
+- **Box** (required) — The element `as` names — a <p> unless told otherwise. It carries the size, the tone and margin: 0, so the spacing between blocks belongs to the surface rather than to the paragraph.
+- **Type step** (required) — size, one of four: xs, sm, base and lead. lead is --fs-item, the bottom rung of the heading ladder, and is the standfirst that carries a piece.
+- **Ink step** (required) — tone, one of three, because the ink ladder has three rungs: body is --ink-2, strong is --ink, muted is --ink-3-aa.
+
+## Best practices
+
+### Do
+
+- Leave tone alone for body copy. The default is --ink-2 on purpose: a page whose paragraphs are all full-strength ink has spent the top of the ladder on its body text and has nothing left for the headings.
+- Use as="span" for a run inside a sentence. A <p> nested inside a <p> is not nesting — the HTML parser closes the outer one and you get two paragraphs and a broken layout.
+- Reach for size="lead" for the standfirst under a title, and stop there. It is --fs-item, the same step an in-card title uses; anything larger is a heading that has not admitted it.
+
+### Don’t
+
+- Do not set spacing on it. Every Text is margin: 0, so a stack of them inside a plain <div> has no rhythm by design — put them in an Article or give the container the gap, or every surface ends up with its own idea of what a paragraph gap is.
+- tone="muted" is --ink-3-aa, never --ink-3. The two look identical on paper and are not the same token: --ink-3 is a translucent tint that takes on whatever is under it, so it clears AA on the page ground and quietly fails on a card or a code plate.
+- Do not use it as a heading with a bigger size. The element is what a screen reader navigates by, and a <p> at --fs-item is invisible to a heading list.
+
+## Accessibility
+
+- as changes the element and nothing else, so the markup can say what the content is without the look changing under it.
+- Every tone is an AA-safe rung; the muted step is --ink-3-aa rather than the translucent --ink-3.
+
+## Text
+
+A paragraph, or a run of text that wants the system's voice. The step between `Article` and raw JSX. `Article` styles a whole reading column from element selectors and is the right answer for a post; this is for the single paragraph that is NOT in a column — a card's description, a dialog's explanation, the line under an empty state. The default tone is `body` (`--ink-2`), not `--ink`. A page whose paragraphs are all full-strength ink has spent the top of the ladder on its body copy and has nothing left for the headings, which is the single most common way a monochrome page loses its hierarchy.
+
+### Props
+
+- `children` — `ReactNode`.
+- `size` — `TextSize` default `'base'`. Which rung of the type scale. See TextSize.
+- `tone` — `TextTone` default `'body'`. Which rung of the ink ladder. See TextTone.
+- `as` — `TextElement` default `'p'`. The element, and ONLY the element. Changing it changes what the markup means — a `span` inside a sentence, an `li` inside a list someone else opened — and changes nothing about the look. That separation is the whole point: the alternative is a `<p>` nested inside a `<p>`, which the HTML parser silently splits into two, or a paragraph faked out of a `<div>` because the real element brought a size with it.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Types
+
+- `TextSize` = `'xs' | 'sm' | 'base' | 'lead'`
+- `TextTone` = `'body' | 'strong' | 'muted'`
+- `TextElement` = `'p' | 'span' | 'div' | 'li' | 'figcaption'`
+
+## Examples
+
+```tsx
+<Text>Twelve releases this quarter, none rolled back.</Text>
+<Text size="lead" tone="strong">A monochrome system for software and writing.</Text>
+<Text as="span" size="sm" tone="muted">Updated just now</Text>
+```

package/dist/agent/Textarea.md

@@ -4,10 +4,29 @@ Multi-line text entry, resizable vertically only.
 
 - Group: Forms
 - Import: `import { Textarea } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/textarea/
 - Related: input, field
 
+## Anatomy
+
+- **Control box** (required) — The <textarea>, on the same CONTROL_BASE as Input plus a min-h-24 floor. That floor is under rows, not over it: rows={2} still renders six rems tall.
+- **Resize grip** — The browser’s own corner handle, constrained to resize-y — a reader can lengthen the box but cannot drag it past the measure or out of the page’s gutter.
+- **Danger border** — The same pair isInvalid reads on Input: the invalid prop or an aria-invalid, including the one a Field sets when it has an error.
+
+## Best practices
+
+### Do
+
+- Set rows to the answer you expect. It is the only thing that raises the resting height above the six-rem floor, and the size of the box is the clearest thing on the page about how long an answer should be.
+- If there is a length limit, set maxLength AND say so in the hint: maxLength swallows the keystroke without explaining, and a paste one character too long is silently truncated.
+- Keep Enter meaning newline. A textarea that submits on Enter has taken the one key the control exists to accept, and the reader loses the paragraph they were halfway through.
+
+### Don’t
+
+- There is no auto-grow. The height is whatever rows and min-h-24 settled on and it never follows the content, so a long answer is reviewed through a six-rem window unless the call site says otherwise.
+- Do not put a required format in the Field’s hint and nothing else: hint and error share one slot, so the format vanishes the instant the field is wrong — which is the only moment anyone needed it.
+
 ## Textarea
 
 Multi-line text entry. Resizes vertically only: horizontal resize lets a reader drag the control past the measure and past the page's own gutter.

package/dist/agent/Timestamp.md

@@ -0,0 +1,64 @@
+# Timestamp
+
+A date or a time, rendered the one way the system renders them.
+
+- Group: Display
+- Import: `import { Timestamp } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/timestamp/
+- Related: text, badge, description-list
+
+## When to reach for it
+
+Any instant on screen. The alternative is toLocaleString() at the call site, which is how a product ends up with four date formats on one screen.
+
+## Anatomy
+
+- **Element** (required) — A <time> whose datetime is the full ISO instant from the very first render and never changes, so anything parsing the markup gets the exact moment whether or not the effect has run.
+- **First paint** (required) — The UTC calendar date, sliced straight out of the ISO string with no Intl anywhere near it. It is what the server renders and what the client renders while hydrating — both sides compute it from the same characters, so they cannot disagree.
+- **Local reading** (required) — Applied after mount, in an effect, where there is a reader to be local to: Intl.RelativeTimeFormat with numeric "auto" for the relative form, Intl.DateTimeFormat at dateStyle medium for the absolute one.
+- **Missing value** — A value nothing can parse renders an em dash at --ink-3-aa and no <time> at all, because an element whose datetime cannot be written is not a time.
+
+## Best practices
+
+### Do
+
+- Leave format on auto for a record list. It reads relative while the gap is under relativeWithin — a week by default — and switches to the calendar date past it, which is both the more useful fact and the one that stops changing.
+- Pass the instant, not a formatted string. A Date, an ISO string or epoch milliseconds all work, and all three end up as the same ISO datetime attribute.
+- Re-render from above when a list has to tick. It formats once per mount on purpose: a hundred rows each holding an interval to keep "3 minutes ago" honest is a cost nobody asked for.
+
+### Don’t
+
+- Do not expect the relative text in the server-rendered HTML. The first paint is deliberately the UTC date — a crawler, a static export and a test reading markup all see 2026-01-14, and only a mounted browser sees "3 hours ago".
+- Do not format a date beside it with toLocaleString. The two would disagree the moment one page renders on a build server, which is exactly the hydration mismatch this component is built around.
+- Do not use it for a duration. It renders an instant relative to now; "2m 14s of build time" is a length, not a moment, and belongs in a plain string.
+
+## Accessibility
+
+- The datetime attribute carries the exact ISO instant from the first render, so assistive technology reading the machine value never depends on an effect having run.
+- The visible text changes once after mount and the machine value never does, which keeps the announced value and the parsed value in agreement.
+- An unparseable value renders an em dash rather than the browser’s literal "Invalid Date" string, which is an engineering artefact and not something to put in front of a reader.
+
+## Timestamp
+
+A date or a time, rendered the one way the system renders them. Every list of records needs this, and `new Date().toLocaleString()` at the call site is precisely how a product ends up with four date formats on one screen. **On hydration.** Both halves of a formatted date are environment-dependent: a relative time depends on when it is read, and even an absolute one depends on the reader's locale and time zone, none of which a static build knows. So the first paint — the one the server produces and the one the client must reproduce exactly — is the ISO calendar date in UTC, sliced straight out of the ISO string with no `Intl` anywhere near it. Both sides compute it from the same characters, so they cannot disagree. The locale-aware and relative forms are applied after mount, in an effect, where there is a reader to be local to. This package statically exports every page, so the alternative is a hydration mismatch on any page with a date on it. The `datetime` attribute is the full ISO instant from the first render onwards and never changes, so a screen reader, a crawler, or anything else parsing the markup gets the exact moment whether or not the effect has run. It formats once per mount. A hundred rows each holding a ticking interval to keep "3 minutes ago" honest is a cost nobody asked for; a list that must tick should re-key or re-render from above.
+
+### Props
+
+- `value` (required) — `Date | string | number`. The instant. A `Date`, an ISO string, or epoch milliseconds.
+- `format` — `TimestampFormat` default `'auto'`. How the instant reads. See TimestampFormat.
+- `relativeWithin` — `number` default `604_800_000`. How far from now `auto` still prints a relative time, in milliseconds. Seven days by default — past a week the calendar date is the more useful fact, and it is also the one that stops changing.
+- `showTime` — `boolean` default `false`. Adds the clock time to the absolute form.
+
+Also accepts: `Omit<TimeHTMLAttributes<HTMLTimeElement>, 'dateTime' | 'children'>`.
+
+## Types
+
+- `TimestampFormat` = `'auto' | 'relative' | 'absolute'`
+
+## Examples
+
+```tsx
+<Timestamp value={deploy.finishedAt} />
+<Timestamp value="2026-01-14T09:30:00Z" format="absolute" showTime />
+```

package/dist/agent/Toast.md

@@ -4,7 +4,7 @@ A transient confirmation, mounted once near the app root.
 
 - Group: Feedback
 - Import: `import { Toast } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/toast/
 - Related: alert
 
@@ -12,9 +12,33 @@ A transient confirmation, mounted once near the app root.
 
 Something succeeded and needs no response. A toast is dismissed by time, and time is not an acknowledgement.
 
+## Anatomy
+
+- **Toaster** (required) — The single mount, bottom-right by default. It renders sonner’s list into a portal at the end of body, which is why the theming is an inline style — a stylesheet scoped to the app never reaches there.
+- **Token style** (required) — sonner’s --normal-bg, --normal-text, --normal-border and --border-radius pointed at --paper, --ink, --rule-2 and --radius, plus the sans face. The --success-* and --error-* pairs join them only when richColors is on, which is the only state sonner reads them in.
+- **Notification region** (required) — sonner’s own section, aria-live="polite" and labelled “Notifications altKey+KeyT”. Taken out of the tab order and reachable by that shortcut, and polite for every toast type — there is no assertive path.
+- **Toast** — One entry, pushed by toast() or one of its typed variants and removed from the DOM after sonner’s default four seconds, which this wrapper does not change. Three are visible at once; the rest queue.
+- **Close button** — On by default here, where sonner ships it off. Without it the only ways out are the timer and a swipe, and a keyboard has no swipe.
+
+## Best practices
+
+### Do
+
+- Mount exactly one Toaster. Every toast() call reaches every Toaster listening, so one in a root layout and one in a nested layout render the same message twice, in two corners.
+- Set duration per toast for anything longer than a short sentence. The wrapper leaves sonner’s default at four seconds — roughly ten words read aloud — and the rest of the message is removed from the page before it has been read.
+- Keep the message to what happened. Three toasts are visible at a time and the rest wait their turn, so a loop that toasts per item shows the last three and delivers the others after the reader has moved on.
+- Set data-mode on <html> and leave theme alone. sonner hard-codes the description’s colour per theme — #3f3f3f, overridden only under its dark theme — so a page painted dark by an attribute the Toaster was not following put that grey on --paper at roughly 1.85:1, and every toast with a description lost its second half.
+
+### Don’t
+
+- Nothing a reader must act on belongs here. Four seconds is a deadline they were never told about, and the button is in a portal at the end of body that a keyboard reaches last — an Undo in a toast is an offer most people cannot take.
+- Nothing a reader must read twice belongs here either — an error code, a reference, a name to type elsewhere. There is no history: once the timer expires the text is out of the DOM and unrecoverable.
+- Do not report a failure with toast.error and consider it reported. The region is polite for every type, so the failure queues behind whatever the screen reader was already saying and can be removed before its turn comes.
+- Do not pass theme="system". It reads prefers-color-scheme, not data-mode, so a reader who overrode a dark operating system with a light page gets a dark toast over it — the same defect the old default had, pointing the other way.
+
 ## Toaster
 
-Transient confirmations, mounted once near the app root. A toast is for something that succeeded and needs no response. Anything the reader must act on belongs in the page — a toast is dismissed by time, and time is not an acknowledgement. `richColors` stays off by default: sonner's rich palette is not this system's status scale, and turning it on reintroduces chroma the White Reset spends only on state.
+Transient confirmations, mounted once near the app root. A toast is for something that succeeded and needs no response. Anything the reader must act on belongs in the page — a toast is dismissed by time, and time is not an acknowledgement. `theme` follows `data-mode`. sonner defaults to `light` and hard-codes the description's colour per theme — `#3f3f3f`, overridden only under `[data-sonner-theme=dark]` — so a Toaster that never passed `theme` put dark grey text on this system's `--paper: #0d0d0d` and every `toast(title, { description })` lost its second half. Pass `theme` yourself and that wins; sonner's own `system` is the one value not to reach for, since it reads the OS rather than the attribute the page is actually painted from. `richColors` stays off by default: sonner's rich palette is not this system's status scale, and turning it on reintroduces chroma the White Reset spends only on state.
 
 ## Examples
 

package/dist/agent/ToggleGroup.md

@@ -4,7 +4,7 @@ A segmented control: several options, one strip.
 
 - Group: Forms
 - Import: `import { ToggleGroup } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/toggle-group/
 - Related: tabs, radio-group
 
@@ -12,6 +12,28 @@ A segmented control: several options, one strip.
 
 It changes a VALUE. Something that switches panels is Tabs.
 
+## Anatomy
+
+- **Strip** (required) — The bordered pill holding the segments, w-fit as well as inline-flex — without it a flex or grid parent stretches the strip to the widest sibling and leaves dead space after the last segment.
+- **Travelling pill** — The --accent block behind the selection, on single-value groups only and only once it has measured a selected segment. It moves rather than cross-fading, so the eye follows one thing.
+- **Segment** (required) — A button at --control-h-sm. In a single group it changes ink only and lets the pill behind it do the filling; in a multiple group it fills itself, because there is nothing travelling.
+- **Segment content** — children, in a gap-2 row. There is no iconOnly path here the way Button has one, so an icon with no words is a segment with no name.
+
+## Best practices
+
+### Do
+
+- Give a single-value group a defaultValue or a value. The pill appears only after it has measured a selected segment, so a group that starts empty is a bare strip with nothing marked in it.
+- Name the strip. Inside a Field its label does it, through aria-labelledby — the root is a div, so there is nothing for htmlFor to bind to — and standing alone it needs its own aria-label, which with type="single" is what a radiogroup is announced by.
+- Give an icon-only segment its own aria-label: nothing strips the text or supplies a name for you here, so a strip of three glyphs announces three unnamed buttons.
+
+### Don’t
+
+- type="single" has radio semantics but not radio behaviour: pressing the selected segment deselects it and commits an empty string, so a view switcher built on it can be switched off into no view at all.
+- Segments are --control-h-sm — 36px comfortable, 30px under data-density="compact" — which is below the 44px pointer floor (WCAG 2.5.5). A strip meant for a thumb needs its own height.
+- Do not put six options in it. The strip neither wraps nor scrolls, so past about five segments it simply runs out past its container, and that is a Select or a Combobox anyway.
+- A Field’s required marks a single-value strip and leaves a multiple-value one unmarked: that one is a role="toolbar", which takes no aria-required at all, so on type="multiple" the asterisk is the whole of the marking.
+
 ## Accessibility
 
 - type="single" gets radio semantics; type="multiple" gets independent toggles. Choosing wrong tells a screen reader that picking one option unpicks the others.
@@ -24,7 +46,7 @@ It changes a VALUE. Something that switches panels is Tabs.
 
 ## ToggleGroup
 
-A segmented control: several options, one strip. `type="single"` is a choice — Radix gives it radio semantics, and it is the right shape for a view switcher or a density setting. `type="multiple"` is a set of independent toggles, which is a different thing announced differently; choosing the wrong one is how a "filter by tag" control ends up telling a screen reader that picking one tag unpicks the others. The two look different on purpose. A single-value strip moves ONE filled pill between its options, so the eye follows a thing travelling; a multiple-value strip fills each pressed option separately, because there is no single selection to travel. Two people looking at a screenshot should be able to tell which kind they are looking at, and before this they could not. Distinct from `Tabs`, which switches PANELS and owns a tabpanel relationship. A toggle group changes a value.
+A segmented control: several options, one strip. `type="single"` is a choice — Radix gives it radio semantics, and it is the right shape for a view switcher or a density setting. `type="multiple"` is a set of independent toggles, which is a different thing announced differently; choosing the wrong one is how a "filter by tag" control ends up telling a screen reader that picking one tag unpicks the others. The two look different on purpose. A single-value strip moves ONE filled pill between its options, so the eye follows a thing travelling; a multiple-value strip fills each pressed option separately, because there is no single selection to travel. Two people looking at a screenshot should be able to tell which kind they are looking at, and before this they could not. Distinct from `Tabs`, which switches PANELS and owns a tabpanel relationship. A toggle group changes a value. Inside a `Field` the strip takes its name from that label, by pointing back at it — the root is a div, and `<label for>` does not bind to one, so the words above it do not click through. Standing alone it still needs its own `aria-label`.
 
 Also accepts: `ComponentProps<typeof ToggleGroupPrimitive.Root>`.
 

package/dist/agent/Toolbar.md

@@ -0,0 +1,71 @@
+# Toolbar
+
+The bar of actions at the edge of a working surface.
+
+- Group: Surfaces
+- Import: `import { Toolbar } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/toolbar/
+- Related: button, app-shell, card
+
+## When to reach for it
+
+A form’s actions that must stay in reach while the form scrolls, or a filter bar over a list. Not a page header — that is AppShell.
+
+## Anatomy
+
+- **Bar** (required) — A <div role="group"> named by label, wrapping its children on a flex row at --z-sticky. It is not role="toolbar": that role promises a single tab stop with arrow keys between the controls, and this implements no such thing.
+- **Ground** (required) — Opaque --paper, and deliberately not a blur. Content scrolls UNDER this bar, so anything translucent puts the last row of a table behind the submit button and makes both unreadable.
+- **Edge** (required) — A --rule-2 hairline on the side the bar sticks to: border-t for bottom, border-b for top. position="static" keeps the rule and drops the stickiness.
+- **Actions** (required) — children, on a flex-wrap row with a --gap of 3. align places them along the inline axis and defaults to end, which is where a form’s primary action goes.
+
+## Best practices
+
+### Do
+
+- Write label as what the bar IS — "Form actions", "List filters". A group with no name is announced as "group", and a page with two of them announces the same nothing twice.
+- Give the scrolling ancestor a height for position="bottom". A sticky element sticks within its scroll container, so a bar inside a container that is as tall as its content has nothing to stick to and simply sits at the end.
+- Keep it to the actions. A bar that has grown a title, a status and a breadcrumb is a page header, and a page header that follows the reader down the screen is a page with less of itself visible.
+
+### Don’t
+
+- Do not add role="toolbar" through props. The role tells a screen-reader user that arrow keys move between the controls; nothing here implements roving tabindex, so those keys would do nothing and the promise would be false.
+- Do not make the ground translucent to "let the content show through". The content it would show through is the row the reader is trying to read, and the button they are trying to press.
+
+## Accessibility
+
+- label is required and becomes the group’s accessible name, so a page with a filter bar and an action bar announces two distinct things.
+- Every control keeps its own place in the tab order, because the bar deliberately does not claim role="toolbar" and its single-tab-stop contract.
+- The ground is opaque, so a control on the bar always meets its contrast ratio against --paper rather than against whatever happens to be scrolling behind it.
+
+## Keyboard
+
+- Tab — Reaches each control in turn — the bar itself is not a stop.
+
+## Toolbar
+
+The bar of actions at the edge of a working surface. Two page templates built the same thing independently — a sticky strip on `--paper` with a rule along the edge it sticks to — which is the signal that it belongs here rather than in each of them. The ground is opaque `--paper` and not a blur. Content scrolls UNDER this bar, so anything translucent puts the last row of a table behind the submit button and makes both unreadable; `FloatingIconButton` blurs because it floats over a gap, which is a different problem. It is not `role="toolbar"`. That role's contract is a single tab stop with arrow keys moving between the controls inside it, and this implements no such thing — declaring the role without the behaviour tells a screen-reader user to press arrow keys that do nothing. It is a named `group`, so the controls keep their own places in the tab order and the bar is still announced.
+
+### Props
+
+- `label` (required) — `string`. Names the bar for a screen reader — "Form actions", "List filters". Required, because a group with no name is announced as "group" and a page with two of them is a page with two identical announcements.
+- `position` — `ToolbarPosition` default `'bottom'`. Which edge the bar sticks to. See ToolbarPosition.
+- `align` — `ToolbarAlign` default `'end'`. Where the contents sit along the inline axis.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Types
+
+- `ToolbarPosition` = `'bottom' | 'top' | 'static'`
+- `ToolbarAlign` = `'start' | 'center' | 'end' | 'between'`
+
+## Examples
+
+```tsx
+<Toolbar label="Form actions">
+  <Button variant="secondary">Cancel</Button>
+  <Button type="submit">Save changes</Button>
+</Toolbar>
+<Toolbar label="List filters" position="top" align="between">…</Toolbar>
+```

package/dist/agent/Tooltip.md

@@ -4,7 +4,7 @@ A short label on hover and on focus.
 
 - Group: Overlays
 - Import: `import { Tooltip } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/tooltip/
 - Related: dialog
 
@@ -12,6 +12,28 @@ A short label on hover and on focus.
 
 Never for anything the reader NEEDS: a tooltip is unreachable on touch and invisible while scanning.
 
+## Anatomy
+
+- **Provider** (required) — TooltipProvider, wrapped once around the app or the smallest subtree that has tooltips. It holds the shared 700ms open delay and the 300ms skip window; Radix throws without it rather than rendering an untimed tip.
+- **Trigger** (required) — children, handed to Radix with asChild — so the child IS the trigger and no wrapper is inserted around it.
+- **Tip** (required) — content, in the portalled panel: 11px mono on --feature-surface, capped at 16rem, 6px off the chosen side, at --z-toast (300) so it stays above a modal it was opened inside.
+- **Portal** — Where the tip lands — document.body, or the element an enclosing OverlayContainer names, which is also the box it collides against with 8px of padding.
+
+## Best practices
+
+### Do
+
+- Put the Provider high and put one there. Radix throws without it, and a provider per tooltip defeats the shared timing that stops a row of icon buttons flashing a separate tip on every hover.
+- Match the tip to the control’s aria-label word for word: two different names for one control is the “label in name” failure (WCAG 2.5.3), and a voice-control user says the words they can see.
+- Keep the tip to a phrase. It is capped at 16rem and set in 11px mono, so a sentence wraps into a five-line block that covers the thing it was describing.
+- Put it on a control that already works without it: Radix returns early when the pointer type is touch, so the tip never opens on a phone at all and anything it is the sole carrier of is simply missing there.
+
+### Don’t
+
+- delayDuration={0} does not just make it faster — the state becomes instant-open rather than delayed-open, and the fade is keyed to delayed-open, so the tip appears with no transition at all.
+- Setting delayDuration on one Tooltip overrides the provider for that trigger alone, which is how a toolbar ends up with one tip that appears instantly beside neighbours at 700ms — read as lag, not as emphasis.
+- Nothing focusable belongs in content: the tip is not in the tab order and closes when the trigger loses focus, so a link or a button in there is reachable by pointer and by nothing else. That is a Popover.
+
 ## Accessibility
 
 - Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.

package/dist/agent/TreemapChart.md

@@ -4,7 +4,7 @@ Part of a whole, when the whole has too many parts for a pie — and the parts n
 
 - Group: Charts
 - Import: `import { TreemapChart } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/treemap-chart/
 - Related: pie-chart, bar-chart
 
@@ -12,6 +12,28 @@ Part of a whole, when the whole has too many parts for a pie — and the parts n
 
 Fifty items where a pie fails at six. Under a dozen items with a ranking to read, a BarChart’s length is the more precise encoding.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, named by title, wrapping one ChartContainer.
+- **Tiles** (required) — The root’s own tile renderer. The gap between tiles is a 2px --chart-surface STROKE rather than a smaller rect, so the tiles still tile — a treemap whose parts do not touch stops reading as a partition of one whole.
+- **Tile labels** — showLabels, on by default, but a tile is only labelled when it is wider than 56px and taller than 26px. Below that the name is dropped rather than clipped, so the long tail is unlabelled by design.
+- **Tooltip** — <TreemapChart.Tooltip>, keyed on the tile name. It is doing more work here than elsewhere: it is the only way to name a tile too small to carry its own label.
+- **Hidden data table** (required) — The sr-only table lists the LEAVES, each with the path that names it. A nested tree read row by row is not something anyone can follow, so the hierarchy is flattened into the row header instead.
+- **Paint** — variant="ramp" walks --series-1 to --series-8 by tile INDEX; variant="nested" steps by DEPTH instead, which is the right encoding once the question is what is inside what.
+
+## Best practices
+
+### Do
+
+- Feed it non-negative values that sum to something the reader recognises as the whole. Area is the encoding, an area cannot be negative, and a leaf at zero or below is laid out at zero width and dropped from the picture — the hidden table prints it as “not drawn” rather than letting the two views disagree about how many leaves there are.
+- Compose <TreemapChart.Tooltip> whenever there is a tail. Anything under 56 by 26 pixels carries no label at all, and on a fifty-item treemap that is most of it.
+- Switch to variant="nested" once the tree has a second level. ramp keys the fill off the tile index, so it separates siblings and says nothing at all about depth.
+
+### Don’t
+
+- Do not read the ramp as a key. The slot is index modulo eight, so tile one and tile nine are painted identically — the fill here is separation, not identity, and the picture will not correct a reader who assumes otherwise.
+- Do not reach for it to rank a dozen items. A bar’s length is read far more precisely than a rectangle’s area, and the squarify layout deliberately does not order tiles by value alone, so a reader cannot even scan them in order.
+
 ## Accessibility
 
 - title is required. The table view lists the LEAVES with the path that names them: a nested tree read row by row is not something anyone can follow.
@@ -37,6 +59,7 @@ Part of a whole, when the whole has too many parts for a pie — and the parts n
 - `children` — `ReactNode`. The hover panel.
 - `chartProps` — `TreemapExtras`.
 - `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