@misoto22/folio 0.0.0 → 0.16.0

package/dist/agent/Heading.md

@@ -0,0 +1,65 @@
+# Heading
+
+A heading whose element and whose size are two decisions.
+
+- Kind: component
+- Group: Display
+- Import: `import { Heading } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/heading/
+- Related: text, article, markdown
+
+## When to reach for it
+
+Any heading. level follows the document outline; size follows the design, and defaults from level.
+
+## Anatomy
+
+- **Element** (required) — level, 1 to 6, rendered as the matching <h1>–<h6>. This is the document outline — what a screen reader navigates by — so it follows the section the heading opens, never the size it wants to be.
+- **Step** (required) — size, one of title, lead, heading, sub, item and label. Defaults from level through the system ladder, so writing only level is correct.
+- **Anchor offset** (required) — scroll-margin-top: var(--scroll-offset), carried by every heading, so one given an id and linked from a table of contents comes to rest below the masthead instead of under it.
+
+## Best practices
+
+### Do
+
+- Write level alone unless the outline and the design genuinely disagree. The default ladder is 1→title, 2→heading, 3→sub, 4→item, 5 and 6→label — the same map article.css applies to rendered Markdown, which is what makes a post and a component page read as one publication.
+- Notice that the default ladder SKIPS lead between levels 1 and 2, and skip a step yourself when you set size by hand: --fs-lead over --fs-heading is a ratio of 1.14 and reads as a rendering accident, where --fs-title over --fs-heading is 1.86 and reads as a hierarchy.
+- Give a heading an id when anything links to it. The component already carries the scroll offset the anchor needs; nothing else on the page does.
+
+### Don’t
+
+- Do not raise level to get a bigger heading. Two <h1>s on a page make its outline unnavigable, and size is one prop away.
+- Do not reach past size="title". The ladder ends there because a page has exactly one thing larger than its own records; a bigger heading is className territory and it is the moment the page stopped being in the system.
+- size="label" is the mono kicker at 11px and --ink-3-aa, not a small serif heading — it is what levels 5 and 6 should look like, and setting it on an <h2> makes the section title read as metadata.
+
+## Accessibility
+
+- level renders the real heading element, so the outline is navigable rather than merely visible.
+- The two decisions are separate props, which is what lets a semantically-correct h3 look like a page title without bending the outline.
+- Carries scroll-margin-top so an anchored heading is not hidden under a fixed masthead (WCAG 2.4.7 in practice).
+
+## Heading
+
+A heading, with its element and its size decided separately. Every heading component that takes one number gets this wrong in one of two directions: either the outline is bent to reach a size (an `<h1>` in the middle of a page because the design wanted big type), or the size is bent to keep the outline (a section title set at 20px because it is the fourth level down). Both are one prop away from being right, so there are two. `level` is the document. `size` is the page. The default binds them through the system's ladder, so writing only `level` is correct — and the moment they come apart, the call site says so. Set in the editorial serif at weight 400, like every heading in the system. It also carries `scroll-margin-top`, so a heading given an `id` and linked from a table of contents comes to rest below the masthead rather than under it.
+
+### Props
+
+- `children` — `ReactNode`.
+- `level` (required) — `HeadingLevel`. The element: `1` renders `<h1>`, `6` renders `<h6>`. This is the document outline and nothing else — it is what a screen reader navigates by, so it follows the section the heading opens, never the size it wants to be. A heading two levels down inside an `<h2>` section is an `<h3>` even when the design calls for something enormous.
+- `size` — `HeadingSize`. The size, when the outline and the design genuinely disagree. Defaults from `level` through the ladder above, which is the answer nearly always. Reach for this when a semantically-correct `h3` opens a page and has to look like one — not to squeeze a fourth step between two that are already only 14% apart.
+
+Also accepts: `HTMLAttributes<HTMLHeadingElement>`.
+
+## Types
+
+- `HeadingLevel` = `1 | 2 | 3 | 4 | 5 | 6`
+- `HeadingSize` = `'title' | 'lead' | 'heading' | 'sub' | 'item' | 'label'`
+
+## Examples
+
+```tsx
+<Heading level={1}>The White Reset</Heading>
+// Third level in the outline, page-title sized.
+<Heading level={3} size="title">Colour</Heading>
+```

package/dist/agent/Heatmap.md

@@ -0,0 +1,78 @@
+# Heatmap
+
+A grid of values read by weight.
+
+- Kind: component
+- Group: Data
+- Import: `import { Heatmap } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/heatmap/
+- Related: table, scatter-chart
+
+## When to reach for it
+
+A calendar of activity, a confusion matrix, an hour-by-weekday load. The one form a monochrome system renders better than a chromatic one.
+
+## Anatomy
+
+- **Figure caption** (required) — title in a figcaption, hidden from sight unless showTitle prints it above the grid with description under it. The same string is also the table’s own sr-only caption, so the grid is named on the way in and again from the table.
+- **Column headers** (required) — One th scope="col" per entry in columns, in the order given, preceded by an sr-only corner cell reading “Row” so the header line has something standing over the row labels.
+- **Row headers** (required) — One th scope="row" per entry in rows — end-aligned mono at --chart-axis, so every cell can be traced back to the pair of labels that names it.
+- **Cell** (required) — A td whose background is a color-mix of --series-1 into --chart-surface at the value’s position in the domain. Continuous rather than stepped, because banding a ramp invents boundaries the data does not have, and 2px of border-spacing between cells is what makes two neighbouring weights countable.
+- **Missing cell** — What a null draws — and what a row and column pair absent from cells draws too: a dashed --rule outline over the page, announcing “no data” instead of a number.
+- **Printed value** — formatValue inside the cell. Visible with showValues, otherwise sr-only and un-hidden again under forced colours, where the wash that WAS the encoding has been remapped away.
+
+## Best practices
+
+### Do
+
+- Switch scale to diverging the moment the values cross zero. sequential ramps on POSITION in the domain, so on a grid of changes the deepest fall is the palest cell and the biggest rise the darkest; diverging ramps on distance from the midpoint instead, which is the read a delta actually wants.
+- Pin domain when one cell is an order of magnitude clear of the rest. The derived domain runs from zero — or the lowest value, when that is negative — to the highest, so a single 10,000 among readings of 5 to 40 puts every other cell inside the first half percent of the ramp, and forty distinct numbers render as one dark square on a blank grid.
+- Spell a cell’s row and column exactly as they appear in rows and columns: cells are looked up by that pair, so an unmatched entry draws nothing at all. It no longer counts toward the derived domain either — a typo used to stretch the ramp with a value that appeared nowhere on the grid, pushing every drawn cell into the first fraction of it.
+- Take the contrast trade knowingly when showValues goes on. The wash is capped at 35 percent of the ramp so one ink colour clears 4.5:1 on every cell — the ORDER of the cells survives untouched, the spread between them narrows, and the printed numbers become the thing carrying the detail.
+
+### Don’t
+
+- Do not let a pipeline fill gaps with zero before the grid sees them. A null is drawn as a dashed outline and announced as no data, and a zero is drawn as the palest cell on the ramp — so substituting one for the other turns an outage into a quiet hour, and nothing on the grid says which it was.
+- Do not expect a reader to recover a figure from the wash. There is no legend and no step: weight orders the cells and never states one. The forced-colours fallback un-hides the numbers because the background has stopped existing there, which is a rescue for a remapped ground rather than a substitute for showValues on a grid whose exact figures matter.
+
+## Accessibility
+
+- A real <table>, not an SVG: the structure a screen reader walks is the structure the eye reads, and every cell announces its own row, column and value.
+- Lightness is the only channel that is unambiguously ordered, which is why the standing advice everywhere else is “one hue, light to dark”. Here there is no hue left to get wrong.
+- A null is drawn as a dashed outline, never as the palest cell — a missing reading is not a zero.
+- Pin domain whenever two grids are compared: on independent domains they look alike and mean different things, which is the one failure a shared legend cannot fix.
+
+## Heatmap
+
+A grid of values read by weight — a calendar of activity, a confusion matrix, an hour-by-weekday load. The one form in the set that a monochrome system renders BETTER than a chromatic one. A heatmap needs a scale whose order the eye can read without consulting a legend, and lightness is the only channel that is unambiguously ordered — which is why "one hue, light to dark" is the standing advice everywhere else, and why the rainbow heatmap is a perennial mistake. Here there is no hue left to get wrong. It is built as a real `<table>` rather than as an SVG, so the structure a screen reader walks is the structure the eye reads: a header row, a header column, and a cell that announces its own value. Nothing else in the package can say that, and nothing else needs to — which is also why this one takes no rendering engine at all.
+
+### Props
+
+- `title` (required) — `string`. What the grid shows. Required, and it names the table.
+- `showTitle` — `boolean` default `false`. Prints the title above the grid instead of hiding it from sight.
+- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
+- `columns` (required) — `string[]`. Column headers, in the order they should appear.
+- `rows` (required) — `string[]`. Row headers, in the order they should appear.
+- `cells` (required) — `HeatmapCell[]`.
+- `scale` — `HeatmapScale` default `'sequential'`.
+- `domain` — `[number, number]`. The domain, as `[min, max]`. Derived from the data when omitted. Pin it whenever two grids are meant to be compared: two heatmaps on independent domains look alike and mean different things, which is the one failure a shared legend cannot fix.
+- `formatValue` — `(value: number, cell: HeatmapCell) => string` default `(value) => value.toLocaleString()`. Formats a value for the cell's announcement and its printed label. The cell is handed over as well, so a grid whose columns are not self-describing can name the reading rather than only the number. A calendar is the case that needs it: two days with the same count are two different readings, and the row and column headers a cell is announced with — "Mon" and a month name over a block of five weeks — do not say which day it was.
+- `showValues` — `boolean` default `false`. Prints the number inside each cell. Only legible on a coarse grid.
+- `className` — `string`.
+- `empty` — `ChartEmptyProps`. What the grid shows when it has no rows or no columns to draw. A heatmap with no headers renders as a caption over nothing, which reads as a grid that failed to load rather than as one with nothing in it.
+
+## Types
+
+- `HeatmapScale` = `'sequential' | 'diverging'`
+
+## Examples
+
+```tsx
+<Heatmap
+  title="Commits by weekday and hour"
+  columns={hours}
+  rows={weekdays}
+  cells={cells}
+/>
+```

