@misoto22/design 0.7.0 → 0.9.0

package/dist/agent/Sheet.md

@@ -4,7 +4,7 @@ A panel docked to an edge of the viewport.
 
 - Group: Overlays
 - Import: `import { Sheet } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/sheet/
 - Related: dialog, popover
 
@@ -12,6 +12,29 @@ A panel docked to an edge of the viewport.
 
 A modal that needs room — a filter panel, a detail view. It IS a Dialog, docked; the sides are named in reading order, so `end` is the right in English and the left in Arabic.
 
+## Anatomy
+
+- **Scrim** (required) — The same --scrim at --z-overlay that Dialog uses — the same component, in fact, so the page behind is inert and scroll-locked exactly as it is under a dialog.
+- **Panel** (required) — The docked box. start and end are a min(24rem, 92vw) column at full height; top and bottom are a full-width band capped at 85vh. A flex column that scrolls itself.
+- **Title** (required) — title, typed as required rather than optional — there is no unnamed-sheet path to fall into, only a hidden-title one via hideTitle.
+- **Description** — description, under the title, sharing the wrapper that hideTitle hides.
+- **Close** (required) — The X in the top-end corner. Unlike Dialog there is no showClose to turn it off, so every sheet has one whichever edge it is docked to.
+
+## Best practices
+
+### Do
+
+- Reach for a Sheet over a Dialog when the content is a list or a form long enough to scroll: it gets the full height of the viewport rather than Dialog’s 32rem by 85vh box, and the reader keeps the page edge as an anchor.
+- Use top or bottom when the content is wide and short — a filter bar, a date range. start and end are a 24rem column, and a table pushed into one wraps into a ribbon.
+- Name the sides start and end rather than reaching for left and right: each edge has its own literal class string carrying its own rtl: variant, so end arrives from the right in English and the left in Arabic with no second code path.
+- Wrap the cancelling control in SheetClose so the close runs through Radix — a sheet closed by your own state setter leaves focus inside a panel that is no longer on the page.
+
+### Don’t
+
+- Do not re-declare the travel in className. The panel carries data-m22-animated, which removes its transform outright under reduced motion; a second transform of your own only gets the universal floor, so it still arrives — a hundredth of a millisecond later, from wherever you put it.
+- An OverlayContainer whose element is not positioned docks the sheet to the wrong box: naming a container switches the panel from fixed to absolute, so an unpositioned container sends it to the nearest positioned ancestor rather than to the frame.
+- It is a modal dialog, so the page behind is scroll-locked and pointer-inert: this is not the home for a filter panel the reader is meant to work alongside. That is a Popover, or a column in the layout.
+
 ## Accessibility
 
 - Shares Dialog’s focus trap, Escape handling and scroll lock rather than reproducing them — a second focus trap is a second one to get wrong.
@@ -32,7 +55,7 @@ Radix Dialog root, trigger and close — a sheet IS a dialog, docked.
 
 ## SheetContent
 
-A panel docked to an edge of the viewport. It is a modal dialog — Radix's, so the focus trap, the escape key, the scroll lock and the `aria-modal` wiring are the same ones `Dialog` gets. The only differences are where it sits and which way it arrives, which is why this shares that implementation rather than reproducing it: a second focus trap is a second focus trap to get wrong. The title is required, visible or not. A modal with no accessible name drops a screen reader into an unnamed region with no way back out.
+A panel docked to an edge of the viewport. It is a modal dialog — Radix's, so the focus trap, the escape key, the scroll lock and the `aria-modal` wiring are the same ones `Dialog` gets. The only differences are where it sits and which way it arrives, which is why this shares that implementation rather than reproducing it: a second focus trap is a second focus trap to get wrong. The title is required, visible or not. A modal with no accessible name drops a screen reader into an unnamed region with no way back out. Portals into the element an enclosing `OverlayContainer` names, docking to that element's edge rather than the viewport's when there is one.
 
 ### Props
 

package/dist/agent/Sidebar.md

@@ -0,0 +1,193 @@
+# Sidebar
+
+A navigation rail down the side of an application.
+
+- Group: Navigation
+- Import: `import { Sidebar } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/sidebar/
+- Related: nav-item, collapsible, app-shell
+
+## When to reach for it
+
+A whole application’s navigation, in a column that stays. A list of links inside a page is NavItem on its own; a strip of panels is Tabs.
+
+## Anatomy
+
+- **Provider** (required) — SidebarProvider. It holds whether the rail is open and binds the shortcut that changes it, and it sits ABOVE both the rail and the content beside it — the page has to reserve the rail’s width, and a state that lived inside the rail could only ever be read downwards. It also supplies the tooltip provider a collapsed rail needs, so the icon state works without the app being told to wrap itself in one.
+- **Rail** (required) — Sidebar. A <nav>, not an <aside>: the element decides the landmark, and a rail of links announced as “complementary” is not the one a reader jumps to when they go looking for the navigation. Its width animates between --sidebar-w and --sidebar-w-icon while the column inside stays full width, so the rows do not reflow under the wipe.
+- **Header** — SidebarHeader. The brand, the workspace, the switcher — and where SidebarTrigger belongs. A control that hides a thing lives on the thing; out in an application’s masthead it is one more anonymous icon with nothing connecting it to the column it operates.
+- **Content** — SidebarContent. The scrolling middle, and the only part that scrolls.
+- **Group** — SidebarGroup: a heading, an optional count, an optional action, and rows behind a hairline. The heading is the same size as its rows and outranks them by weight and one step of ink — smaller than what it contains, it reads as a footnote over a list rather than as a title over its own contents.
+- **Row** — SidebarItem, which is NavItem plus the two things a rail adds: a trailing slot, and an answer for the state with no room for words. Collapsed, the label leaves the layout and becomes the row’s tooltip.
+- **Branch** — SidebarBranch: a row that opens onto more rows, behind the same hairline a group draws and one indent further in. It is the line between a place and a heading — a workspace that contains projects is a place containing places, and it carries an icon and a state the way its children do, which a Group has neither of. Two levels is what the indent has room for; a third in a 16rem column is a horizontal scrollbar with an outline in it.
+- **Footer** — SidebarFooter. The utilities a rail ends on, kept out of the index above it.
+- **Page** — SidebarInset, the column beside the rail. It is `min-w-0` — the half every hand-written version forgets, and the reason one wide table inside pushes the page past the viewport and takes the rail’s width with it. Under variant="inset" it is also the panel: the rail becomes the ground, and this draws the bordered --paper surface sitting on it.
+- **Drawer** — What the rail becomes under the provider’s breakpoint (768px by default): fixed against its own edge, over a scrim, and inert while closed. Nothing to render — the same <Sidebar> is both — but it is a different component to a reader, and the collapsible setting does not apply there.
+
+## Best practices
+
+### Do
+
+- Give every row an icon if the rail collapses to icons. The icon is the whole of what a collapsed row shows, and SidebarItem keeps the label drawn on a row without one rather than leaving a blank line — which is a rail that is half collapsed.
+- Choose collapsible by what the rows ARE. icon suits a fixed set a reader learns the shape of; offcanvas suits a long index nobody memorises, where a column of unrecognisable glyphs is worse than no column.
+- Reach for SidebarBranch when the thing is a PLACE that contains places, and for SidebarGroup when it is a heading over a set. A group has no icon and no state because it is not somewhere you can be; a branch has both because it is.
+- Put SidebarTrigger in the header. It is where the component expects it and where a reader looks for it, and it is the difference between a control that belongs to the rail and one that has wandered into the masthead.
+- Wrap the page in SidebarInset rather than a hand-written flex column. It carries min-w-0, which is what stops one wide table inside the page from pushing the whole layout past the viewport, and it is the other half of variant="inset".
+- Pass persist with a key when the rail is an application’s own. A reader who put the rail away did not mean “until the next page”. Only the docked state is kept: restoring an open drawer is a page that loads with its navigation over the top of itself.
+- Give the provider a ground for variant="floating" and variant="inset" — bg-(--stone) on the element holding it. Both draw a --paper panel, and a panel on the same colour as the thing behind it is a border with nothing on either side of it.
+
+### Don’t
+
+- Do not reach for it for navigation inside a page. This is an application landmark that owns a whole edge of the window; a set of links in a column is NavItem, and putting those in a rail gives a page two navigation landmarks competing for the same reader.
+- Do not pass shortcut and then bind Cmd+B yourself. Two handlers on one chord toggle twice and land back where they started, which reads as a rail that ignores its own shortcut. Pass shortcut={null} where the app owns it.
+- Do not nest a branch inside a branch. The indent is sized for two levels at this width, and a third takes the words with it — what a reader gets is an outline with a horizontal scrollbar under it.
+- Do not control open without onOpenChange. The trigger and the shortcut then both do nothing, and the state that looks broken is the one the caller froze.
+- Do not put a transform, filter or perspective on an element wrapping the provider. The drawer is fixed, and any of those makes that ancestor its containing block — so it opens inside the wrapper instead of against the edge of the window.
+- Do not build the phone drawer yourself around this. It already is one under breakpoint, with the scrim, the inert closed state and the close-on-navigate; a second one outside gives the page two drawers and one of them has no scrim.
+
+## Accessibility
+
+- label is required, and names the landmark. A page with two navigations in it announces two things called “navigation” unless each says which it is.
+- The trigger’s name says what it will DO and aria-expanded reports what is true now, so it is never the permanently ambiguous “Toggle sidebar”.
+- A collapsed row keeps its label as its accessible name, through a tooltip — an icon alone is a guess for a sighted reader and nothing at all for a screen reader.
+- A collapsed group keeps its heading as the group’s name even though the words are not drawn.
+- The current row carries aria-current="page", not only a darker ground.
+- The closed drawer is inert, not merely translated off-screen. Off-screen it still holds focus and is still read aloud, so a shut drawer puts its whole index between the reader and the page they were on.
+- The scrim is a button with a name, because tapping beside a drawer is how a drawer is closed — and a gesture that exists only for a pointer is one a keyboard cannot make.
+
+## Keyboard
+
+- ⌘B / Ctrl B — Opens and closes the rail.
+- Enter / Space — On a group heading, folds or unfolds it.
+- Tab — Moves through the rows in the order they are drawn.
+
+## useSidebar
+
+The rail's own state, for anything that has to answer to it. A page beside the rail needs it to reserve the right width; a control inside needs to know whether its label is being drawn. This one THROWS outside a provider, and the parts above do not, and the difference is who made the mistake. A part rendered on its own is somebody writing `<Sidebar>` to see what it looks like; a call to this hook is code asking for state that nothing is keeping, and returning a plausible default there is a layout that is wrong in one state and right in the other with nothing to say which.
+
+## SidebarProvider
+
+Holds whether the rail is open, and binds the shortcut that changes it. Separate from `Sidebar` itself because the answer is needed on BOTH sides of the layout: the rail draws itself from it, and the content beside the rail reserves width from it. A state that lived inside the rail could only ever be read downwards.
+
+### Props
+
+- `open` — `boolean`. Controlled open state. Leave off to let the provider own it.
+- `defaultOpen` — `boolean` default `true`.
+- `onOpenChange` — `(open: boolean) => void`.
+- `collapsible` — `SidebarCollapsible` default `'icon'`. What closing does to the rail. See SidebarProps.collapsible.
+- `shortcut` — `string | null` default `'b'`. The keyboard shortcut that toggles the rail, as a single letter. `b`, with the platform's own modifier, because that is what every editor and every application shell already uses for the same thing. Pass `null` to bind nothing — an app that already owns that chord should not have it taken twice, and a rail that cannot be closed does not need a shortcut for closing it.
+- `side` — `SidebarSide` default `'start'`. Which edge the rail is on. Logical: `end` is the right in LTR, the left in RTL.
+- `variant` — `SidebarVariant` default `'flush'`. How the rail meets the page. `flush` is a column with a hairline down its inner edge — the rail and the page are one surface divided by a line. `floating` lifts the rail off that surface as its own bordered panel with the page ground showing around it. `inset` is the same gesture the other way up: the rail sits on the page ground and `SidebarInset` draws the CONTENT as the panel. `floating` and `inset` both need a ground to sit on — put `bg-(--stone)` on the element holding the provider, or they are a panel on the same colour as the thing behind it.
+- `breakpoint` — `SidebarBreakpoint | null` default `'md'`. The step below which the rail becomes a drawer over the page. A rail is a column when there is a column's worth of room and an overlay when there is not; below this the rail is `fixed`, covers the page from its own edge, and closes onto a scrim. `null` pins it as a column at every width, for a layout that is never narrow — an embedded console, a preview frame. Named, not a number: the switch is a media query in the stylesheet, and a class built from a runtime number is a class the compiler never emitted. It also puts the rail on the same four steps as the page around it.
+- `persist` — `string | null` default `null`. A `localStorage` key under which the DOCKED state is remembered. A reader who put the rail away did not mean "until the next page". Only the docked state is kept: an open drawer is a thing a reader did to this screen, and restoring it on the next visit is a page that opens with its navigation over the top of itself. Read after mount, never during render — a value from storage in the first pass is a hydration mismatch, and the markup the server sent is the one the client has to agree with.
+- `contained` — `boolean` default `false`. The drawer covers its nearest positioned ancestor rather than the window. For a rail inside a bounded frame — a device preview, an embedded console, an example on a documentation page. `fixed` resolves against the viewport wherever the markup sits, so without this the drawer inside a 400px preview opens across the whole page it is previewed on. Give the frame `relative`.
+- `children` (required) — `ReactNode`.
+
+## Sidebar
+
+A navigation rail down the side of an application. A `<nav>`, not an `<aside>`. The element decides the landmark, and a rail of links announced as "complementary" is not the one a screen reader user jumps to when they go looking for the navigation. Composed rather than configured: a rail is a header, a scrolling middle and a footer, and every product wants different things in all three. What this owns is the part that is the same everywhere — the width, the edge, the scroll behaviour, and what happens when it closes. **Closing has three shapes**, and `collapsible` on the provider picks one. `icon` keeps the rail and drops the labels, which is right when the rows are a fixed set a reader learns the shape of. `offcanvas` takes the whole rail away, which is right when the rows are a long index nobody memorises. `none` is a rail that does not close. The trigger belongs INSIDE the rail — `SidebarHeader` places it — rather than out in an application's masthead. A control that hides a thing should live on the thing: in the masthead it is one more anonymous icon in a row of them, and nothing connects it to the column it operates. **Under the provider's `breakpoint` it is a drawer**, not a column: `fixed` against its own edge, over a scrim, and `inert` while closed. Merely translating it off-screen is not closed — it keeps focus and it is still read aloud, so a shut drawer puts its whole index between the reader and the page they were on. The scrim is a real button, because tapping beside a drawer is how a drawer is closed and that gesture has to exist for a keyboard too. `fixed` resolves against the viewport unless an ancestor has a `transform`, `filter` or `perspective`, which makes that ancestor the containing block instead. Do not put one on an element wrapping the provider, or the drawer opens inside it.
+
+### Props
+
+- `label` (required) — `string`. Names the landmark. Required: a page with two navigations in it announces two things called "navigation" unless each of them says which it is.
+- `scrimLabel` — `string` default `'Close the navigation'`. What the scrim behind the open drawer announces. It is a button — tapping beside a drawer closes it, and that has to be a control a keyboard and a screen reader can reach, not a decorated `<div>`.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `Omit<ComponentProps<'nav'>, 'children'>`.
+
+## SidebarInset
+
+The page beside the rail. Every layout built on this component was writing the same `flex min-w-0 flex-1 flex-col` by hand, and `min-w-0` is the half everybody forgets: a flex child's floor is its content, so one wide table inside pushes the whole page past the viewport and takes the rail's width with it. It is also the other half of `variant="inset"`. There the rail is the ground and this is the panel — a bordered `--paper` surface with the ground showing around it — which is why the variant lives on the provider rather than on either piece: one setting, two components, and no way to set half of it. A `<div>`, not a `<main>`. What goes in here is usually a masthead AND the page under it, and only one of those is the main landmark.
+
+## SidebarHeader
+
+The block at the top of the rail: a brand, a workspace, a switcher. It is also where `SidebarTrigger` belongs, and the layout assumes one: anything passed as `children` takes the space and the trigger sits at the inline end of the row.
+
+## SidebarContent
+
+The scrolling middle. Everything that is a list of places goes here.
+
+## SidebarFooter
+
+The block at the bottom: the utilities, the account, the thing a rail ends on. A separate landmark from the content above it because it is a separate kind of thing — a reader scanning the index does not want Trash and Help in it.
+
+## SidebarSeparator
+
+A rule between blocks of rows, inset to the rail's own padding.
+
+## SidebarTrigger
+
+The control that opens and closes the rail. Its accessible name changes with what it will DO, and `aria-expanded` reports what is true now — a button permanently called "Toggle sidebar" tells a screen reader user nothing about which way it will go.
+
+### Props
+
+- `labels` — `{ open: string; close: string }` default `{ open: 'Open the sidebar', close: 'Close the sidebar' }`. What the button announces. Both states, because it says both things.
+
+Also accepts: `ComponentProps<'button'>`.
+
+## SidebarGroup
+
+A labelled block of rows, optionally foldable. The heading is the same SIZE as the rows beneath it and outranks them by weight and by ink. Both halves of that are corrections. Smaller, it inverted the hierarchy it exists to express — a group read as a footnote over a list rather than as a title over its own contents. In the MONO face, which is where it went next, ten of them stacked in a column read as a terminal listing: mono is this system's voice for code, metadata and figures, and a navigation heading is none of those. Rank belongs to weight and to a step up the ink ladder, which are the two signals that can outrank a row without changing what kind of thing it is. An open group draws a hairline down its rows. Fifty rows under seven headings have nothing in them saying which heading any given row belongs to — only the distance to the last one, which is gone the moment the list is scrolled. The whole block hides when the rail is collapsed to icons: a heading with no room for its own word is two or three letters and a number, and the rows are still there underneath as icons.
+
+### Props
+
+- `label` (required) — `string`. The heading over the rows.
+- `count` — `number`. How many rows are inside, printed on the far side of the heading.
+- `badge` — `ReactNode`. A mark that belongs to the GROUP — "Beta", "3 new". Beside the label, not out at the end with the count: it qualifies the words, and a qualifier that has drifted to the other side of the row reads as a second, unrelated fact.
+- `action` — `ReactNode`. A control on the heading row — a menu, an "add" button. Sits between the label and the count, and is NOT rendered inside the heading's own button: a control nested in a control is one the keyboard reaches by pressing the thing it is inside.
+- `collapsible` — `boolean` default `true`. Whether the group folds at all. A group of two rows usually should not.
+- `defaultOpen` — `boolean` default `true`.
+- `children` (required) — `ReactNode`.
+- `className` — `string`.
+
+## SidebarBranch
+
+A row that opens onto more rows. The thing a rail is for and the thing a flat list of groups cannot do: a workspace with projects in it, a folder with documents in it, a service with its environments. `SidebarGroup` is a HEADING over a set — it is not itself a place, and it has no icon and no state. This is a place that contains places, so it is a row like any other and it carries the same icon, trailing slot and hover as its children. The children sit behind the same hairline a group draws, one indent further in, so nesting reads as depth rather than as two unrelated lists. Two levels is what the indent has room for at this width; a third is a tree, and a tree in a 16rem column is a horizontal scrollbar with an outline in it. Collapsed to icons the row becomes its icon and the children are not drawn — there is nowhere for an indent to go, and a nested icon under an unnested one is two glyphs with no visible relationship.
+
+### Props
+
+- `label` (required) — `string`. The row's own words, and the name of the group it opens.
+- `icon` — `LucideIcon`. Drawn at the start of the row, and the whole of the row when collapsed.
+- `trailing` — `ReactNode`. A count or a state at the end of the row.
+- `defaultOpen` — `boolean` default `false`.
+- `open` — `boolean`.
+- `onOpenChange` — `(open: boolean) => void`.
+- `children` (required) — `ReactNode`.
+- `className` — `string`.
+
+## SidebarItem
+
+One row. `NavItem` with the two things a RAIL adds: a trailing slot, and an answer for the state where there is no room for words. Collapsed to icons the label is removed from the layout rather than hidden with CSS — a `sr-only` label still occupies the flex row's gap — and moves into a tooltip, because an icon on its own is a guess for everyone and unusable for a screen reader. A row with no `icon` keeps its label collapsed, since hiding it would leave a blank row: the icon is what makes the collapsed state legible, and a rail that collapses needs one on every row.
+
+### Props
+
+- `trailing` — `ReactNode`. A count or a state on the far side of the row. Hidden with the label.
+
+Also accepts: `NavItemProps`.
+
+## Types
+
+- `SidebarCollapsible` = `'icon' | 'offcanvas' | 'none'`
+- `SidebarSide` = `'start' | 'end'`
+- `SidebarVariant` = `'flush' | 'inset' | 'floating'`
+- `SidebarBreakpoint` = `'sm' | 'md' | 'lg' | 'xl'`
+
+## Examples
+
+```tsx
+<SidebarProvider>
+  <Sidebar label="Documentation">
+    <SidebarHeader>Acme</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup label="Guide" count={2}>
+        <SidebarItem href="/start" icon={Home}>Getting started</SidebarItem>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+</SidebarProvider>
+<SidebarBranch label="Acme HQ" icon={Building} defaultOpen>
+  <SidebarItem href="/hq" icon={Home}>Home</SidebarItem>
+  <SidebarItem href="/hq/tasks" icon={CheckSquare}>My tasks</SidebarItem>
+</SidebarBranch>
+```

