@misoto22/design 0.6.1 → 0.8.0

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.6.1
+- 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.6.1
+- 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
 

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.6.1
+- Version: 0.8.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.8.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.6.1
+- Version: 0.8.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.6.1
+- Version: 0.8.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
 

package/dist/agent/WaterfallChart.md

@@ -4,7 +4,7 @@ How a total got from one figure to another.
 
 - Group: Charts
 - Import: `import { WaterfallChart } from '@misoto22/design/charts'`
-- Version: 0.6.1
+- Version: 0.8.0
 - Docs: https://ui.misoto22.com/components/waterfall-chart/
 - Related: bar-chart, funnel-chart
 
@@ -12,6 +12,29 @@ How a total got from one figure to another.
 
 “Why did this change”, where the contributions can be negative. A pie cannot hold a negative slice; a BarChart is right when the parts need not add up to the gap between two totals.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero steps. description is where the ordering caveat goes, and it is sr-only until showTitle is set.
+- **Steps** (required) — <WaterfallChart.Bars>: one floating range bar per step, running from the previous total to the new one, with a custom shape over it. Increases and totals take the solid series fill, decreases the 45 degree hatch, so direction survives greyscale and forced colours.
+- **Connectors** — connectors, on by default, joining each bar’s closing edge to where the next one starts. Without them a waterfall is a row of bars floating at unrelated heights and the reader has to reconstruct the cascade.
+- **Zero baseline** (required) — A reference line at zero that <WaterfallChart.Bars> draws itself. It is what the total bars stand on, and a waterfall with no visible zero asks the reader to take every floating bar on trust.
+- **Step labels** — showValues, and it is OFF by default. It prints each step’s signed change beside its bar — worth more here than anywhere else, because an intermediate bar has no baseline under it and its length is the one thing the axis cannot give back.
+- **Hidden data table** — The sr-only table carries the CHANGE and the RUNNING TOTAL per step, which is exactly the pair the picture encodes as a length and a position.
+
+## Best practices
+
+### Do
+
+- Turn showValues on. It is off by default and it is the relief for this form’s central weakness: an intermediate bar floats, so a reader can see that a step was small and cannot see how small.
+- Leave value off the closing total step. Omitted, it is computed from the deltas above it; typed by hand it can disagree with them, and the chart will draw the disagreement without saying a word.
+- Say in description when the step order is editorial, and pass showTitle so the sentence is actually printed. The connectors draw the steps as a sequence and most breakdowns are not one — churn and expansion in the same month are simultaneous — and a reader takes the leftmost bar as the first cause.
+
+### Don’t
+
+- Do not net two opposing movements into one step. A bar reading minus twenty that is really plus one hundred and eighty against minus two hundred is drawn exactly like a quiet month, and showing what moved is the entire purpose of the form.
+- Do not compare an intermediate bar with a total bar by eye. Only the totals sit on the zero line; everything between them is a length at an arbitrary height, so a small step high in the cascade and a large one near zero are not on comparable ground.
+- Do not reach for a pie when the contributions are signed. This is the form that exists because a pie cannot hold a negative slice — and a BarChart is the right one instead when the parts need not add up to the gap between two totals.
+
 ## Accessibility
 
 - The connectors draw the steps as a sequence, and most breakdowns are not sequential — churn and expansion in the same month are simultaneous, and a reader takes the leftmost bar as the first cause. Where the order is arbitrary, say so in description.

package/dist/agent/WorkflowFigure.md