package/dist/agent/Histogram.md

@@ -0,0 +1,88 @@
+# Histogram
+
+The shape of one distribution.
+
+- Kind: component
+- Group: Charts
+- Import: `import { Histogram } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/histogram/
+- Related: box-plot, bar-chart
+
+## When to reach for it
+
+A single distribution has to be understood — two clusters, a hard floor, a pile-up at a timeout. Several distributions side by side want a BoxPlot.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state when no bucket survives binning — which is what zero finite observations produces.
+- **Bars** (required) — <Histogram.Bars>, each drawn from its bucket’s own two edges rather than placed in an equal category slot, which is what lets an uneven bucket be as wide as it really is. radius is 0 by default, unlike BarChart’s: a rounded corner draws a gap between two buckets that touch.
+- **Measured axis** (required) — <Histogram.XAxis>, numeric, running from the first bucket’s lower edge to the last one’s upper edge.
+- **Count axis** — <Histogram.YAxis>. Under mode="frequency" it is a count; under mode="density" it is count over n times width, and the bars then enclose an area of one.
+- **Binning rule** — Not a mark on screen and the most consequential part of the figure: bins takes a bucket count or the explicit edges, and the default is Freedman-Diaconis capped at 200 buckets, falling back to Sturges when the interquartile range is zero. Explicit edges are also a RANGE — an observation outside the first and last has no bucket, and is counted into the tooltip’s share and into a Below or Above row of the table rather than dropped.
+- **Hidden data table** — The sr-only table prints each bucket’s two edges as its row header and its count beside them — the only exact reading a binned chart can offer, since every bar stands for a range rather than for a value. Observations outside explicit edges get their own Below and Above rows, because they have no bar anywhere.
+
+## Best practices
+
+### Do
+
+- Name the binning rule on the page. The same numbers cut into eight buckets and into eighty are two different pictures, and a gap between two humps can be created or erased by moving one edge — so look at more than one width before believing a feature.
+- Set mode="density" whenever the buckets are uneven. Under frequency a bucket twice as wide stands twice as tall at the same underlying rate, which is the trap pre-counted buckets from a metrics backend walk straight into.
+- Give values or data, never both. data wins when both arrive, so the values array is then binned by nothing and drawn by nothing, with no warning anywhere.
+
+### Don’t
+
+- Do not read the tooltip’s share as a share of the bars. It is a share of the SAMPLE, so a set of buckets summing to 96% is telling you the other 4% fell outside your own edges — which is the one reading a share taken over the drawn buckets could never give, because it always sums to 100.
+- Do not use it to compare several distributions. Two histograms overlaid occlude each other and six side by side do not fit; that is a BoxPlot, which spends a tenth of the ink per distribution.
+- Do not assume the automatic rule kept the resolution you asked for. Freedman-Diaconis divides by the interquartile range, so a tight middle with a long tail asks for tens of thousands of sub-pixel bars — the 200-bucket cap turns that into a coarse histogram rather than a hung tab, and a coarse histogram is a different picture.
+- Do not read a single-value distribution as a shape. Every observation on one number still draws: the edges become that value plus and minus a half, and the result is one honest bar that is not a distribution.
+
+## Accessibility
+
+- The shape is a property of the bin width, not only of the data: the same numbers cut into eight buckets and into eighty are two different pictures. The rule that drew it — Freedman–Diaconis by default — is named on the page.
+- The x axis is numeric and every bar is drawn from its own two edges, so an uneven bucket is as wide as it really is rather than flattened into an equal slot.
+- mode="density" corrects the trap uneven buckets create: under frequency a bucket twice as wide stands twice as tall at the same underlying rate.
+- The hidden data table prints each bucket’s two edges and its count, which is the only exact reading a binned chart can offer.
+
+## Histogram
+
+The shape of one distribution — where the mass sits, how it leans, whether there is more than one hump in it. The form that answers what a `<BoxPlot>` structurally cannot: two clusters, a hard floor, a pile-up at a timeout value. Reach for the box plot when several distributions have to be compared side by side, and for this one when a single distribution has to be understood. **A histogram's shape is a property of its bin width, not only of its data.** The same numbers cut into eight buckets and into eighty are two different pictures, and a gap between two humps can be created or erased by moving a bin edge. That is not a defect to be fixed, it is what binning IS, and the defence is to say which rule drew the picture — the default here is Freedman–Diaconis — and to look at more than one width before believing a feature. Uneven buckets add a second trap: under `frequency` a bucket twice as wide stands twice as tall at the same underlying rate, which is what `mode="density"` exists to correct. Recharts earns its place here for the axes, the grid and the tooltip, but not for the bars: a bar chart's bars are positioned by CATEGORY and a histogram's are positioned and SIZED by a continuous measurement. So the x axis is numeric and each bar is drawn from its own two edges — which is what lets an uneven bucket be as wide as it really is instead of being flattened into an equal slot beside its neighbours.
+
+### Props
+
+- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a histogram has one distribution and as many bars as it has buckets.
+- `values` — `number[]`. The raw observations, in any order. Binned for you by `bins`. Give this OR `data`, not both — `data` wins if both arrive.
+- `data` — `HistogramBin[]`. Buckets that were counted somewhere else — by a database, by a sketch, by a metrics backend that only ever ships histograms. Uneven bucket widths are drawn at their real widths, which is the whole reason this takes edges rather than labels. Set `mode="density"` when they are uneven, or the wide buckets will read as tall ones.
+- `bins` — `number | number[]`. How to cut `values` up: a number of equal-width bins, or the explicit edges. Defaults to Freedman–Diaconis (`2 × IQR × n^(-1/3)`), falling back to Sturges when the interquartile range is zero. Explicit edges are a RANGE as well as a set of buckets: an observation outside the first and last edge has no bucket to fall in. It is counted anyway — into the tooltip's share-of-total, and into a "Below" or "Above" row in the table — so a tail your edges cut off is still somewhere a reader can find it.
+- `mode` — `HistogramMode` default `'frequency'`. What the bar heights mean. `frequency` is the count in each bucket and is what a reader assumes. `density` is `count / (n × bin width)`, so the total area is 1 — which is what makes two histograms of different sample sizes comparable, and what makes uneven buckets honest.
+- `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, and `<Histogram.Bars>`.
+- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
+- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
+- `formatValue` — `(value: number) => string` default `defaultTick`. Formats the measured values — bin edges, ticks, the tooltip's heading.
+- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
+- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the axes, for a chart whose emptiness is itself the reading.
+
+## Types
+
+- `HistogramMode` = `'frequency' | 'density'`
+
+## Examples
+
+```tsx
+<Histogram title="Response times" values={samples} bins={20}>
+  <Histogram.Grid />
+  <Histogram.XAxis label="ms" />
+  <Histogram.YAxis />
+  <Histogram.Tooltip />
+  <Histogram.Bars />
+</Histogram>
+// Buckets that arrived already counted, with uneven widths.
+<Histogram title="Payload size" data={buckets} mode="density">
+  <Histogram.XAxis />
+  <Histogram.YAxis />
+  <Histogram.Bars />
+</Histogram>
+```

