@misoto22/folio 0.0.0 → 0.16.0

package/dist/agent/Accordion.md

@@ -0,0 +1,65 @@
+# Accordion
+
+Disclosure rows that open in place.
+
+- Kind: component
+- Group: Navigation
+- Import: `import { Accordion } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/accordion/
+- Related: tabs
+
+## When to reach for it
+
+The marker is a plus, not a chevron: a plus says “this opens”, a chevron says “there is more below”.
+
+## Anatomy
+
+- **Row** (required) — AccordionItem — one hairline-ruled record, keyed by the value Radix opens and closes it by. The set is the root above it: type="single" with collapsible for an FAQ, type="multiple" for a stack of settings.
+- **Heading** (required) — Radix’s Accordion.Header, which is an <h3> and takes no level prop. Every row therefore adds an h3 to the document outline, wherever the accordion happens to sit.
+- **Trigger** (required) — The full-width button inside that heading: title against the start edge, marker against the end, py-4. It is also what names the open panel.
+- **Marker** (required) — A 16px plus, aria-hidden, rotating 45° into a minus when the row opens. The state it draws is carried for everyone else by aria-expanded on the trigger.
+- **Panel** — Radix’s Content — a role="region" labelled by its trigger, mounted only while open, overflow-hidden so its measured height can animate, with pb-4 pe-8 inside so the text stops short of the marker’s column. It carries data-folio-animated, so the open and close are dropped outright for a reader who asked for less motion.
+
+## Best practices
+
+### Do
+
+- Pass collapsible alongside type="single": without it there is no empty value to return to, so the first row the reader opens is a row they can never close again.
+- Key each item by something stable rather than by its position — Radix tracks the open row by value, so re-ordering or filtering the list leaves whatever now sits in that slot standing open.
+- Write the title as the whole question: it is the accessible name of the panel as well as of the trigger, so a row titled “More” opens a region called “More”.
+- Reach for type="multiple" when two rows have to be read against each other — single closes the one the reader was holding in order to open the one they wanted to compare it with.
+
+### Don’t
+
+- A closed row’s content is not in the DOM, so an FAQ built out of these is invisible to find-in-page and prints as a list of questions — anything that has to be searchable or printable belongs in the page.
+- The trigger is fixed at h3 by Radix’s header, so an accordion under an <h3> lists its rows as that heading’s siblings and the outline goes flat exactly where it should have nested.
+- The panel is overflow-hidden — that is what lets the open height animate — so anything inside that must escape the row’s box has to portal out of it; a menu that renders in place is cut off at the row’s edge.
+
+## Keyboard
+
+- Tab — Moves between rows.
+- Enter / Space — Opens or closes the focused row.
+
+## Accordion
+
+Radix root, re-exported. Pass `type="single" collapsible` for an FAQ and `type="multiple"` for a settings stack; Radix's own discriminated union then types `value` correctly for each.
+
+## AccordionItem
+
+One disclosure row: a hairline-ruled trigger and its panel. The marker is a plus that rotates into a minus, not a chevron. A chevron says "there is more below"; a plus says "this opens" — and in a stack of rows the difference decides whether the reader expects navigation or expansion. The panel animates on Radix's own `--radix-accordion-content-height`, so it opens to its real height without measuring anything at the call site.
+
+### Props
+
+- `title` (required) — `ReactNode`. The row's summary — what the reader clicks. Named `title` rather than inherited from the DOM attribute of the same name, which is a tooltip.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `Omit<ComponentProps<typeof AccordionPrimitive.Item>, 'children' | 'title'>`.
+
+## Examples
+
+```tsx
+<Accordion type="single" collapsible>
+  <AccordionItem value="ship" title="How do I ship it?">Push to main.</AccordionItem>
+</Accordion>
+```

package/dist/agent/Actions.md

@@ -0,0 +1,49 @@
+# Actions
+
+Share action menus and a scroll-to-top control.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { ActionMenu } from '@misoto22/folio/website'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/actions/
+
+## When to reach for it
+
+Connect generic accessible controls to host-owned share and scroll intentions.
+
+## Best practices
+
+### Do
+
+- Supply localized labels, descriptive links and meaningful image alternatives.
+
+### Don’t
+
+- Do not put service credentials, routing logic or backend models inside presentation components.
+
+## ActionMenu
+
+A collision-aware action menu with roving focus and an optional native trigger.
+
+### Props
+
+- `label` (required) — `string`.
+- `icon` (required) — `ReactNode`.
+- `items` (required) — `ActionMenuItem[]`.
+- `open` (required) — `boolean`.
+- `onOpenChange` (required) — `(open: boolean) => void`.
+- `side` — `'top' | 'bottom'` default `'bottom'`.
+- `align` — `'start' | 'center' | 'end'` default `'center'`.
+- `onTriggerAction` — `() => void`. A host-native action may replace the menu on a supported device.
+- `className` — `string`.
+
+## ScrollControl
+
+Page position belongs to the host; visibility and a safe tab stop belong here.
+
+### Props
+
+- `label` (required) — `string`.
+- `visible` (required) — `boolean`.
+- `onActivate` (required) — `() => void`.

package/dist/agent/Alert.md

@@ -0,0 +1,65 @@
+# Alert
+
+A message about the page, in place.
+
+- Kind: component
+- Group: Feedback
+- Import: `import { Alert } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/alert/
+- Related: toast, error-state
+
+## When to reach for it
+
+Something the reader needs to see and may need to act on. Something they only need to notice is a Toast.
+
+## Anatomy
+
+- **Region** (required) — The container, carrying the role and the aria-live the tone chooses, plus the tone’s ground. It is not focusable and it is not a landmark, so it exists for the reader who is already there and for the announcement.
+- **Mark** — The tone’s Remix Icon glyph at 18px — RiInformationLine, RiCheckboxCircleLine, RiAlertLine or RiCloseCircleLine — aria-hidden, so it doubles the colour for sighted readers only. hideIcon removes it.
+- **Title** — title, as a medium-weight paragraph in --ink. A p and not a heading, so it never appears in a screen reader’s heading list.
+- **Body** — children, in --ink-2 at relaxed leading, offset from the title only when there is a title to offset from.
+- **Action** — action, below the body and inside the region — so its label is read out with the message rather than being something the reader has to go looking for.
+
+## Best practices
+
+### Do
+
+- Mount the Alert when there is something to say and unmount it when there is not. A region kept permanently in the page announces only when its words change, so a second failed submit carrying the same message is announced to nobody.
+- Move focus after a failed submit — to the Alert or to the field it names. The component announces and then stays put, so a keyboard reader hears the error from wherever they were standing and has no way back to it.
+- Put the retry, the link or the escape in action rather than describing it in the prose. It sits inside the live region, which is the difference between the announcement telling the reader what to do and merely telling them something is wrong.
+
+### Don’t
+
+- hideIcon takes away one of the two things that double the colour, and the tinted grounds are 13–16% alpha over paper. With the mark gone the severity is carried by a wash the reader may not resolve at all, so the words have to say it outright.
+- info is the default and the only tone with a border and no tint — --paper-2 inside a --rule-2 hairline, which is a card. An Alert written without tone therefore looks like page furniture rather than like a notice.
+- Do not stack alerts as a running log. Each one is its own live region, so five on a page are five announcements competing for the same speech queue, and a danger among them is assertive enough to cut off the four that explain it.
+
+## Accessibility
+
+- danger is role="alert" and interrupts; the other three are role="status" and wait for a pause.
+- Colour is doubled by an icon and by the words.
+
+## Alert
+
+A message about the page, in place. Carries `role="alert"` for the danger tone and `role="status"` for the rest, which is the difference between interrupting the reader and waiting for a pause. Getting that backwards is the usual accessibility failure here: a "saved" toast that talks over someone mid-sentence, or a payment error that is never announced at all. The tone is the message's SEVERITY, not its decoration. Colour is doubled by an icon and by the words, so the meaning survives both monochrome printing and colour-blindness.
+
+### Props
+
+- `tone` — `AlertTone` default `'info'`.
+- `title` — `ReactNode`.
+- `children` — `ReactNode`.
+- `action` — `ReactNode`. Optional action — a retry, a link to the settings that fix this.
+- `hideIcon` — `boolean` default `false`. Hides the leading icon for a dense inline notice.
+
+Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.
+
+## Types
+
+- `AlertTone` = `'info' | 'success' | 'warning' | 'danger'`
+
+## Examples
+
+```tsx
+<Alert tone="danger" title="Upload failed">The file exceeds 25 MB.</Alert>
+```