package/dist/agent/Skeleton.md

@@ -4,7 +4,7 @@ The shape of the page, before the page.
 
 - Group: Feedback
 - Import: `import { Skeleton } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/skeleton/
 - Related: spinner, empty-state
 
@@ -12,6 +12,28 @@ The shape of the page, before the page.
 
 A wait the reader would otherwise think was a broken page. A shape that describes what is coming beats a dot that describes nothing.
 
+## Anatomy
+
+- **Frame** (required) — SkeletonPage: the div carrying role="status", aria-busy="true" and the single pulse. It is the only part that speaks and the only part that moves — the shapes inside it do neither.
+- **Label** (required) — The sr-only sentence inside the frame, from the required label prop. Every shape is aria-hidden, so this one sentence is the entire loading state for a screen reader.
+- **Fill** — Skeleton itself: a --stone rectangle one line tall — h-3 — and, being a div, already full width. Height is the one dimension the element does not have on its own, so that is the one the base supplies; anything in className replaces it.
+- **Line, Block and Circle** — The three presets over that fill. SkeletonLine is a 12px pill and takes its width from the caller, SkeletonBlock only sets --radius-sm, and SkeletonCircle is a fixed 36px round.
+- **Paragraph** — SkeletonText: three lines by default, the last at 62% so it ends mid-measure the way prose does rather than squaring off into a table.
+
+## Best practices
+
+### Do
+
+- Wrap the shapes in SkeletonPage even when there is only one bar. The role, the aria-busy and the pulse all live on the frame, so parts used loose are aria-hidden, silent and completely still — a grey rectangle that never resolves.
+- Give every Skeleton the height of the thing it stands in for. The base falls back to one line, so a block left unsized is no longer invisible — it is a 12px bar where a 160px plate is about to land, and the page jumps by the difference.
+- Make whatever replaces the skeleton announce itself or take focus. aria-busy never flips to false here — the frame is unmounted, not updated — so the end of the wait is the disappearance of the only thing that was speaking.
+
+### Don’t
+
+- Do not add animate-pulse to a part. The frame already animates opacity and a second ramp on a child multiplies with it, so the part beats at a rate the shape around it does not. Reduced motion is not the reason it is wrong: the rule in keyframes.css is a universal floor on animation-duration and transition-duration, so a hand-written Tailwind animation is clamped along with everything else. data-m22-animated is a component asserting its motion is decorative, not the mechanism that does the cancelling.
+- Do not nest one SkeletonPage inside another. Each is a role="status" region with its own sr-only sentence, so a page assembled from two skeleton sections announces two loading messages and marks two regions busy for a single wait.
+- Do not carry a skeleton between screens unedited. SkeletonCircle is 36px and SkeletonLine is 12px tall whatever they stand in for, so a copied avatar mount and a copied heading are two guaranteed reflows the moment the real content lands.
+
 ## Accessibility
 
 - One live region on the wrapper; every shape inside it is aria-hidden.
@@ -19,7 +41,7 @@ A wait the reader would otherwise think was a broken page. A shape that describe
 
 ## 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.
+The fill every skeleton part is drawn from: `--stone`, at the height of one line until something says otherwise. 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. `h-3` is a default rather than a design. A `<div>` is already full width, so height was the one dimension a caller could omit and get nothing for — a bare `<Skeleton />` was a zero-height box, which is not a small skeleton but an absent one. Twelve pixels is the height `SkeletonLine` already chose, and any class the caller passes replaces it.
 
 Also accepts: `HTMLAttributes<HTMLDivElement>`.
 

package/dist/agent/Slider.md

@@ -4,14 +4,39 @@ A value chosen along a range.
 
 - Group: Forms
 - Import: `import { Slider } from '@misoto22/design'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/slider/
 - Related: progress
 
