@misoto22/design 0.3.1 → 0.6.0

package/dist/agent/Skeleton.md

@@ -0,0 +1,73 @@
+# Skeleton
+
+The shape of the page, before the page.
+
+- Group: Feedback
+- Import: `import { Skeleton } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/skeleton/
+- Related: spinner, empty-state
+
+## When to reach for it
+
+A wait the reader would otherwise think was a broken page. A shape that describes what is coming beats a dot that describes nothing.
+
+## Accessibility
+
+- One live region on the wrapper; every shape inside it is aria-hidden.
+- One pulse on the wrapper, not one per bar, so the page breathes together.
+
+## Skeleton
+
+The fill every skeleton part is drawn from: `--stone`, and nothing else. Deliberately NOT a shimmer. A shimmer sweeps a highlight across the shape, which implies a light source; the White Reset has none, so the sweep reads as a bug rather than as loading. The whole page breathes together instead — see `SkeletonPage`, which owns the single pulse.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## SkeletonLine
+
+A line of type. Height is the line's; width is how far it runs.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## SkeletonBlock
+
+A block: an image mount, a plate, a chart.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## SkeletonCircle
+
+A circle: an avatar, a marker.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## SkeletonText
+
+A paragraph. The last line is short, because real prose ends mid-measure. A block of equal full-width bars reads as a table, and the reader then flinches when a paragraph arrives instead.
+
+### Props
+
+- `lines` — `number` default `3`. How many lines of prose to stand in for.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## SkeletonPage
+
+The frame a skeleton sits in: the live region, and the single pulse. One `animate-pulse` on the wrapper rather than one per part, so the page breathes together instead of shimmering out of phase — twenty independently animated bars is a visual noise floor, not a loading state. A skeleton whose shape does not match what replaces it is worse than none: it promises a layout and then the page jumps out from under the reader. Compose the parts to match the real thing, and change both together.
+
+### Props
+
+- `label` (required) — `string`. What is loading, in words. Announced once; the shapes themselves are `aria-hidden`, so this sentence is the entire experience for a screen reader and "Loading" alone tells it nothing.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Examples
+
+```tsx
+<Skeleton className="h-3 w-40 rounded-(--radius-pill)" />
+<SkeletonPage label="Loading projects">
+  <SkeletonLine className="h-2.5 w-28" />
+  <SkeletonBlock className="mt-6 h-40" />
+</SkeletonPage>
+```

package/dist/agent/Slider.md

@@ -0,0 +1,39 @@
+# Slider
+
+A value chosen along a range.
+
+- Group: Forms
+- Import: `import { Slider } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/slider/
+- Related: progress
+
+## Accessibility
+
+- label is required. A thumb that announces "42" and nothing else leaves a screen reader user with a number and no idea what it measures.
+- A 44px hit area sits invisibly around the 16px thumb.
+- Arrows step, Page keys jump, Home and End reach the ends.
+
+## Keyboard
+
+- ← / → — Moves by one step.
+- Page Up / Page Down — Moves by a larger step.
+- Home / End — Jumps to the minimum or maximum.
+
+## Slider
+
+A value chosen along a range. Radix owns the keyboard contract — arrows step, Page keys jump, Home and End reach the ends — and the ARIA that reports the value. What is here is the look, and the labelling, which is the part a slider most often gets wrong: a thumb that announces "42" and nothing else leaves a screen reader user with a number and no idea what it measures. A 44px hit area sits invisibly around the 16px thumb, because a thumb sized for the design is well under any pointer-target guideline.
+
+### Props
+
+- `label` (required) — `string | [string, string]`. Names the control. Required: a slider with no name announces only a number, and a number with no noun is not information. A range slider (two thumbs) needs one name per thumb — pass an array.
+- `showValue` — `boolean` default `false`. Prints the current value beside the label.
+- `format` — `(value: number) => string` default `String`. Renders the value with a unit or a currency, e.g. `(n) => n + '%'`.
+
+Also accepts: `ComponentProps<typeof SliderPrimitive.Root>`.
+
+## Examples
+
+```tsx
+<Slider label="Quality" defaultValue={[80]} max={100} step={5} showValue format={(n) => `${n}%`} />
+```