package/dist/agent/AppShell.md

@@ -0,0 +1,69 @@
+# AppShell
+
+Two columns on a desktop, a drawer on a phone.
+
+- Kind: component
+- Group: Surfaces
+- Import: `import { AppShell } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/app-shell/
+- Related: nav-item, page-header
+
+## Anatomy
+
+- **Frame** (required) — The root: min-h-svh on --paper, one column on a phone and a 15rem sidebar beside a 1fr content column from md up. It is the grid and nothing else — no padding, no measure.
+- **Sidebar** (required) — An <aside> named by sidebarLabel, 15rem wide. A static grid column on a desktop; on a phone a fixed drawer that slides in from the edge reading STARTS at, so it comes from the right in a right-to-left document.
+- **Brand** — brand, in a 3.5rem row at the top of the sidebar above a hairline — the same height as the topbar, so the two rules meet across the column boundary. Omit it and the nav starts at the top and that line is gone.
+- **Nav** (required) — A <nav> named by navLabel, “Primary” by default, holding the sidebar prop. It is the part that scrolls, with scroll-slim, so a list that outgrows the column moves under a brand that stays put.
+- **Topbar** (required) — A sticky 3.5rem header at --paper/85 with a backdrop blur and a hairline under it, holding the toggle and then topbar. It is rendered whether or not you pass one.
+- **Drawer toggle** — A 44px button, phone-only, swapping Menu for X and carrying aria-expanded plus aria-controls pointing at the sidebar. Its only name is openLabel or closeLabel.
+- **Scrim** — A full-screen <button> named by closeLabel, mounted only while the drawer is open and hidden from md up.
+- **Content well** (required) — contentAs — a <main> by default — centred at --w-page with --page-pad either side and py-8. The measure and the page padding are the shell’s, so a child that adds its own puts a second measure inside the first.
+
+## Best practices
+
+### Do
+
+- Pass contentAs="div" for a shell rendered inside another page — a documentation preview, a screenshot harness. A document may hold exactly one main, and the second one leaves assistive tech unable to answer “where is the content”.
+- Name both landmarks when a page could hold two shells: sidebarLabel and navLabel are the only way one complementary is told from another, and the only way a non-English app gets landmark names its readers can read.
+- Translate openLabel and closeLabel with everything else — the toggle holds an icon and no text, so those strings are its entire accessible name on every page of the app.
+- Put the whole sidebar in the sidebar prop and let the nav scroll it: build the column yourself with the brand inside it and a long list carries the brand off the top of the screen with it.
+
+### Don’t
+
+- Do not treat the closed drawer as unmounted: below md it is translated off-screen and marked inert, not removed, so everything inside it still renders and still runs its effects — a nav item that measures itself measures a box nobody can see.
+- Do not assume no topbar means no bar: the header renders regardless, so a shell with nothing to put up there still costs 3.5rem and a rule across the page.
+- Do not wrap the children in your own max-width and page padding — the well already applies both, and the content ends up in the middle of the middle.
+
+## Accessibility
+
+- The drawer closes on Escape as well as on the scrim, so a keyboard user is not stranded inside it.
+- The scrim is a <button>, because a div with an onClick is neither reachable nor announced.
+- Below md the closed drawer carries inert, so its links are out of the tab order and out of the accessibility tree rather than merely off screen. Above md it never is: there the sidebar is the page’s navigation column.
+- Both ways out return focus to the toggle. Focus left inside an inert subtree is focus the browser throws away, and the scrim is worse — it is the focused element and it unmounts.
+
+## AppShell
+
+Two columns on a desktop, one column and a drawer on a phone. The drawer closes on Escape as well as on the scrim, because a drawer that only closes by tapping outside it strands a keyboard user inside a menu they cannot leave. The scrim is a `<button>` for the same reason — a `<div>` with an `onClick` is not reachable by keyboard and not announced as anything. Below `md` the closed drawer is `inert`. Sliding it off-screen is a visual state and nothing more: without that attribute every link in it stays focusable and stays in the accessibility tree, so Tab from the toggle walks into a menu nobody can see. Closing it also returns focus to the toggle, because the element focus was on is the element that just left.
+
+### Props
+
+- `sidebar` (required) — `ReactNode`. Navigation content for the sidebar (e.g. a stack of `NavItem`s).
+- `topbar` — `ReactNode`. Optional content for the sticky topbar, laid out after the mobile toggle.
+- `brand` — `ReactNode`. Optional brand lockup pinned to the top of the sidebar.
+- `contentAs` — `'main' | 'div'`. Which element the content well renders as. `main` is right for the shell of an application, and is the default. A document may contain exactly one `main` landmark, so an AppShell rendered INSIDE another page — a preview on a documentation site, a screenshot harness — must pass `div`, or the page has two and assistive tech can no longer answer "where is the content".
+- `sidebarLabel` — `string` default `'Sidebar'`. Names the sidebar landmark. Two `complementary` landmarks with the same name cannot be told apart, and a shell rendered inside another page — a preview, a screenshot harness — makes exactly that pair. It is also the only way a non-English app gets a landmark name its readers can read.
+- `navLabel` — `string` default `'Primary'`. Names the navigation landmark inside the sidebar.
+- `openLabel` — `string` default `'Open navigation'`. The drawer toggle, closed and open.
+- `closeLabel` — `string` default `'Close navigation'`.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Examples
+
+```tsx
+<AppShell brand={<Wordmark />} sidebar={<NavItem href="/">Home</NavItem>}>
+  <Card>…</Card>
+</AppShell>
+```

package/dist/agent/ArchitectureFigure.md

@@ -0,0 +1,72 @@
+# ArchitectureFigure
+
+A component map: services, datastores, trust boundaries, and what talks to what.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { ArchitectureFigure } from '@misoto22/folio/diagrams'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/architecture-figure/
+- Related: dataflow-figure, diagram, diagram-canvas
+
+## When to reach for it
+
+Reach for it when the question is "what talks to what". If the question is "in what order", that is a workflow or a sequence; if it is "what is in this arrow", that is a data flow.
+
+## Anatomy
+
+- **Figure shell** (required) — The frame all five figures sit in — a serif title, the scrolling paper surface, the role="img" svg. What a map hands it is the relationship list: every connection published as "CloudFront → API: HTTPS", which is the sentence this diagram type exists to make.
+- **Grid** (required) — What row and col index into: a 184 × 72 cell with 64 and 76 unit gutters, overridable per figure through spec.layout — where cellW is the pitch AND the width of the plates drawn at it. A component declaring neither row nor col flows into the next free cell, wrapping at layout.cols; pos replaces the grid entirely and puts the box at an absolute coordinate.
+- **Component plate** (required) — One box per component: a sigil and an eyebrow on the top line, the name at reading size, the sublabel in mono under it. The eyebrow prints the component’s own tag when it has one and the kind word otherwise, and the box grows past a declared height rather than printing through its own bottom rule.
+- **Boundary frame** — A labelled rule around the union of the boxes its wraps names, inflated by pad — 28 units by default. Solid for a region, dashed for a security-group, so where a thing runs and what may reach it are two different lines before either label is read.
+- **Connections** — Lines that leave and arrive perpendicular to a face, spread across that face when several share it, each with its wording on a mask that punches the line out from under itself.
+- **Key** — The kinds actually drawn, each shown with the same sigil the plates carry. legend="all" names all seven instead; legend="hidden" prints none.
+
+## Best practices
+
+### Do
+
+- Build a new spec object when something changes. The model is memoised on the spec’s identity, so mutating spec.components in place leaves the same reference and the figure goes on drawing the picture it was first given — development prints DIAGRAM_SPEC_MUTATED when it catches that, and a production build prints nothing and still draws the old picture.
+- Place both ends with pos when a connection carries a hand-tuned via, channelX or channelY. Those are honoured only when both endpoints were placed absolutely — on the grid they are coordinates in a space this renderer did not choose, so a route between two row/col components is dropped and re-routed.
+- Drive a guided reading yourself. meta.views typechecks and no renderer reads it — a chapter is a control rather than a layout — so the chapter’s focus ids have to arrive as activeIds, which is what dims everything else and adds the "n highlighted" status line.
+- Leave row and col off the components you have no opinion about. They flow into the next free cell in declaration order, wrapping at layout.cols and stepping around whatever the placed ones claimed — a component declaring neither used to mean row 0, column 0, which is one plate with the rest of them underneath it.
+
+### Don’t
+
+- Two components on one cell are still two plates at one coordinate, one drawn over the other: there is no second place to put the second plate. Development prints DIAGRAM_CELL_COLLISION naming both, which is the only signal — the picture is identical either way.
+- A boundary silently shrinks to the components it can find. A wraps id no component declares is skipped, and a boundary whose ids are all missing draws no frame at all — a trust boundary can leave the picture while the specification still claims it.
+
+## Accessibility
+
+- The <svg> is role="img" with a name, so a screen reader announces a picture instead of walking two hundred <text> nodes in drawing order.
+- The diagram’s content is published beside it as an ordinary list — every node with its kind, every relationship as "A → B: over HTTPS". That list is where the meaning lives for anyone not looking at the picture.
+- Passing onSelectNode turns that list into real buttons, which is the keyboard’s only route to a selection: the plates inside the picture are presentational by construction.
+
+## ArchitectureFigure
+
+A component map: services, datastores, boundaries, and what talks to what. Takes the same JSON an archify `architecture` specification carries — `components`, `boundaries`, `connections` — and draws it in this system's own terms: paper plates on a hairline, one reversed plate for the component the diagram is about, and seven drawn sigils where archify uses seven hues. IT RENDERS ON A SERVER because every position is already in the specification. A component gives a `row` and a `col` into a grid whose cell size is either declared or defaulted, or it gives an absolute `pos` — nothing here is solved for, relaxed, or measured. So the markup is a pure function of the input, it is identical on the server and in the browser, and there is no layout shift on hydration because there is no layout to do. A component that declares NEITHER flows: it takes the next free cell in declaration order, wrapping at `layout.cols`. That is still arithmetic on numbers the specification carries rather than a solver — and the alternative was every unplaced component defaulting to row 0, column 0 and stacking into one plate. BOUNDARIES ARE DRAWN FIRST, AND DRAWN DIFFERENTLY. A `region` is where something RUNS — a VPC, a zone, a cluster — and is a solid frame. A `security-group` is what may REACH it, and is dashed. That is not decoration: an infrastructure diagram is very often read for exactly one of those two questions, and a reader should be able to tell which line answers which without reading either label.
+
+### Props
+
+- `spec` (required) — `ArchitectureSpec`.
+
+Also accepts: `FigureChrome`.
+
+## Examples
+
+```tsx
+<ArchitectureFigure
+  spec={{
+    meta: { title: 'Request path' },
+    components: [
+      { id: 'cdn', type: 'cloud', label: 'CloudFront', row: 0, col: 0 },
+      { id: 'api', type: 'backend', label: 'FastAPI', sublabel: 'ECS', row: 0, col: 1 },
+      { id: 'db', type: 'database', label: 'Postgres', row: 0, col: 2 },
+    ],
+    connections: [
+      { from: 'cdn', to: 'api', label: 'HTTPS' },
+      { from: 'api', to: 'db', label: 'SQL' },
+    ],
+  }}
+/>
+```

package/dist/agent/AreaChart.md

@@ -0,0 +1,94 @@
+# AreaChart
+
+A filled series over a continuous axis, where the area means something.
+
+- Kind: component
+- Group: Charts
+- Import: `import { AreaChart } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/area-chart/
+- Related: line-chart, bar-chart, composed-chart
+
+## When to reach for it
+
+Reading one magnitude over time. Comparing several series against each other is a LineChart — four translucent fills stacked on each other answer neither question.
+
+## Anatomy
+
+- **Figure frame** (required) — The <figure> ChartFigure draws, named through aria-labelledby rather than left to the figcaption, because deriving a name from a <figcaption> resolves in only some screen readers. The caption holds title and description together and is sr-only until showTitle is set, so a caveat written into description is announced and never printed.
+- **Plot** (required) — ChartContainer: a 16:9 box floored at 13rem and capped at 26rem, and the one place Recharts’ hard-coded #ccc axis and grid strokes are re-pointed at --chart-grid and --chart-axis.
+- **Areas** (required) — <AreaChart.Area>, one per series. Each generates its own id and scopes its gradient, its texture pattern and its reveal mask under it, so six variants share a plot without one overwriting another’s definitions.
+- **Brush strip** — <AreaChart.Brush>, rendered in the container’s footer rather than inside the SVG. Both handles are role="slider" with aria-valuetext naming the row they sit on, so the window is reachable by arrow key.
+- **Toolbar** — <AreaChart.Toolbar>, a role="group" row of at most five 44px icon buttons above the plot. Composing it also switches the plot’s own wheel, drag and keyboard zoom on, and the two drive one window rather than two.
+- **Hidden data table** — An sr-only <table> built from the FULL data rather than the brushed window, so a reader on the table is never shown less than the CSV export holds. hideDataTable removes it, and zero rows render nothing.
+
+## Best practices
+
+### Do
+
+- Stack only quantities that genuinely add up. Under stackType="stacked" a band’s HEIGHT is its own value but its POSITION is the sum of everything under it, so stacking four independent rates draws a running total nobody measured.
+- Reach for stackType="expanded" when the reading is share rather than volume: it sets Recharts’ expand offset and <AreaChart.YAxis> swaps in percentTick on its own, so the axis reads 0% to 100% without a formatter at the call site. A tickFormatter of your own still wins — the axis defers to it rather than dropping it, which it used to do without a word.
+- Vary variant before the ramp on a two-area chart. The six fills are the primary encoding in the monochrome default, and under forced colours every --series-* token resolves to CanvasText — at which point the texture is the only thing left separating two areas.
+- Pass xDataKey. It is the rowKey of the hidden table, and without it the table renders no row-header column at all: a screen reader gets a column of numbers with no month beside them.
+
+### Don’t
+
+- Four translucent fills over each other is this form’s failure mode — the third area is read through two layers of --chart-fill and its own height stops being recoverable. Several series compared against each other is a LineChart, where nothing occludes anything.
+- connectNulls defaults to false for a reason: turned on, a gap in the data is drawn as a straight segment indistinguishable from a measured flat period. Set it only where the gap is a rendering artefact rather than a missing observation.
+- A single row draws nothing. One point has no segment to fill, dot is false unless <AreaChart.Dot> is composed, and the empty state does not fire because there IS a row — so the axes render over a blank plot.
+
+## Accessibility
+
+- title is required and becomes the figure’s accessible name, printed or not.
+- The rows are rendered again as a visually hidden table, so the numbers are reachable rather than only drawn. hideDataTable opts out when the page already prints them.
+- Six fill variants exist because in the monochrome default TEXTURE is the primary carrier of identity and the grey ramp is the second — which is also what keeps two series apart in greyscale print and under forced colours.
+- The intro reveal is a per-frame SVG mask and is dropped entirely under prefers-reduced-motion, as is the crawling dash.
+
+## Keyboard
+
+- Tab — Reaches the plot, which Recharts’ accessibility layer makes navigable.
+- ← / → — Moves the cursor between points, announcing each.
+
+## AreaChart
+
+A filled series over a category axis — the shape for a magnitude that is continuous, where the area under the line means something. Composed rather than configured: axes, grid, tooltip, legend and the areas themselves are children, so a chart renders exactly the parts it asked for and nothing is switched on by a prop nobody can see. Reach for `<LineChart>` instead when the reader is comparing several series against each other rather than reading one total, and for `<BarChart>` when the categories are discrete.
+
+### Props
+
+- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`. Series keys → their label and paint. Declaration order is ramp order.
+- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
+- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
+- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `chartProps` — `ComponentProps<typeof RechartsAreaChart>`. Escape hatch onto the raw Recharts chart element.
+- `curveType` — `ChartCurveType` default `'linear'`. The curve every `<AreaChart.Area>` inherits.
+- `animationType` — `ChartRevealType` default `'forward'`. The intro wipe every `<AreaChart.Area>` inherits.
+- `stackType` — `AreaStackType` default `'default'`. How several marks combine: side by side, stacked, or normalised to 100%.
+- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
+- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
+- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
+- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
+- `loadingPoints` — `number`. How many points the skeleton draws.
+- `xDataKey` — `keyof TData & string`. The row field on the category axis. Needed by the brush and by the table view.
+- `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. Rendered instead of the plot whenever `data` is empty and the chart is not loading — the state a real dashboard reaches within a week, and the one an empty pair of axes is indistinguishable from a failed load. `false` keeps the axes, for a chart whose emptiness is itself the reading.
+
+## Types
+
+- `ChartCurveType` = `ComponentProps<typeof RechartsArea>['type']`
+- `AreaVariant` = `'gradient' | 'gradient-reverse' | 'solid' | 'dotted' | 'lines' | 'hatched'`
+- `AreaStrokeVariant` = `'solid' | 'dashed' | 'animated-dashed'`
+- `AreaStackType` = `'default' | 'stacked' | 'expanded'`
+
+## Examples
+
+```tsx
+<AreaChart title="Visitors per month" config={config} data={data} xDataKey="month">
+  <AreaChart.Grid />
+  <AreaChart.XAxis dataKey="month" />
+  <AreaChart.Tooltip />
+  <AreaChart.Area dataKey="desktop" variant="gradient" />
+</AreaChart>
+```

