@misoto22/design 0.7.0 → 0.8.0

package/dist/agent/Spinner.md

@@ -4,7 +4,7 @@ The one “working” indicator — a ring, never a shimmer.
 
 - Group: Feedback
 - Import: `import { Spinner } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/spinner/
 - Related: skeleton, progress
 
@@ -12,6 +12,27 @@ The one “working” indicator — a ring, never a shimmer.
 
 A wait short enough that the shape of what is coming does not matter. Longer than that, use a Skeleton.
 
+## Anatomy
+
+- **Live region** (required) — The outer span, and the only part with a voice. It carries role="status" while there is a label; pass label={null} and it turns into an aria-hidden box with no role at all.
+- **Ring** (required) — The inner span — 14px, 18px or 26px of border on a transparent box, and the only element size, tone and className reach.
+- **Leading quarter** (required) — border-t, drawn in --ink at the default tone and in the inherited colour at current. It is the whole difference between a ring and a plain circle, which is why a still ring still reads as unfinished.
+- **Screen-reader label** — An sr-only span holding label, present unless label is null. Announced once, when the spinner mounts, and never again.
+
+## Best practices
+
+### Do
+
+- Pass tone="current" for a spinner on any filled ground: the default draws the leading quarter in --ink over a --rule-2 track, and inside a primary Button both of those are the ground it is sitting on.
+- Announce the arrival somewhere else. The label is read once on mount and nothing is said on the way out, so a reader who heard “Loading projects” is never told the projects came.
+- Reach for label={null} only inside a control that already names the operation — it hides the whole element from assistive tech rather than merely dropping the text, so a silenced spinner standing on its own is a wait nobody is told about.
+
+### Don’t
+
+- label defaults to the bare word “Loading”, so a Spinner written without the prop ships the exact announcement the prop exists to prevent — the default is a placeholder, not a value.
+- className is merged onto the ring AFTER size and tone, so it beats both: <Spinner size="lg" className="size-4" /> is a 16px ring, and the prop whose whole job was naming the size is the one that lost.
+- Nothing here sets aria-busy — Button does that for its own control — so a spinner laid over a panel leaves the panel announced as ready while its contents are stale and its buttons still take clicks.
+
 ## Accessibility
 
 - label names the specific thing being waited on; three spinners all saying “Loading” tell a screen reader nothing.
@@ -20,12 +41,13 @@ A wait short enough that the shape of what is coming does not matter. Longer tha
 
 ## Spinner
 
-The system's one "working" indicator. A ring, not a blurred glow and not a shimmer: the White Reset has no light source, so depth and softness are not available to it. The leading quarter is the only thing that distinguishes the ring from a plain circle, which is why the track stays a hairline — a spinner is a hint that time is passing, not a feature of the page. It spins under `motion-safe` only. A reader who has asked for less motion gets a static ring, which still reads as "not finished" because the leading quarter is darker than the track. For a wait long enough that the reader would otherwise wonder whether the page is broken, prefer `Skeleton` — a shape that describes what is coming beats a dot that describes nothing.
+The system's one "working" indicator. A ring, not a blurred glow and not a shimmer: the White Reset has no light source, so depth and softness are not available to it. The leading quarter is the only thing that distinguishes the ring from a plain circle, which is why the track stays a hairline — a spinner is a hint that time is passing, not a feature of the page. It spins under `motion-safe` only. A reader who has asked for less motion gets a static ring, which still reads as "not finished" because the leading quarter is darker than the track. For a wait long enough that the reader would otherwise wonder whether the page is broken, prefer `Skeleton` — a shape that describes what is coming beats a dot that describes nothing. `className` reaches the RING, alongside `size` and `tone`, and overrides them: every utility a caller has for a spinner is about the ring, and merged onto the wrapper instead `className="size-8"` grew an invisible box around an unchanged 18px circle. Layout still works from there — the wrapper is `inline-flex` and takes the ring's margin box as its own.
 
 ### Props
 
 - `size` — `'sm' | 'md' | 'lg'` default `'md'`. 14px / 18px / 26px. Match the size of the type it sits beside.
 - `tone` — `'default' | 'current'` default `'default'`. `default` draws the ring against the page — a hairline track in the rule colour with the leading quarter in ink. `current` draws it in the inherited text colour, which is what a spinner inside a filled button needs: on an ink ground an ink ring is invisible.
+- `className` — `string`. Merged onto the RING, after `size` and `tone`, so it overrides both.
 - `label` — `string | null` default `'Loading'`. Announced to assistive tech. Pass the specific thing being waited on ("Loading projects"), not the generic word — a screen reader user hearing "Loading" three times cannot tell which three things. Pass `null` for a spinner that sits inside a control which already names the operation (a button whose own label changes to "Saving…"), so the two are not read out twice.
 
 Also accepts: `HTMLAttributes<HTMLSpanElement>`.

package/dist/agent/StatusDot.md

@@ -4,10 +4,29 @@ The dot beside a status word.
 
 - Group: Display
 - Import: `import { StatusDot } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/status-dot/
 - Related: status-pill
 