package/dist/agent/Sparkline.md

@@ -0,0 +1,45 @@
+# Sparkline
+
+A run of numbers at the size of a word.
+
+- Group: Data
+- Import: `import { Sparkline } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/sparkline/
+- Related: line-chart, table
+
+## When to reach for it
+
+In a table cell, beside a figure, at the end of a row. When the trend needs reading precisely it wants a LineChart and its own space.
+
+## Accessibility
+
+- label is required and is the whole accessible name: a sparkline has no axes and no legend, so nothing else describes it.
+- Axis-less by design. Every piece of chrome that would let it answer “what value exactly” also makes it too big to sit inline, which was the only reason to reach for it.
+- Pin domain for a column of them: on independent domains every row peaks and troughs identically, which is how a table of sparklines becomes actively misleading.
+- One path, no rendering engine — so a hundred of them in a table cost nothing.
+
+## Sparkline
+
+A run of numbers at the size of a word — in a table cell, beside a figure, at the end of a row. Deliberately axis-less, gridless and label-less: a sparkline answers "what shape has this been", and every piece of chrome that would make it answer "what value exactly" also makes it too big to sit inline, which was the only reason to reach for it. When the exact value matters, print the number beside it — `value` does — and when the trend needs reading precisely, it wants a `<LineChart>` and its own space. No rendering engine: it is one `<path>` over a normalised viewBox, so it costs nothing to put a hundred of them in a table.
+
+### Props
+
+- `data` (required) — `number[]`. The numbers, in order. Anything shorter than two points draws nothing.
+- `label` (required) — `string`. What the run is, in a sentence. Required, and it is the whole accessible name: a sparkline has no axes and no legend, so nothing else describes it.
+- `variant` — `SparklineVariant` default `'line'`.
+- `height` — `number` default `28`. Height in pixels. The width comes from the container.
+- `domain` — `[number, number]`. The domain, as `[min, max]`. Derived from the data when omitted. Pin it whenever a column of sparklines is meant to be compared: on independent domains every row peaks and troughs identically, which is the one way a table of sparklines can be actively misleading.
+- `showLast` — `boolean` default `true`. Marks the last point, which is usually the one being asked about.
+- `value` — `ReactNode`. The value announced alongside the label — the current reading, formatted. Falls back to the last number.
+- `className` — `string`.
+
+## Types
+
+- `SparklineVariant` = `'line' | 'area' | 'bars'`
+
+## Examples
+
+```tsx
+<Sparkline label="Weekly signups" data={[12, 18, 9, 24, 30, 22, 41]} value="41" />
+```

package/dist/agent/Spinner.md

@@ -0,0 +1,39 @@
+# Spinner
+
+The one “working” indicator — a ring, never a shimmer.
+
+- Group: Feedback
+- Import: `import { Spinner } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/spinner/
+- Related: skeleton, progress
+
+## When to reach for it
+
+A wait short enough that the shape of what is coming does not matter. Longer than that, use a Skeleton.
+
+## Accessibility
+
+- label names the specific thing being waited on; three spinners all saying “Loading” tell a screen reader nothing.
+- label={null} silences it for use inside a control that already announces the operation.
+- Spins under motion-safe only; the static ring still reads as unfinished because the leading quarter is darker.
+
+## 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.
+
+### 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.
+- `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>`.
+
+## Examples
+
+```tsx
+<Spinner size="lg" label="Loading projects" />
+// Inside a filled button, where the ground is ink:
+<Spinner size="sm" tone="current" label={null} />
+```

package/dist/agent/StatusDot.md