+## Anatomy
+
+- **Track** (required) — A 1px rule in --stone that thickens to 1.5 when the pointer is anywhere over the control, not only over the thumb.
+- **Range** — The --accent fill from the minimum to the thumb, or between the two thumbs of a range.
+- **Thumb** — One per entry in the value array — so the number of thumbs comes from the value, not from a prop, and a slider given neither value nor defaultValue falls back to the primitive’s own default of one thumb at the minimum. Each is a 16px circle with an invisible 44px hit area from a before pseudo-element.
+- **Value readout** — Only with showValue: a mono row above the track, the names on the start edge and the formatted values on the end, each joined by an en dash and in the thumbs’ own order — so a two-ended range reads “Minimum – Maximum” over “10 – 90”.
+- **Editable readout** — What editable turns those figures into: one box per thumb, showing format’s output at rest and the bare number while it has focus, so a reader still sees “$1,200” and a typist is never asked to type a currency symbol back. Each is named separately from its thumb — two controls announcing “Quality” is one control announced twice.
+
+## Best practices
+
+### Do
+
+- Pass defaultValue or value whenever there is more than one end to it. The thumb count comes from that array, so a price filter left to the default is a single thumb sitting at the minimum.
+- Pass an array of two names for a two-thumb range: every thumb after the first falls back to names[0], so both ends of a price filter otherwise announce themselves as “Minimum”.
+- Turn on editable when the exact number matters. A slider on its own cannot be typed into, and someone who needs 37 rather than roughly 40 is dragging a 16px thumb across a hundred steps to get it — the box in the readout is the way out, and it replaces the second Input this used to ask for.
+
+### Don’t
+
+- format becomes each thumb’s aria-valuetext, which REPLACES the number rather than decorating it — so a formatter that rounds hard or drops the unit is what a screen reader gets instead of the value.
+- editable typing is bounded by the NEIGHBOURING thumb as well as by min and max, and it has to be: 90 typed into the lower end of a range sitting at 70 would otherwise cross the two thumbs over. So a number can be accepted and then land somewhere else, and the box shows where it landed.
+- Do not disable a slider to make it read-only: the whole control dims and stops taking the pointer, and Radix drops the thumb out of the tab order, so the value becomes unreachable rather than uneditable.
+- Do not pass two names to a one-thumb slider: the heading prints one name per THUMB, so the second is drawn nowhere and announced nowhere.
+- A Field’s label above it does not name it and does not click through: the role is on the THUMB and the root is a <span>, so the label prop here is the only name a reader hears. The hint and the error do reach the thumb.
+
 ## 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.