+## Anatomy
+
+- **Box** (required) — The aria-hidden <span> the whole thing lives in — 8px square at md, 7px at sm, inline-grid and shrink-0 so it stays circular in a flex row however long the label beside it runs.
+- **Dot** (required) — An absolutely-positioned filled circle in --ok, --warn, --danger or --ink-3-aa. It is the only part of this component tone touches.
+- **Halo** — A second ring of the same colour on the m22-halo keyframes, present only while pulse is true. A separate element rather than a box-shadow, because a shadow in this system is never blurred.
+
+## Best practices
+
+### Do
+
+- Set pulse={false} for anything settled. It defaults to true, so a dot for a build that finished or a status that will not change today carries a halo announcing that something is happening right now.
+- Reach for StatusPill the moment you find yourself writing the dot and its label together — that pairing assembled per call site is how one site ended up with three dot sizes and two pulse timings for the same state.
+- Let it sit directly in the flex row beside its label: shrink-0 is what keeps it round, and a dot wrapped in a div that can shrink comes out an ellipse as soon as the label runs long.
+
+### Don’t
+
+- An aria-label on the dot buys nothing — aria-hidden is still set, and a hidden element has no name to give. A call site with no visible label is a state no screen reader ever reports.
+- sm and md are 7px and 8px, one pixel apart. That is an optical adjustment for sitting beside smaller type, not a size scale, and nothing in a layout should be built on the difference.
+
 ## Accessibility
 
 - aria-hidden without exception: it repeats a state the adjacent label already names.

package/dist/agent/StatusPill.md

@@ -4,13 +4,39 @@ A live state, named: a dot plus an uppercase mono label.
 
 - Group: Display
 - Import: `import { StatusPill } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/status-pill/
 - Related: status-dot, badge
 
+## Anatomy
+
+- **Pill** (required) — The outlined <span>: --radius-pill, a --rule-2 hairline, --paper ground, and deliberately uneven padding — 10px before the dot, 12px after the label — so the pair sits optically centred rather than mathematically.
+- **Dot** (required) — A StatusDot handed tone and pulse. It is aria-hidden, so it is not where the tone reaches a reader who cannot see it.
+- **Label** (required) — children in the eyebrow idiom — 11px uppercase mono, tracking pulled back from 0.2em to 0.12em because a pill is a shorter run than a section kicker.
+- **Severity** — A visually-hidden “Warning” or “Error” at the warning and danger tones, so those two reach a reader through something other than a colour on a hidden dot. success and neutral add nothing: they are the absence of alarm, which is what a reader already assumes.
+
+## Best practices
+
+### Do
+
+- Put the state in the words anyway. The severity word reaches a screen reader and nothing else — the pill’s own text is --ink-2 at every tone, so on a monochrome screen “Degraded” in a warning pill and in a neutral one are still the same pill.
+- Set pulse={false} once the state has settled — the default halo means “right now”, and an archived or shipped pill pulsing forever tells the reader something is live when nothing is.
+- Take the whole pill rather than composing a dot and a span at the call site: that assembly is how the same “available for work” chip came out at three dot sizes and two pulse timings on one site.
+
+### Don’t
+
+- It is not a live region. The pill is a plain <span>, so a state flipping from Available to Degraded while the reader is on the page changes silently — if the change is the news, the call site owns the role="status" around it.
+- One per view, not one per row. The label is an uppercase eyebrow at 0.12em tracking — the loudest small type the system has — and a column of them down a table is Badge’s job, which is why Badge carries the same status tones in plain 12px mono.
+
+## Accessibility
+
+- The warning and danger tones are doubled by a visually-hidden severity word, because the dot that carries the colour is aria-hidden and has no name to give.
+- success and neutral are silent on purpose: announcing “OK” before every settled pill is noise charged to the two tones worth interrupting for.
+- Not a live region. A state that flips while the reader is on the page changes silently unless the call site owns a role="status" around it.
+
 ## StatusPill
 
-A live state, named: a dot plus an uppercase mono label in an outlined pill. One component rather than a dot and a pill assembled per call site, which is how the same "available for work" chip ended up with three different dot sizes and two different pulse timings on one site.
+A live state, named: a dot plus an uppercase mono label in an outlined pill. One component rather than a dot and a pill assembled per call site, which is how the same "available for work" chip ended up with three different dot sizes and two different pulse timings on one site. A warning or danger tone is doubled by a visually-hidden severity word, so the tone survives the dot being hidden. It does not survive monochrome: the pill's own text is `--ink-2` at every tone, and the state itself still belongs in the words the call site writes.
 
 ### Props
 

package/dist/agent/Steps.md

@@ -4,7 +4,7 @@ A numbered sequence, as a rail — one thing after another, with a rule through
 
 - Group: Display
 - Import: `import { Steps } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/steps/
 - Related: diagram, article
 