@@ -0,0 +1,36 @@
+# StatusDot
+
+The dot beside a status word.
+
+- Group: Display
+- Import: `import { StatusDot } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/status-dot/
+- Related: status-pill
+
+## Accessibility
+
+- aria-hidden without exception: it repeats a state the adjacent label already names.
+- The halo is motion-safe, so a reader who asked for less motion gets a still dot.
+
+## StatusDot
+
+The dot beside a status word. `aria-hidden` without exception: the dot repeats a state the adjacent label already names, and a screen reader announcing "available" twice is worse than not announcing the decoration at all. If a call site has no visible label, the fix is a label, not an `aria-label` on the dot. The halo is a separate absolutely-positioned ring rather than a box-shadow, because Law 2 of this system is that a shadow is never blurred — and it is motion-safe, so a reader who asked for less motion gets a static dot.
+
+### Props
+
+- `size` — `'sm' | 'md'` default `'md'`. 7px / 8px. `md` is the default.
+- `tone` — `StatusTone` default `'success'`.
+- `pulse` — `boolean` default `true`. A halo that grows and dissolves, for "live right now". Off for a settled state.
+
+Also accepts: `HTMLAttributes<HTMLSpanElement>`.
+
+## Types
+
+- `StatusTone` = `'success' | 'warning' | 'danger' | 'neutral'`
+
+## Examples
+
+```tsx
+<span className="inline-flex items-center gap-2"><StatusDot /> Available</span>
+```

package/dist/agent/StatusPill.md

@@ -0,0 +1,28 @@
+# StatusPill
+
+A live state, named: a dot plus an uppercase mono label.
+
+- Group: Display
+- Import: `import { StatusPill } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/status-pill/
+- Related: status-dot, badge
+
+## 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.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `tone` — `StatusTone` default `'success'`.
+- `pulse` — `boolean` default `true`. Pulsing live dot (default) vs a settled one.
+
+Also accepts: `HTMLAttributes<HTMLSpanElement>`.
+
+## Examples
+
+```tsx
+<StatusPill>Available for work</StatusPill>
+<StatusPill tone="warning" pulse={false}>Degraded</StatusPill>
+```

package/dist/agent/Steps.md

@@ -0,0 +1,44 @@
+# Steps
+
+A numbered sequence, as a rail — one thing after another, with a rule through them.
+
+- Group: Display
+- Import: `import { Steps } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/steps/
+- Related: diagram, article
+
+## When to reach for it
+
+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.
+
+## Accessibility
+
+- An <ol>, because the order IS the content — a stack of divs says nothing about sequence.
+- aria-current="step" marks the filled one, which is the only thing here a reader could not infer from the reading order.
+- The markers and the connector are aria-hidden: the number is the list position, and screen readers already announce that.
+
+## Steps
+
+A numbered sequence, as a rail. The shape a pipeline actually has: one thing after another, each with a name and a line of detail, and a rule running through them so the eye reads them as one process rather than as five unrelated rows. It is the figure a technical post reaches for most often after a diagram, and it is NOT a diagram — nothing branches, nothing points at anything, and drawing it with boxes and arrows says otherwise. The connector is drawn on the ITEM rather than as a full-height line behind the markers, so it starts under one and stops above the next instead of running through both — and so the last step has no tail hanging off it. That is the detail that separates a rail from a list with a border on it. An `<ol>`, because the order is the content. `aria-current="step"` marks the filled one, which is the only thing here a screen reader could not otherwise infer from the order it is read in.
+
+### Props
+
+- `steps` (required) — `Step[]`.
+- `label` — `string`. Names the sequence for assistive tech when no heading does.
+- `marker` — `'number' | 'rule'` default `'number'`. How the marker is drawn. `number` counts from one and is right for a pipeline, a recipe, a migration. `rule` drops the digit for a plain hairline node, which is what a sequence of states wants — "queued, running, done" is an order, not a numbered list.
+
+Also accepts: `Omit<HTMLAttributes<HTMLOListElement>, 'children'>`.
+
+## Examples
+
+```tsx
+<Steps
+  label="How an answer is built"
+  steps={[
+    { title: 'Corpus', note: 'Blog MDX · project database' },
+    { title: 'Chunking', note: 'By heading · 300–800 tokens' },
+    { title: 'Answer', note: 'Live citation panel', current: true },
+  ]}
+/>
+```

package/dist/agent/Switch.md

@@ -0,0 +1,29 @@
+# Switch
+
+A setting that takes effect immediately.
+
+- Group: Forms
+- Import: `import { Switch } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/switch/
+- Related: checkbox
+
+## When to reach for it
+
+Inside a form with a Save button, a switch is a lie about when the change happened. Use a Checkbox.
+
+## Keyboard
+
+- Space / Enter — Toggles it, and the change applies immediately.
+
+## Switch
+
+A setting that takes effect immediately. Distinct from `Checkbox`, and the distinction is not cosmetic: a switch applies on flip, a checkbox applies on submit. A switch inside a form with a Save button is a lie about when the change happened. The track fills with ink when on and the thumb is paper with a hairline — rather than a white thumb floating on a drop shadow, which this system does not have. The off state is a filled rule-coloured track, so the control still reads as a control on a white page.
+
+Also accepts: `ComponentProps<typeof SwitchPrimitive.Root>`.
+
+## Examples
+
+```tsx
+<Field label="Email notifications"><Switch defaultChecked /></Field>
+```