+- format is announced as aria-valuetext, so a thumb showing “$1,200” says that rather than 1200.
 - Arrows step, Page keys jump, Home and End reach the ends.
 
 ## Keyboard
@@ -22,13 +47,14 @@ A value chosen along a range.
 
 ## 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.
+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. `editable` is the answer to the thing a slider cannot do. Reach for it whenever the exact figure is the point — a budget, a timeout, a price — and leave it off when the value is genuinely approximate, because a box invites precision the setting may not have. Inside a `Field`, the hint, the error and the requirement land on the THUMB, which is the element carrying `role="slider"` — on the root they would sit on a `<span>` with no role and announce nothing. The NAME still comes from `label` here: a field's label above a slider points at that same roleless root, so it neither names the control nor clicks through to it.
 
 ### 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 + '%'`.
+- `showValue` — `boolean` default `false`. Prints the current value beside the label. A two-thumb range prints both names and both values, in the same order — the heading used to print the first name over a pair of numbers, which read as "Minimum" over "10 – 90".
+- `editable` — `boolean` default `false`. Turns that readout into a box the number can be typed into, and implies `showValue`. A slider is a control for a NEIGHBOURHOOD; someone who needs 1,150 rather than roughly 1,200 is dragging a 16px thumb across a hundred steps to get it. This is the way out, in the place the value already is, rather than a second field beside the track that has to be kept in step by hand. The box shows `format`'s output at rest and the bare number while it has focus, so a reader still sees "$1,200" and a typist is never asked to type a currency symbol back.
+- `format` — `(value: number) => string`. Renders the value with a unit or a currency, e.g. `(n) => n + '%'`. Reaches assistive tech as well as the readout: it becomes each thumb's `aria-valuetext`, so a thumb showing "$1,200" announces that rather than the bare number. Left off, the platform announces the value itself.
 
 Also accepts: `ComponentProps<typeof SliderPrimitive.Root>`.
 