package/dist/agent/Input.md

@@ -0,0 +1,52 @@
+# Input
+
+A single line of text entry.
+
+- Kind: component
+- Group: Forms
+- Import: `import { Input } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/input/
+- Related: field, textarea
+
+## Anatomy
+
+- **Control box** (required) — The <input>, on the CONTROL_BASE it shares with Textarea and the Select trigger. Its padding is --field-px / --field-py, so a subtree marked data-density="compact" tightens the fields along with the buttons.
+- **Placeholder** — placeholder, in --ink-3-aa inside the box — the same slot the value occupies, which is why it cannot also be the name.
+- **Focus border** — focus:border-(--ink) on the border already there, not an added ring. The box does not gain a pixel on focus, so nothing in the row shifts.
+- **Danger border** — What invalid — or an aria-invalid set by a Field with an error — swaps in. It changes the border colour and nothing else, so the reason has to come from the message below.
+
+## Best practices
+
+### Do
+
+- Spell out type and inputMode. An <Input> with no type is type="text", so an email field that never says so gets a phone keyboard with no @ on it and no browser validation at all.
+- Name the field to the browser with autoComplete: a password field without current-password or new-password is one a manager fills with the wrong value and one no browser offers to save.
+- Reach for readOnly rather than disabled when the value is real but not editable — a disabled input is skipped by Tab AND left out of the submitted form data, so the server hears nothing about a field the reader can plainly see.
+
+### Don’t
+
+- readOnly is styled by nothing here: CONTROL_BASE dims on :disabled only, so a read-only input is pixel-identical to an editable one and the first thing a reader learns about it is that typing does nothing.
+- type="number" is for quantities, not for digits. A phone number, a card number or a postcode loses its leading zeros, and a scroll wheel over the focused control changes the value without a keystroke.
+- A Tooltip on a disabled input never opens — disabled:pointer-events-none means the control receives no hover — so the explanation for why it is disabled has to live in the Field’s hint instead.
+
+## Accessibility
+
+- A placeholder is not a label — it disappears the moment anyone types. Pair with Field.
+
+## Input
+
+A single line of text entry. Shares `CONTROL_BASE` with Textarea and Select, so the three cannot drift apart. Pair with `Field` for the label, hint and error — an input with a placeholder and no label is not labelled, because the placeholder disappears the moment anyone types.
+
+### Props
+
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `ref` — `Ref<HTMLInputElement>`.
+
+Also accepts: `InputHTMLAttributes<HTMLInputElement>`.
+
+## Examples
+
+```tsx
+<Field label="Email" htmlFor="email"><Input id="email" type="email" /></Field>
+```

package/dist/agent/Kbd.md

@@ -0,0 +1,48 @@
+# Kbd
+
+A key on a keyboard, set as one.
+
+- Kind: component
+- Group: Display
+- Import: `import { Kbd } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/kbd/
+- Related: badge
+
+## Anatomy
+
+- **Key** (required) — The <kbd>: a --rule-2 hairline on the --radius-sm corner, min-w-[1.6em] so a single character is a cap rather than a sliver, and 0.8em type so the whole cap scales with the copy around it.
+- **Legend** (required) — children, printed verbatim. One key per element — the space between two of them is a real space in the markup, not a separator the component draws.
+
+## Best practices
+
+### Do
+
+- Write one Kbd per key. A whole chord in one box — ⌘K — is a single cap with two glyphs in it, and the min-w-[1.6em] that makes one character square just stretches to hold both.
+- Let it take its size from its surroundings: it is set in em, so the same shortcut printed in a heading and in body copy comes out right in both. Pinning it to px is how one shortcut ended up three sizes on one page.
+- Give a glyph-only key an aria-label — ⌘, ⌥ and ⇧ are read out as their Unicode names or skipped entirely, so a Mac shortcut written in symbols alone is a silent instruction.
+
+### Don’t
+
+- An outline Badge and a Kbd are near enough identical on screen, so the choice between them is entirely about meaning: <kbd> says the reader presses this, and a badge shaped like a key invites a press nothing answers.
+- Nothing here binds anything. The element is typography, so a key printed for a shortcut no handler listens for is documentation of a feature the page does not have.
+
+## Accessibility
+
+- Renders <kbd>, which carries the meaning a styled <span> does not.
+
+## Kbd
+
+A key on a keyboard, set as one. Renders a `<kbd>`, which is the element that means this — a `<span>` styled to look like a key tells a screen reader nothing. Sized in `em` so it tracks whatever type it sits beside rather than fixing itself at one px value, which is how the same shortcut ended up three different sizes across a page. Every dimension here tracked its context except the leading, which was a literal `1.6` — the body's READING leading, on a chip that is never a paragraph. Inside a control it therefore stood proud of the label beside it and pushed the whole box past its own height token: the masthead's search field measured 39px against a 36px `sm`, and it was this keycap doing it. `--control-lh` is the leading a one-line box gets, and this is one.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+
+Also accepts: `HTMLAttributes<HTMLElement>`.
+
+## Examples
+
+```tsx
+Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to open the palette.
+```