package/dist/agent/Table.md

@@ -0,0 +1,85 @@
+# Table
+
+A ruled data table — alignment, sorting and rules all per column.
+
+- Group: Data
+- Import: `import { Table } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/table/
+- Related: card, figure-band
+
+## When to reach for it
+
+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.
+
+## Accessibility
+
+- caption is required: an unnamed table on a page with three tables is unnavigable.
+- Column labels are <th scope="col">, so a cell can be traced back to its heading.
+- 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.
+
+## Keyboard
+
+- Tab — Reaches the scroll region, and each sortable column header.
+- ← / → — Scrolls the table sideways once the region has focus.
+
+## 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.
+
+### 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 .
+- `density` — `'comfortable' | 'compact'` default `'comfortable'`. Tightens the row padding, for a table that is mostly numbers.
+
+Also accepts: `TableHTMLAttributes<HTMLTableElement>`.
+
+## THead
+
+Header group. The rule under it is drawn by the table's border setting.
+
+## TBody
+
+## TR
+
+## TH
+
+A column label. Mono and uppercase, so it never reads as data. When sortable, the label becomes a `<button>` INSIDE the `<th>` rather than the `<th>` becoming clickable: a cell with a click handler is not focusable and not announced as a control, so the sort exists only for a mouse. Sorting is per column and opt-in. A table where every header is a button invites the reader to try sorting a column the data cannot be ordered by.
+
+### Props
+
+- `align` — `TableAlign` default `'start'`. Which edge the column's contents sit against. Numbers belong at `end`.
+- `sortable` — `boolean` default `false`. Makes the label a button and shows the sort marker.
+- `sortDirection` — `SortDirection` default `'none'`. Which way this column is sorted. Also set as `aria-sort`, which is the only way a screen reader learns a table is ordered at all — a caret drawn in the header tells it nothing.
+- `onSort` — `() => void`.
+
+Also accepts: `Omit<ThHTMLAttributes<HTMLTableCellElement>, 'align'>`.
+
+## TD
+
+### Props
+
+- `align` — `TableAlign` default `'start'`. Which edge the cell's contents sit against. Match the column's header.
+
+Also accepts: `Omit<TdHTMLAttributes<HTMLTableCellElement>, 'align'>`.
+
+## Types
+
+- `TableAlign` = `'start' | 'center' | 'end'`
+- `TableBorders` = `'rows' | 'grid' | 'bordered' | 'bordered-grid' | 'none'`
+- `SortDirection` = `'ascending' | 'descending' | 'none'`
+
+## Examples
+
+```tsx
+<Table caption="Deploy history">
+  <THead><TR><TH>Commit</TH><TH align="end" sortable sortDirection={dir} onSort={sort}>Duration</TH></TR></THead>
+  <TBody><TR><TD>a1b2c3d</TD><TD align="end">2m 14s</TD></TR></TBody>
+</Table>
+<Table caption="Inventory" borders="bordered-grid" density="compact">…</Table>
+```

package/dist/agent/Tabs.md

@@ -0,0 +1,48 @@
+# Tabs
+
+One strip, several panels.
+
+- Group: Navigation
+- Import: `import { Tabs } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/tabs/
+- Related: accordion
+
+## 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.
+- 44px tall, because a tab is a pointer target like any other.
+
+## Keyboard
+
+- Tab — Moves into the strip, and out of it — the whole strip is one stop.
+- ← / → — Moves between tabs and switches the panel with them.
+- Home / End — Jumps to the first or last tab.
+
+## Tabs
+
+Radix Tabs root, re-exported as a typed passthrough.
+
+## TabsList
+
+The tab strip. Scrolls horizontally rather than wrapping. A wrapped second row of tabs moves every tab below it when the strip grows, and the reader loses the one they were about to click.
+
+## TabsTrigger
+
+One tab. The active marker is a 2px ink rule pulled onto the strip's own border with `-mb-px`, so the two occupy the same line instead of stacking into a 3px edge. 44px tall, because a tab is a pointer target like any other.
+
+## TabsContent
+
+The panel paired to a  by matching `value`.
+
+## Examples
+
+```tsx
+<Tabs defaultValue="preview">
+  <TabsList>
+    <TabsTrigger value="preview">Preview</TabsTrigger>
+    <TabsTrigger value="code">Code</TabsTrigger>
+  </TabsList>
+  <TabsContent value="preview">…</TabsContent>
+</Tabs>
+```