@@ -12,6 +12,29 @@ A numbered sequence, as a rail — one thing after another, with a rule through
 
 A pipeline, a migration, a recipe: an order with no branches. The moment something forks or points at something else it is a Diagram, and drawing a fork as a list hides it.
 
+## Anatomy
+
+- **Rail** (required) — The <ol>, carrying --step-size — one number that three rules read: the marker’s own box, where the connector starts, and where it is centred.
+- **Marker** (required) — A 2rem circle per step, aria-hidden: the position number, or a blank hairline node when marker is "rule". Filled with --accent for the current one.
+- **Connector** — A hairline drawn on every item but the last, placed absolutely from the foot of that marker to the foot of its row — so it spans the gap rather than running behind the markers, and no tail hangs off the end of the sequence.
+- **Title** (required) — step.title, at 15px in the interface face. The step’s name — a noun, not a description of what happens in it.
+- **Note** — step.note, a mono line under the title: what the step is made of, what it costs, what it uses.
+
+## Best practices
+
+### Do
+
+- Use marker="rule" for a sequence of states. “Queued, running, done” is an order rather than an instruction list, and a digit in front of each one tells the reader they are steps to perform.
+- Mark at most one step current: it is the one thing the rail states rather than draws, and two filled markers put the process in two places at once.
+- Pass label when no heading names the sequence — it is the list’s only name, so without it the rail is announced as five items belonging to nothing.
+- Retune the rail through --step-size on the list rather than by restyling the marker: the marker box, the connector’s start and its centring all read that one number, and moving one of the three leaves the line beginning in mid-air.
+
+### Don’t
+
+- A fork drawn here is a fork the reader never sees. The connector runs from each step to the next one in the array and to nothing else, so two branches flatten into four consecutive steps and the choice between them leaves the figure entirely.
+- steps={[]} renders null rather than an empty rail, so a list filtered down to nothing leaves a heading standing over a gap unless the call site checks the length itself.
+- Nothing here is clickable and the props spread onto the <ol>, so an onClick meant for a step lands on the whole list. A sequence the reader is meant to move through is a Breadcrumb or a Tabs.
+
 ## Accessibility
 
 - An <ol>, because the order IS the content — a stack of divs says nothing about sequence.

package/dist/agent/Switch.md

@@ -4,7 +4,7 @@ A setting that takes effect immediately.
 
 - Group: Forms
 - Import: `import { Switch } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/switch/
 - Related: checkbox
 
@@ -12,6 +12,26 @@ A setting that takes effect immediately.
 
 Inside a form with a Save button, a switch is a lie about when the change happened. Use a Checkbox.
 
+## Anatomy
+
+- **Track** (required) — A 36×20 <button role="switch"> on a pill radius, filled --stone when off and --accent when on. Filled rather than outlined, so it still reads as a control on a white page.
+- **Thumb** (required) — A 14px paper circle with a hairline, not a white disc on a shadow — this system has no shadows. It stretches to 20px while pressed and rounds out as it lands; motion-reduce drops that entirely.
+- **Label** — Not rendered here either. The Radix root IS a <button>, though, which a <label for> does bind to — so unlike Select or RadioGroup, a Field’s label above a Switch really does click through to it.
+
+## Best practices
+
+### Do
+
+- Handle the failure at the control. The flip has already claimed the change happened, so an onCheckedChange whose request fails must put the thumb back and say why, or the page is showing a setting the server does not have.
+- Name it for the state, not the action: the accessible name is read together with “on” or “off”, so “Email notifications, on” is a sentence and “Turn on email notifications, on” is two contradictory ones.
+- Keep the flip instant to the eye even when the write is not — an optimistic thumb with a quiet undo beats a spinner on a control whose whole claim is that it already took effect.
+
+### Don’t
+
+- A switch has two states and no third. “Inherit from the workspace” cannot be a switch, because the only way to draw it is unchecked, which announces “off” — that is a RadioGroup or a Select.
+- There is no readOnly: disabled is the only lock, and it takes the control out of the tab order, so a keyboard reader tabbing the form passes the setting without ever hearing its value.
+- Do not add transition-all from a call site. It replaces transition-[transform,width] wholesale, which puts the track’s colour on the thumb’s longer duration and turns a flip into a fade.
+
 ## Keyboard
 
 - Space / Enter — Toggles it, and the change applies immediately.

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.8.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>`.

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.8.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.8.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.8.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.8.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.8.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.8.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