package/dist/agent/Article.md

@@ -0,0 +1,65 @@
+# Article
+
+The long-form reading surface — everything a Markdown pipeline emits, in this system’s type.
+
+- Kind: component
+- Group: Surfaces
+- Import: `import { Article } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/article/
+- Related: diagram, card
+
+## When to reach for it
+
+A post, a changelog entry, a document. Not for interface copy: a paragraph inside a card is a paragraph, and this is a whole reading column with its own rhythm.
+
+## Anatomy
+
+- **The column** (required) — Whatever as names — article, section or div — tagged data-folio-article, which is what every rule in article.css is scoped to. A 46rem measure and no inline margins of its own, so it sits wherever its parent puts it.
+- **Blocks** (required) — The DIRECT children, and where the rhythm lives: air above every block, more above a heading, none on the first. A block one level deeper is outside that rule and outside its spacing.
+- **Rendered HTML** — html, written with dangerouslySetInnerHTML. Present it and children are not rendered at all — the trust boundary is the pipeline that produced the string, because there is nothing here that will catch a script tag on the way through.
+- **Lead** — p.lead — the standfirst, at --fs-item in full --ink. Marked by the author or the pipeline, never inferred: the stylesheet does not promote whatever happened to come first.
+- **Wide blocks** — figure, table and .folio-wide are the three things allowed out of the measure, because a six-column table and an image with a subject in it are both unreadable at 46rem.
+
+## Best practices
+
+### Do
+
+- Centre it yourself. It sets a measure, not a layout — with no auto margins it sits against the start edge of a wide page until a parent centres it.
+- Keep every block a direct child: the rhythm is a child combinator, so a <div> wrapped around a run of paragraphs — even a display:contents one, which removes the box but not the node — costs all of them their spacing.
+- Have the pipeline wrap a wide table in .folio-table-scroll. A table is allowed out of the measure and has nothing of its own to scroll inside, so eight columns push the whole page sideways instead.
+- Sanitise before the string arrives, and mark the boundary where you do it: html is set as innerHTML, so a CMS field that reaches this prop unsanitised is stored XSS with a reading measure.
+
+### Don’t
+
+- Do not pass html and children together — html wins and the children are dropped. It says so in development now, but html="" is still html, so a pipeline that rendered nothing takes the children down with it. A post that mixes prose with components is two Articles in order, not one holding both.
+- Do not count on a nested component’s utilities holding inside one: article.css is imported unlayered and beats Tailwind’s @layer utilities whatever the specificity, so any property these rules also set is overridden. A component that must keep one needs an inline style, or a tag the stylesheet does not reach.
+- Do not nest six heading levels: h5 and h6 are set as mono uppercase 11px eyebrows rather than as smaller headings, so a document loses its type hierarchy at exactly the depth that needed one.
+
+## Accessibility
+
+- An <article> by default, so the piece is a landmark a reader can jump to.
+- Every heading carries scroll-margin, so an anchored link does not park the heading under a fixed masthead.
+- The styles are imported unlayered, so inside an article they beat a component’s layered utilities — which is what lets a Markdown paragraph give its margin up to the article’s rhythm.
+
+## Article
+
+The long-form reading surface. Everything a Markdown pipeline can emit — headings, prose, lists, tables, quotations, code, figures, footnotes, MathML — set in this system's type, colour and rules. The styles live in `article.css` rather than in a class string, because the input is not JSX: there is no component to hang a class on when the markup arrived as a string, so the contract has to be the element names themselves. That file is published on its own as `@misoto22/folio/article.css`, so a site with its own Markdown pipeline can take the reading surface without taking the components — which is the case this exists for. Three sites hand-rolling a prose stylesheet is three prose stylesheets that drift. Composable either way: pass `html` for a rendered string, or children for real elements — one or the other, never both. `html` wins when both arrive, and says so in development: `html=""` is still `html`, which made losing a page of children a thing that could happen without a word. A post that mixes the two — prose with a `Diagram` dropped into the middle — renders its blocks in order and gives each one an `Article`. Inside one, these rules BEAT a component's utilities: `article.css` is imported unlayered while Tailwind's utilities sit in `@layer utilities`, and an unlayered rule wins over a layered one whatever either one's specificity is. That is the mechanism rather than an accident — it is what lets a `Markdown` paragraph, a `Text` carrying `m-0`, give its margin up to the article's rhythm. A component that has to hold a property inside an article needs an inline style, not a class.
+
+### Props
+
+- `html` — `string`. Rendered HTML from a Markdown or MDX pipeline. Trusted markup only. This sets `dangerouslySetInnerHTML`, so it must come from content you control — a repository's own posts, a CMS you author — and never from a reader. Untrusted Markdown has to be sanitised before it reaches here; that is a pipeline decision, not a component one, and a sanitiser bolted on inside a styling primitive would be the wrong place to make it and the easiest place to get it wrong.
+- `as` — `'article' | 'div' | 'section'`. The element to render. `article` by default; pass `div` for a fragment.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Examples
+
+```tsx
+<Article html={renderedMarkdown} />
+<Article>
+  <h1>The White Reset</h1>
+  <p className="lead">A monochrome system for software and writing.</p>
+  <Diagram spec={spec} />
+</Article>
+```

package/dist/agent/AspectRatio.md

@@ -0,0 +1,58 @@
+# AspectRatio
+
+A box that keeps its shape whatever is inside it.
+
+- Kind: component
+- Group: Surfaces
+- Import: `import { AspectRatio } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/aspect-ratio/
+- Related: skeleton, card
+
+## When to reach for it
+
+The height has to be known before the content loads — a media grid that would otherwise reflow every time an image arrives.
+
+## Anatomy
+
+- **Box** (required) — A relative, full-width <div> carrying aspect-ratio as an inline style. A style and not a class because Tailwind can only generate what it reads verbatim in the source, and this value arrives at runtime.
+- **Children** (required) — Every DIRECT child, taken out of flow and stretched to fill the box. That is what guarantees the ratio holds: nothing inside can contribute a height, so content with no intrinsic size of its own still gets the whole box.
+- **Crop** — object-cover on a direct <img> or <video>, so media fills the box rather than being letterboxed inside it. Content that must not be cropped sets object-contain on itself.
+
+## Best practices
+
+### Do
+
+- Reach for it wherever a reflow would otherwise happen when an image lands. That reflow is the layout shift a Core Web Vitals score measures, and reserving the box is the whole fix.
+- Set object-contain on the child when the whole picture matters — a logo, a diagram, a screenshot. The default crops, which is right for a photograph and wrong for anything with an edge that means something.
+- Give it a width. It is w-full, so inside a container with no width of its own it has no height either, and a box with a ratio and no size is a box that is not there.
+
+### Don’t
+
+- Do not fall back to the padding-top percentage trick beside it. That percentage resolves against the WIDTH, which is why it works at all and also why it breaks as a flex child and eats the element’s own padding.
+- Do not put text in it and expect the box to grow. Every child is absolutely positioned, so a paragraph longer than the box is clipped by overflow-hidden rather than pushing it open.
+
+## Accessibility
+
+- A plain box with no role: it constrains geometry and says nothing, so an <img> inside keeps its own alt and nothing is added to the accessible tree.
+- Reserving the height before the content arrives is what stops the content under it moving out from under a pointer or a reader mid-tap.
+
+## AspectRatio
+
+A box that keeps its shape whatever is inside it. The one layout primitive that is genuinely hard to hand-roll. The `padding- top: 56.25%` trick everyone reaches for is a percentage of the WIDTH, which is why it works at all and also why it silently breaks the moment the box is a flex or grid child — and it takes the element's own padding with it. The modern `aspect-ratio` property does the same job in one line, and only holds if nothing inside forces a height, which is what the absolute positioning below guarantees. So: the box declares the ratio, and every direct child is stretched to fill it and taken out of flow. That means a child with no intrinsic size at all — an empty `<div>`, a map that measures its container, a skeleton — still gets the full box, and an `<img>` or `<video>` is cropped to cover it rather than letterboxed. Content that must not be cropped should set `object-contain` on itself. Reach for this when the height must be known before the content loads: a media grid that would otherwise reflow every time an image arrives is the usual case, and that reflow is the layout shift a Core Web Vitals score is measuring.
+
+### Props
+
+- `ratio` — `number | string` default `16 / 9`. Width over height. A number (`16 / 9`) or the CSS form (`'16 / 9'`). It is a style rather than a class because Tailwind can only generate what it can read verbatim in the source, and this value arrives at runtime.
+- `children` — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLDivElement>`.
+
+## Examples
+
+```tsx
+<AspectRatio ratio={16 / 9}><img src={cover} alt="" /></AspectRatio>
+<AspectRatio ratio="1 / 1" className="rounded-(--radius) border border-(--rule-2)">
+  <Skeleton />
+</AspectRatio>
+```

package/dist/agent/Avatar.md

@@ -0,0 +1,53 @@
+# Avatar
+
+A person, as a circle, with initials until the image lands.
+
+- Kind: component
+- Group: Display
+- Import: `import { Avatar } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/avatar/
+
+## Anatomy
+
+- **Circle** (required) — The Radix root: a --rule hairline over --stone, overflow hidden, and one of three fixed squares — 28px, 36px or 48px. It carries role="img" and alt as its own name, because it is the one element in here that is always rendered.
+- **Image** — Rendered only when src is given, object-cover so a portrait crops to the circle instead of distorting. Its own alt is empty on purpose — the circle around it is what names the person, and a second name here is the same person read twice.
+- **Initials** — The Radix fallback: mono, uppercase, --ink-3-aa, and aria-hidden. Radix shows it while the image is loading and once it has failed, which is why it does not flash on every render the way a hand-rolled onError swap does.
+
+## Best practices
+
+### Do
+
+- Write alt for the person, not for the row: the circle carries it whether or not a photograph ever arrives, so a list where photographs are optional announces every person rather than every second one.
+- Pass initials that hold up on their own: fallback is required because the image is the optional half, and most rows of a real list render as this element rather than as a photograph.
+- Let Radix own the swap rather than reaching for onError — it flips to the fallback only once the image has actually failed, which is what keeps the initials from appearing for a frame before the cache answers.
+
+### Don’t
+
+- The avatar is not the control. sm is 28px and md is 36px, both under the 44px pointer-target floor (WCAG 2.5.8), and the root is a <span> nothing has made focusable — an account menu made by hanging onClick on it is unreachable and undersized at once.
+- children is deliberately omitted from the props: the image and the fallback are the only two things that go in the circle, and the root is overflow-hidden, so a presence dot placed inside it is clipped by the very border that makes it round.
+
+## Accessibility
+
+- alt names the circle itself, as role="img", so an avatar with no photograph still says who it is.
+- An empty alt is correct when the name is already printed beside it: the circle then takes no role at all rather than an unnamed one, and leaves the tree entirely.
+- The initials are aria-hidden — read aloud beside a name the root already gives, they are noise.
+
+## Avatar
+
+A person, as a circle. Wraps Radix so the fallback appears only after the image has actually failed or is still loading — a hand-rolled `onError` swap flashes the initials on every render before the cache answers. The ROOT carries the accessible name, not the image. `alt` on the image reaches the DOM only when `src` does, and the initials are aria-hidden, so an avatar with no photograph announced nothing at all however carefully `alt` was written — and a user list where photographs are optional is full of them.
+
+### Props
+
+- `src` — `string`.
+- `alt` (required) — `string`. Describes the person, not the picture. It names the circle itself rather than the image inside it, because the image is the optional half and most rows of a real list render as initials. Empty string is correct and deliberate when the name is already printed beside the avatar: the circle then leaves the accessibility tree entirely, rather than repeating a name a screen reader has just read.
+- `fallback` (required) — `string`. Shown while the image loads and if it never does. Usually initials.
+- `size` — `'sm' | 'md' | 'lg'` default `'md'`.
+
+Also accepts: `Omit<ComponentProps<typeof AvatarPrimitive.Root>, 'children'>`.
+
+## Examples
+
+```tsx
+<Avatar src={user.photo} alt={user.name} fallback="HC" />
+```