package/dist/agent/Tag.md

@@ -0,0 +1,35 @@
+# Tag
+
+A subject label — a topic, a technology, a filter facet.
+
+- Group: Display
+- Import: `import { Tag } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/tag/
+- Related: badge
+
+## When to reach for it
+
+Several sit together and the reader scans them. One fact about one record is a Badge.
+
+## 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.
+
+## 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.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+- `active` — `boolean` default `false`. Renders the pressed/selected look. Pair with `aria-pressed` on a wrapper button.
+
+Also accepts: `HTMLAttributes<HTMLSpanElement>`.
+
+## Examples
+
+```tsx
+<Tag>TypeScript</Tag>
+<button type="button" aria-pressed={on} onClick={toggle}><Tag active={on}>Rust</Tag></button>
+```

package/dist/agent/Textarea.md

@@ -0,0 +1,26 @@
+# Textarea
+
+Multi-line text entry, resizable vertically only.
+
+- Group: Forms
+- Import: `import { Textarea } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/textarea/
+- Related: input, field
+
+## 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.
+
+### Props
+
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `ref` — `Ref<HTMLTextAreaElement>`.
+
+Also accepts: `TextareaHTMLAttributes<HTMLTextAreaElement>`.
+
+## Examples
+
+```tsx
+<Field label="Notes" htmlFor="notes"><Textarea id="notes" rows={4} /></Field>
+```

package/dist/agent/Toast.md