@@ -36,4 +62,5 @@ Also accepts: `ComponentProps<typeof SliderPrimitive.Root>`.
 
 ```tsx
 <Slider label="Quality" defaultValue={[80]} max={100} step={5} showValue format={(n) => `${n}%`} />
+<Slider label="Monthly budget" defaultValue={[1200]} max={5000} step={50} editable format={(n) => `$${n}`} />
 ```

package/dist/agent/Sparkline.md

@@ -4,7 +4,7 @@ A run of numbers at the size of a word.
 
 - Group: Data
 - Import: `import { Sparkline } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/sparkline/
 - Related: line-chart, table
 
@@ -12,6 +12,28 @@ A run of numbers at the size of a word.
 
 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.
 
+## Anatomy
+
+- **Inline row** (required) — An inline-flex span, full width with 8px of gap, so the run sits in a table cell or beside a figure without breaking the line it is on.
+- **Plot** (required) — One svg role="img" over a 0–100 by 0–100 viewBox with preserveAspectRatio="none", so it stretches to whatever width the container gives it. height, 28px by default, is the only fixed dimension.
+- **Mark** (required) — The path, its area fill, or the bars — variant picks one. The stroke is drawn with non-scaling-stroke, which is what keeps the line the same weight in a narrow cell and a wide one after the box has been stretched to fit.
+- **Last point** — A 2px dot on the final reading, from showLast, on the line and area variants. The bars variant carries the end of the run in its own last bar and draws no dot.
+- **Printed value** — value, in mono tabular figures after the plot. It is also what the accessible name says after the label, and it is the only figure this component ever prints.
+- **Too-short state** — What renders in place of the whole plot when fewer than two finite numbers survive: the label and “not enough data”, as one line of mono meta text.
+
+## Best practices
+
+### Do
+
+- Pass value whenever a figure matters. The plot has no axis and no scale, so it carries shape and nothing else, and value is both the one number printed and the reading appended to the accessible name. Left out, that name falls back to the last point through toLocaleString — the raw number, without the unit, the currency or the rounding the row beside it uses.
+- Pin domain across any two that will be read against each other. Each run is normalised into the same fixed box from its OWN min and max, so the highest point always touches the top edge and the lowest always the floor: a series moving between 4 and 6 and a series moving between 400 and 900 draw the same silhouette, and the difference between them is drawn nowhere.
+- Downsample a long run before handing it over. The x step is 100 divided by one less than the number of points, spread across whatever width the cell has, so four hundred readings in a 200px cell land half a pixel apart and the path fills in as a band.
+- Read a flat line through the middle as “unchanged”, not as “at its floor”. A run whose min equals its max has a scale with no width, so no position on it is truer than another and every point sits at the centre — the same answer Heatmap and BulletChart give a zero span, and the one that keeps “unchanged” and “pinned at its worst” apart in a column of them.
+
+### Don’t
+
+- Do not assume something chart-shaped always renders. Non-finite entries are filtered out first, and anything left under two points returns a line of text instead of an SVG, so the new account’s row is a sentence where every other row in the column is a chart.
+
 ## Accessibility
 
 - label is required and is the whole accessible name: a sparkline has no axes and no legend, so nothing else describes it.

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