package/dist/agent/LifecycleFigure.md

@@ -0,0 +1,50 @@
+# LifecycleFigure
+
+A state machine: what something can be, and what moves it between states.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { LifecycleFigure } from '@misoto22/folio/diagrams'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/lifecycle-figure/
+- Related: workflow-figure, steps
+
+## When to reach for it
+
+The one figure that spends colour, and it spends exactly the two tokens the system reserves for state. Every other distinction is shape, so a greyscale print keeps six of the eight.
+
+## Anatomy
+
+- **Figure shell** (required) — The frame around the picture. What a machine hands it is a transition list with each note folded in after an em dash, so the condition on an arrow — the timeout, the retry count — is in the text copy and not only on the line.
+- **State plate** (required) — One shape per kind: a filled cap for a start, a diamond for a decision, a dashed frame for a wait, a cut corner for an external, and the two washes the system reserves for the terminals. The name is centred, step sits in the leading corner and tag along the bottom edge.
+- **Main rail** — The first lane’s states, sorted by col and joined consecutively at the emphasis weight — one line per neighbouring pair the transitions do not already declare, so a spine written out in full is drawn from the transitions and a spine left implied is drawn anyway. Without it the top row reads as five unconnected boxes, because the spine of a machine is the part nobody writes down.
+- **Transition** — A routed line with its label on a mask and its note in a quieter line beneath. A declared transition between two rail neighbours replaces the implicit one rather than doubling it.
+- **Lane** — A rule with a mono caption above it, drawn only as far as that lane’s own states reach. A lane past the first has its columns shifted along the main rail, which is what keeps a drop out of the spine vertical rather than a dogleg.
+
+## Best practices
+
+### Do
+
+- Keep the first lane for the ordered spine and nothing else. Consecutive states there are joined by the implicit rail even when no transition declares the pair, so a state parked in lane 0 for spacing invents an edge the machine does not have. A state whose lane id nothing declares is kept out of that rail and reported as DIAGRAM_LANE_UNKNOWN instead, because a typo should not be able to add an arrow.
+- Count a secondary lane’s columns from the rail. Every col in a lane past the first is shifted two columns along, so col: 0 in the second lane sits under col: 2 in the first — the convention archify’s lifecycle contract already implies, restated here because it is what makes a drop land on the state it came from.
+- Say whether a failure is recoverable with an edge, not with the type. type: "failure" only paints the plate; a retryable error and a terminal one are identical until a reader follows the arrows out, and the one with none is where the run ended.
+
+### Don’t
+
+- yOffset moves the plate and moves nothing out of its way. The lane’s rule is drawn from what that lane holds, so a negative nudge drags the rule up with the state and a large positive one drops the plate into the band below — a state needing that much room wants a column of its own rather than a push.
+- The figure claims a state can be left only the ways its arrows say. A cancel that can happen from anywhere and is drawn from nowhere reads as impossible, which is a reading the picture makes and the specification never wrote — draw it, or say in the subtitle that it is not drawn.
+
+## Accessibility
+
+- success and failure are the only coloured marks in the package’s diagrams, and each is also a distinct plate shape — colour is never the only carrier.
+- The main rail is drawn between consecutive states in the first lane even when the specification does not list those transitions, because they are the diagram’s spine rather than its exceptions.
+
+## LifecycleFigure
+
+A state machine: what something can BE, and what moves it. The one figure here that spends colour, and it spends exactly the two tokens this system reserves for state: `--success` on a terminal success, `--danger` on a terminal failure. Nothing else in the package is allowed those two, and a lifecycle diagram is the case they were reserved for — the whole point of the picture is which end a run came out of. The other six kinds are carried by shape, so a greyscale print loses the two outcomes' hue and keeps every other distinction: a start is a filled cap, a decision is a diamond, a wait is a dashed frame, an external is a plate with a cut corner. A RECOVERABLE FAILURE IS A FAILURE WITH A WAY BACK. `type: "failure"` says how a state is drawn; a transition OUT of it is what says whether the run is over. A retryable error and a terminal one look identical until you follow the arrows, which is correct — the difference between them is a real edge in the machine, not an adjective on a box.
+
+### Props
+
+- `spec` (required) — `LifecycleSpec`.
+
+Also accepts: `FigureChrome`.