@@ -0,0 +1,26 @@
+# Toast
+
+A transient confirmation, mounted once near the app root.
+
+- Group: Feedback
+- Import: `import { Toast } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/toast/
+- Related: alert
+
+## When to reach for it
+
+Something succeeded and needs no response. A toast is dismissed by time, and time is not an acknowledgement.
+
+## 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.
+
+## Examples
+
+```tsx
+// app root
+<Toaster />
+// anywhere
+toast.success('Saved')
+```

package/dist/agent/ToggleGroup.md

@@ -0,0 +1,44 @@
+# ToggleGroup
+
+A segmented control: several options, one strip.
+
+- Group: Forms
+- Import: `import { ToggleGroup } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/toggle-group/
+- Related: tabs, radio-group
+
+## When to reach for it
+
+It changes a VALUE. Something that switches panels is Tabs.
+
+## Accessibility
+
+- type="single" gets radio semantics; type="multiple" gets independent toggles. Choosing wrong tells a screen reader that picking one option unpicks the others.
+
+## Keyboard
+
+- Tab — Moves into the strip — one stop for the group.
+- ← / → — Moves between segments.
+- Enter / Space — Toggles the focused segment.
+
+## 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.
+
+Also accepts: `ComponentProps<typeof ToggleGroupPrimitive.Root>`.
+
+## ToggleGroupItem
+
+One segment. In a single-value group the item draws no background of its own — the travelling pill behind it does — so it only changes ink. In a multiple-value group it fills, because there is nothing travelling.
+
+Also accepts: `ComponentProps<typeof ToggleGroupPrimitive.Item>`.
+
+## Examples
+
+```tsx
+<ToggleGroup type="single" defaultValue="grid" aria-label="Layout">
+  <ToggleGroupItem value="grid">Grid</ToggleGroupItem>
+  <ToggleGroupItem value="list">List</ToggleGroupItem>
+</ToggleGroup>
+```

package/dist/agent/Tooltip.md

@@ -0,0 +1,51 @@
+# Tooltip
+
+A short label on hover and on focus.
+
+- Group: Overlays
+- Import: `import { Tooltip } from '@misoto22/design'`
+- Version: 0.6.0
+- Docs: https://ui.misoto22.com/components/tooltip/
+- Related: dialog
+
+## When to reach for it
+
+Never for anything the reader NEEDS: a tooltip is unreachable on touch and invisible while scanning.
+
+## 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.
+- The trigger is asChild, so the child must be focusable — a div trigger simply has no keyboard tooltip, which this API shape makes obvious rather than silent.
+- Not an accessible name. An icon-only button still needs its own aria-label.
+
+## Keyboard
+
+- Tab — Shows the tip — focus reveals it, not only hover.
+- Escape — Dismisses it.
+
+## TooltipProvider
+
+Wrap the app — or the smallest subtree that has tooltips — once. Radix needs it to share the open/close timing between neighbouring triggers, which is what stops a row of icon buttons flashing a tooltip per hover.
+
+## Tooltip
+
+A short label on hover and on focus. `asChild` on the trigger by design: the tooltip must not add a wrapper that swallows the trigger's own focus ring or breaks a flex row. It also means the child has to be focusable — a `<div>` trigger gets no keyboard tooltip, which is the failure this API shape makes obvious rather than silent. Not a replacement for an accessible name. An icon-only button still needs its own `aria-label`; the tooltip repeats that name for sighted pointer users.
+
+### Props
+
+- `children` (required) — `ReactNode`. The element the tooltip describes. Must be focusable.
+- `content` (required) — `ReactNode`. The tip. Keep it to a phrase — a tooltip is unreachable on touch and invisible to a reader who is scanning, so anything a user NEEDS belongs on the page instead.
+- `side` — `ComponentProps<typeof TooltipPrimitive.Content>['side']` default `'top'`.
+- `sideOffset` — `number` default `6`.
+
+Also accepts: `Pick<ComponentProps<typeof TooltipPrimitive.Root>, 'open' | 'defaultOpen' | 'onOpenChange' | 'delayDuration'>`.
+
+## Examples
+
+```tsx
+<TooltipProvider>
+  <Tooltip content="Copy to clipboard">
+    <Button iconOnly aria-label="Copy"><Copy size={16} /></Button>
+  </Tooltip>
+</TooltipProvider>
+```