@@ -0,0 +1,50 @@
+# WorkflowFigure
+
+A process in lanes and phases, with the main path drawn heavier than its branches.
+
+- Group: Diagrams
+- Import: `import { WorkflowFigure } from '@misoto22/design/diagrams'`
+- Version: 0.8.0
+- Docs: https://ui.misoto22.com/components/workflow-figure/
+- Related: lifecycle-figure, sequence-figure, steps
+
+## When to reach for it
+
+A runbook, an approval chain, a CI pipeline — anything with an owner per step. mainPath is what turns fourteen boxes into a diagram with a subject.
+
+## Anatomy
+
+- **Figure shell** (required) — The same frame every figure sits in. What a process hands it is a key of LINE variants rather than of node kinds — Call, Primary path, Crosses a trust boundary, Asynchronous — because a runbook is read for its arrows and not for its boxes.
+- **Lane** (required) — A 92-unit band per lane with its name set in the 118-unit gutter to its left. The band spans only what the lane actually holds, and a lane marked exception is washed rather than ruled — the one wash in the package’s diagrams, because nothing routes across it.
+- **Column** (required) — What col indexes: a 168-unit column with a 58-unit gutter, the same across every lane. A node sits centred in its lane’s depth, moved off that centre line only by yOffset.
+- **Phase header** — A mono caption at the x of its fromCol, over a rule drawn across the columns from fromCol to toCol — so a phase’s extent is something a reader can see rather than a field only its author knows. variant dashes that rule for security and thickens it for emphasis. A phase is an axis label, so it is set like one rather than framed.
+- **Group frame** — A labelled rule around a run of columns inside ONE lane — a planning loop, an evidence path — dashed when its variant is security.
+- **Main path** — mainPath, drawn as weight rather than as a mark of its own: every edge between two consecutive ids on it goes heavier whatever its own variant says.
+
+## Best practices
+
+### Do
+
+- Give every node a lane that spec.lanes declares. An unknown lane id still resolves to the first lane — there is nowhere else to put the box — so a step written for the exception band is drawn in the right column, at the right size, in the wrong row, and development prints DIAGRAM_LANE_UNKNOWN naming the node.
+- Write mainPath as the path in order. The heavier weight is applied to CONSECUTIVE pairs, so [intake, review, ship] emphasises intake→review and review→ship and nothing else; an id whose neighbour on the list is not the far end of a real edge changes nothing at all.
+- Say what an edge MEANS with role and let the drawing follow it. async and error take the quiet dashed line, return takes an open arrowhead, and main and branch add no stroke of their own because mainPath already draws that distinction as weight. An explicit variant overrides all of it, which is what it is for.
+
+### Don’t
+
+- Phases partition the columns; they do not stack. Each is drawn as a rule across its own span, so two phases claiming the same columns put two rules on one line and one caption over the other — and a reader cannot tell that from one phase drawn twice.
+- An empty lane is not a spacer. The band is sized from what the lane holds, so a lane with no nodes collapses to about one column beside the gutter with its name still set — and an exception lane in that state washes a strip of ground next to the figure rather than under the failure path.
+
+## Accessibility
+
+- Same contract as every figure: a named picture, with its nodes and relationships published as text beside it.
+- The exception lane is the one washed band in the system’s diagrams, and it is still labelled — the wash is not carrying the meaning on its own.
+
+## WorkflowFigure
+
+A process: who does what, in what order, and where it can go wrong. Three structures stacked on one grid, and they are three because they answer three different questions a reader brings to a runbook. **Lanes** are rows and answer WHO. A lane marked `exception` is the one band that gets a wash rather than a rule, and it earns the exception to the frames-are-rules law because nothing routes across it — it IS the ground for the failure path, not a frame drawn over the happy one. **Phases** are columns across every lane and answer WHEN. Printed as captions on one header rule, because a phase is an axis label. **Groups** are frames inside a single lane and answer WHAT BELONGS TOGETHER — a planning loop, an evidence path. THE MAIN PATH IS HEAVIER, and that is the whole hierarchy. `mainPath` lists the node ids a reader should be able to follow without thinking. Every edge between two consecutive ids on it is drawn at the emphasis weight whatever its own variant says, which is the one thing that turns fourteen boxes and nineteen arrows into a diagram with a subject. An `error` role goes the other way — dashed and soft — so the exception path recedes without disappearing, and so does `async`. `branch` adds no stroke of its own: a branch is an edge the main path does not list, and that is already the difference on the page.
+
+### Props
+
+- `spec` (required) — `WorkflowSpec`.
+
+Also accepts: `FigureChrome`.