package/dist/agent/LineChart.md

@@ -0,0 +1,85 @@
+# LineChart
+
+Several series compared over a continuous axis.
+
+- Kind: component
+- Group: Charts
+- Import: `import { LineChart } from '@misoto22/folio/charts'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/line-chart/
+- Related: area-chart, composed-chart
+
+## When to reach for it
+
+The reader is comparing series against each other. When the area under one line is the point, fill it — that is an AreaChart.
+
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure> and its sr-only caption. description is announced with the title and printed only under showTitle, which is where a note about a clipped axis belongs.
+- **Lines** (required) — <LineChart.Line>, one per series at a 1.6px stroke. isClickable adds a second, fully transparent 15px line underneath the visible one, because a hairline is not a pointer target.
+- **Point markers** — <LineChart.Dot> and <LineChart.ActiveDot>, both slots and both off by default. The resting dot shares the intro wipe mask so it arrives with its own line; the active dot is never masked, because it exists only on hover, long after the wipe has finished.
+- **Buffer segment** — buffer draws the last leg dashed by measuring the real path with getPointAtLength, so a projection reads as a different kind of fact at any curve type. Fewer than two drawable points and it falls back to a plain curve.
+- **Sonification control** — <LineChart.Sonify>, a real <button> above the plot that plays the visible rows as pitch. Sound never starts from an effect, only from that click, and it reads the brushed window rather than the whole series.
+- **Hidden data table** — The sr-only table of the full data. Recharts’ accessibilityLayer gives a keyboard cursor that announces one point at a time, which is navigation; this is the figures.
+
+## Best practices
+
+### Do
+
+- This is the one chart in the family that survives a truncated value axis. A line encodes by SLOPE, so clipping the domain to the data’s own range is often what makes a two percent move visible at all — state the range in description when you do it.
+- Reach for buffer on a period still open rather than dropping it. A part-month plotted solid reads as a crash; plotted as a dashed final leg it reads as what it is, which is incomplete.
+- Compose <LineChart.Dot> when the series is sparse. With dots off — the default — five points are four segments, and the reader cannot tell a measured value from a bend in the interpolation.
+
+### Don’t
+
+- A single row draws nothing at all: one point has no segment, dot is false unless composed, and the empty state does not fire because a row exists. Guard the one-row case at the call site.
+- Eight lines in one frame is a hairball, and a 1.6px stroke over an eight-step grey ramp makes it a worse one than a chromatic chart would. Past about five series the answer is Facet, not a ninth ramp slot — SERIES_SLOTS is 8 and there is no ninth.
+- connectNulls turns a gap into a straight segment that looks measured. It costs more here than on an area, because the reader reads the slope of that invented segment as a rate.
+
+## Accessibility
+
+- title is required; the rows are also rendered as a visually hidden table.
+- A clickable line gets a 15px transparent line underneath it, because a 1.6px stroke is not a pointer target.
+- buffer draws the last segment dashed by measuring the real path length, so a projection is visibly a different kind of fact at any curve type.
+
+## LineChart
+
+Several series compared over a continuous axis — the shape for "which of these is going where". The difference from `<AreaChart>` is what the reader is asked to do: an area says "read the magnitude under this", a line says "compare these against each other". Filling four overlapping series makes the second question unanswerable, which is why a line chart has no fill variant to offer.
+
+### Props
+
+- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`.
+- `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 RechartsLineChart>`. Escape hatch onto the raw Recharts chart element.
+- `curveType` — `ChartCurveType` default `'linear'`. How the line between two points is interpolated. Every mark inherits it unless it says otherwise.
+- `animationType` — `ChartRevealType` default `'forward'`.
+- `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
+
+- `LineStrokeVariant` = `AreaStrokeVariant`
+
+## Examples
+
+```tsx
+<LineChart title="Visitors per month" config={config} data={data}>
+  <LineChart.Grid />
+  <LineChart.XAxis dataKey="month" />
+  <LineChart.Tooltip />
+  <LineChart.Line dataKey="desktop">
+    <LineChart.Dot variant="border" />
+  </LineChart.Line>
+</LineChart>
+```

package/dist/agent/LinkArrow.md

@@ -0,0 +1,49 @@
+# LinkArrow
+
+The mark on a link that leaves the page.
+
+- Kind: component
+- Group: Display
+- Import: `import { LinkArrow } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/link-arrow/
+
+## Anatomy
+
+- **Marker box** (required) — An aria-hidden inline-block <span> carrying the 0.22em of lead-in, the 0.28em baseline lift and --ink-3-aa. inline-block is load-bearing twice over: it stops an underlined parent drawing its rule through the glyph, and it is what the alignment is measured against.
+- **Glyph** (required) — The ↗ itself at 0.68em, so it tracks the type beside it instead of competing with it. Exported as EXTERNAL_LINK_ARROW, so a surface that is not React uses the same character.
+
+## Best practices
+
+### Do
+
+- Put it inside the <a>, as the last child. Outside it, it is an arrow pointing at a link the pointer misses by 0.22em.
+- Reach for EXTERNAL_LINK_ARROW when the surface is not React — a Markdown pipeline, an OG image, an email — so the mark stays one character rather than three near-identical arrows across a site.
+- Pass a colour through className on a reversed plate: it is set in --ink-3-aa, which is the AA floor against paper and close to invisible on ink.
+
+### Don’t
+
+- The arrow is not the announcement. It is aria-hidden, and target="_blank" is not announced either, so a link that opens a new tab has to say so in its own accessible name — otherwise this glyph is the only warning anyone gets, and only if they can see it.
+- Do not pin it to a px size. 0.68em is what makes one component right in body copy and in a heading; fixed at 11px it is correct in one of them and a speck in the other.
+- Do not put it on every row of an index. It marks a change of destination, so a list where every link leaves the site marks nothing at all and pays 0.22em a row for it.
+
+## Accessibility
+
+- aria-hidden, so it is not read as “north east arrow” in the middle of a sentence.
+- Sized in em, so it tracks whatever type it sits beside instead of competing with it.
+
+## EXTERNAL_LINK_ARROW
+
+The glyph itself, exported so a non-React surface can use the same mark.
+
+## LinkArrow
+
+The mark on a link that leaves the page — outbound, or on to a full index. Call sites used to write a bare `↗` inside the link text, which inherited the link's own size (a 17px arrow beside a 17px word, competing with it) and was read aloud as "north east arrow" because nothing hid it. `inline-block` is load-bearing twice over: it stops an underlined parent drawing its rule through the glyph, and it is what `align` is measured against. Sized in `em`, so it tracks whatever type it sits beside; coloured against paper, so a call site on a reversed plate passes its own colour.
+
+Also accepts: `HTMLAttributes<HTMLSpanElement>`.
+
+## Examples
+
+```tsx
+<a href="https://example.com">Read the paper<LinkArrow /></a>
+```

package/dist/agent/Markdown.md

@@ -0,0 +1,69 @@
+# Markdown
+
+A Markdown string, rendered as this system’s components.
+
+- Kind: component
+- Group: Display
+- Import: `import { Markdown } from '@misoto22/folio'`
+- Version: 0.16.0
+- Docs: https://ui.misoto22.com/components/markdown/
+- Related: article, code-block, heading, text
+
+## When to reach for it
+
+Content nobody on this side wrote — a comment, a README, a model’s answer. Trusted HTML from your own pipeline is an Article.
+
+## Anatomy
+
+- **Fragment** (required) — What it renders. There is no wrapper element, because Article’s rhythm is a direct-child combinator — anything between the two, display: contents included, would cost every paragraph its spacing.
+- **Parser** (required) — parseMarkdown by default: ATX headings, paragraphs, fenced code, blockquotes, nested lists, thematic breaks, and inline emphasis, strong, code, links, images and escapes. Raw HTML is dropped rather than rendered, so this path has no dangerouslySetInnerHTML in it at all.
+- **Nodes** (required) — The system’s own components: Heading, Text, Code, CodeBlock and Separator. That is what makes it styled on its own rather than only inside a reading column. One of them is not server-only — a fenced block renders CodeBlock, which is ‘use client’ with useState, useEffect and two icons, so content containing code brings a client component with it.
+- **Heading ids** (required) — Slugged from each heading’s own text, in any script, deduplicated within the document with -2, -3. Exported as slugify, so a table of contents can arrive at the same ids without reading them back off the DOM.
+
+## Best practices
+
+### Do
+
+- Set headingLevelStart to the level BELOW the heading the content sits under. Markdown is written as a document, so its # is an <h1>; dropped into a page that already has one, that is two first-level headings and an outline nobody can navigate.
+- Put it inside an Article — <Article as="div"> for a comment or an answer, <Article> for a document. Markdown makes the nodes, Article is the column they sit in and the only thing that spaces them, which is also why Markdown renders no element of its own.
+- Pass idPrefix when two documents share a page. Both would otherwise claim #installation, and a fragment link lands on whichever the browser found first.
+- Bring your own parser through parse for tables, footnotes or task lists. The package ships no parser dependency on purpose: markdown-it measures 110.7 kB minified against the 38.9 kB this package had left under its bundle budget.
+
+### Don’t
+
+- Do not hand it HTML. It parses Markdown; a string of tags renders as the text of those tags, which is the safe answer and not the one you wanted — trusted HTML belongs in Article.
+- Do not expect the rhythm without a surface, and do not try to buy it with a gap. Every node renders m-0 into a bare fragment, and prose spacing is not uniform — article.css gives a heading 2.25em above and 0.75em below, which is what sits it with the paragraph it introduces. A uniform gap on a container cannot reproduce that; <Article as="div"> can.
+- Do not assume the full GFM surface. Tables, footnotes, task lists, setext headings, reference links and hard breaks are outside the built-in parser, and asking for one silently gets you a paragraph.
+
+## Accessibility
+
+- headingLevelStart shifts the whole document at once, so nested content keeps a valid outline instead of restarting at h1.
+- Every heading gets a stable, script-preserving id, deduplicated in document order, so a table of contents can link into it.
+- A link whose href carries a scheme that is not http, https, mailto or tel renders as plain text — javascript: never becomes a control.
+- A link that leaves for another site carries rel="noreferrer nofollow", so an untrusted author cannot spend the page’s ranking or read its URL out of the Referer. It is not configurable; markExternalLinks adds the visible outbound arrow and is off by default.
+- A malformed or empty string renders nothing rather than throwing, which is the normal case for content a reader wrote.
+
+## Markdown
+
+A Markdown string, rendered as this system's components. The gap it fills is content nobody on this side wrote: a comment, a README, a model's answer, a description out of a database. `Article` cannot take those — it renders HTML through `dangerouslySetInnerHTML` and is documented as trusted-input-only — and until now the alternative was a `<pre>` or a sanitiser bolted onto a styling primitive. IT IS NOT AN `Article`, and the two do not merge. `Markdown` turns a string into nodes; `Article` is the reading column those nodes can sit in. It renders a FRAGMENT rather than a wrapper, which is what makes that nesting work — `Article`'s rhythm is a direct-child combinator, so any element between the two, `display: contents` included, would cost every paragraph its spacing. ── It brings type and colour, and no vertical rhythm ── The nodes carry the system's faces and inks on their own, so one of these looks right in isolation. It is not SPACED in isolation: every node renders `m-0`, and a fragment has no box of its own to put a gap in. Nor does a uniform `gap` on a container reproduce it, because prose spacing is not uniform — `article.css` gives a heading 2.25em above and 0.75em below, which is what sits a heading with the paragraph it introduces rather than midway between two. For anything longer than a sentence — a comment, an answer, a README — put it in `<Article as="div">` and get the real rhythm for the cost of one element. ── A fenced code block brings a client component with it ── The renderer is plain functions and has no state, but a fenced block renders `CodeBlock`, which is `'use client'` and arrives with `useState`, `useEffect` and two icons. That is correct — the copy button is the reason the block exists — but "server-rendered" only holds for content with no code in it, which is worth knowing before this goes into a route that has no client bundle yet. ── Why there is no parser in `dependencies` ── Three options, and the decision is written here because it is the one a reader will want to argue with. 1. BUNDLE A PARSER. markdown-it is the obvious pick, and the documentation site already depends on it — but the site is an app and this is a library, where the dependency list is part of the contract every consumer signs. Measured with the same esbuild pass `check:size` uses, markdown-it is 110.7 kB minified against the 38.9 kB this package had left under its bundle budget. It is not close, and "we will raise the budget" is how a design system becomes the largest thing on a page. 2. TAKE PRE-PARSED HTML, the way `Article` does. Cheapest, and wrong for the case this exists for: HTML from an untrusted author is the input this is supposed to make safe, and it cannot carry `headingLevelStart` or stable heading ids without the component parsing markup back apart to find them. 3. PARSE THE SUBSET WE STYLE, and take a `parse` function for the rest. Chosen. The block grammar is line-based and small (see `parse.ts`), it emits React elements rather than markup — so there is no `dangerouslySetInnerHTML` in this path at all, no sanitiser to configure and no sanitiser to get wrong — and a consumer who needs tables, footnotes or task lists passes `parse` and keeps every other promise the component makes. Headings carry an `id` slugged from their own text and deduplicated within the document, so a table of contents can link to them without the caller post-processing the DOM to find out where they went. A link in the source is validated here, at the boundary: a scheme that is not `http`, `https`, `mailto` or `tel` never becomes a link, and one that leaves for another site carries `rel="noreferrer nofollow"` — so an author the page does not trust cannot spend its ranking or read its URL out of the `Referer`.
+
+### Props
+
+- `children` (required) — `string`. The Markdown source. A string — not nodes, not HTML.
+- `headingLevelStart` — `MarkdownHeadingLevel` default `1`. The level the document's top heading renders at. Markdown is written as a document, so its `#` is an `<h1>`. Dropped into a page that already has one — inside an `<h2>` section, in a card, under a dialog's title — that produces two first-level headings and an outline a screen reader cannot navigate. Set this to the level BELOW the heading the content sits under, and every level in the document shifts with it.
+- `idPrefix` — `string`. Namespaces the generated heading ids. Two documents on one page both containing "Installation" would otherwise both claim `#installation`, and a fragment link would land on whichever the browser found first.
+- `markExternalLinks` — `boolean` default `false`. Adds the system's outbound arrow to links that leave for another site. Off by default, and opt-in rather than automatic for two reasons. The mark is an addition to a sentence the component did not write, which is a different kind of act from styling one. And `Markdown` has no idea what origin it is being rendered on, so "leaves for another site" can only mean "carries an `http`/`https` scheme" — an absolute link back to your own domain gets the arrow too. A caller who knows the shape of their content turns it on; one who does not should not have it turned on for them. The `rel` on an outbound link is NOT opt-in and cannot be turned off: it is the security half of the same boundary as the scheme check.
+- `parse` — `(source: string) => MarkdownNode[]` default `parseMarkdown`. Bring your own parser. Anything that turns the source into `MarkdownNode`s: markdown-it, remark, or a pipeline that already has an AST and only needs mapping. The node shapes are exported alongside the component as `MarkdownNode`, `MarkdownInline` and `MarkdownHeadingLevel`. The built-in parser covers the subset this system styles; this is the seam for tables, footnotes, task lists and everything else.
+
+## Examples
+
+```tsx
+// A comment body or an answer: the reading column is what spaces it.
+<Article as="div">
+  <Markdown headingLevelStart={3} idPrefix="answer">{answer}</Markdown>
+</Article>
+// A whole document, in the column it was written for.
+<Article><Markdown>{readme}</Markdown></Article>
+// Tables and footnotes, via the consumer's own pipeline.
+<Markdown parse={(source) => toMarkdownNodes(md.parse(source, {}))}>{post}</Markdown>
+```