@jonmilner/ui 0.0.0-stage → 0.1.1

package/dist/docs/Dialog.md

@@ -0,0 +1,166 @@
+# Dialog
+
+## Purpose
+
+A modal panel over the page for one short task: edit a name, fill a small form, read details that need a decision. Built on Base UI's Dialog, which owns the behavior: focus moves into the dialog and stays there, the page behind is inert and does not scroll, Esc and a click on the backdrop close it, and focus returns to the trigger. The parts add the look: a dimmed backdrop, a raised panel with a title, and a zoom-and-fade that is a plain fade under reduced motion.
+
+## When to use
+
+- A task that needs the user's full attention before they go on, and fits on one screen.
+- A form too small for its own page (rename, invite one person, change a setting).
+
+## When not to use
+
+- Confirming something destructive or irreversible: use `AlertDialog`, which focuses Cancel and ignores outside clicks.
+- A list of actions: use `Menu`.
+- Content the user wants beside the page, or a hint: use a popover or inline text; a modal blocks the page.
+- A long flow or a lot of content: give it a page.
+- A status message or the result of an action: use `Toast`, which leaves focus where it is; a dialog takes it.
+
+## Rules
+
+- Compose the parts: `Dialog` > `Dialog.Trigger` + `Dialog.Popup` > `Dialog.Body` + `Dialog.Actions` > `Dialog.Close`. `Dialog` holds the open state and renders no element, so it takes no `className` or `style`; every other part does, plus style props.
+- `Dialog.Popup` takes a required `title` and an optional `description`. They head the panel as an `h2` and muted text, and name and describe the dialog for screen readers. Keep the title short: a noun phrase ("Rename project") or the question asked.
+- `size` (`sm`, `med`, `lg`; `med` by default) sets the width, 384, 512 or 640 px at the default font size; the panel never gets wider than the viewport less a 16 px edge.
+- Put the content in `Dialog.Body`. When the dialog outgrows the viewport the whole popup scrolls; keep the content short so the actions stay close.
+- `Dialog.Actions` end-aligns its buttons and wraps them on a narrow screen. Put `Dialog.Close` first, then one primary `Button`. A dialog with no buttons still closes on Esc and the backdrop, but give it a `Dialog.Close` so a pointer user sees the way out.
+- `Dialog.Trigger` and `Dialog.Close` are bare `Clickable`s. Pass Button's `variant`, `size`, `iconStart` or `iconEnd` for a button look (`variant="secondary"` on Close); they render a `Button` with its fill, border and height, and keep the part's behavior and `aria-disabled`. Without them, style them with style props and give them an accessible name.
+- `disabled` on the trigger keeps it focusable and announced, and stops it opening.
+- Control it with `open` and `onOpenChange` to close it after a save or keep it open on an error. `onOpenChangeComplete` runs once the exit transition ends.
+- The popup portals into the trigger's nearest `ThemeProvider`, so it keeps the brand and mode. That provider must not clip or stack its content: wrap the app root, and keep a nested provider off elements with `overflow: hidden`, a `transform` or their own `z-index`. It sits on `zIndex` `modal`. A dialog opened only through `open`, with no `Dialog.Trigger`, has no provider to find and portals to `<body>`.
+- It is always modal. Never add key handlers, `tabIndex` or your own focus trap to the parts.
+- The module has no hooks, so a server component can render the parts; `onOpenChange` and other functions must come from a client component.
+
+## Do
+
+Field has no input of its own yet (ADR 0026); Base UI's `Field.Control` stands in.
+
+```tsx
+<Dialog>
+  <Dialog.Trigger variant="secondary">Rename</Dialog.Trigger>
+  <Dialog.Popup
+    title="Rename project"
+    description="The new name shows everywhere the project does."
+  >
+    <Dialog.Body>
+      <Field name="name">
+        <Field.Label>Name</Field.Label>
+        <BaseField.Control defaultValue={name} />
+      </Field>
+    </Dialog.Body>
+    <Dialog.Actions>
+      <Dialog.Close variant="secondary">Cancel</Dialog.Close>
+      <Button onClick={save}>Save</Button>
+    </Dialog.Actions>
+  </Dialog.Popup>
+</Dialog>
+```
+
+```tsx
+// Closes once the save succeeds; stays open on an error.
+const [open, setOpen] = useState(false);
+<Dialog open={open} onOpenChange={setOpen}>
+  <Dialog.Trigger variant="primary">Invite</Dialog.Trigger>
+  <Dialog.Popup title="Invite a teammate" size="sm">
+    …
+  </Dialog.Popup>
+</Dialog>;
+```
+
+## Don't
+
+```tsx
+// Deleting forever needs AlertDialog: Cancel focused first, no dismissal by an outside click.
+<Dialog.Popup title="Delete project?">
+  <Dialog.Actions>
+    <Button variant="danger" onClick={deleteForever}>
+      Delete
+    </Button>
+  </Dialog.Actions>
+</Dialog.Popup>
+```
+
+```tsx
+// Two primary actions: the user can't tell which one finishes the task.
+<Dialog.Actions>
+  <Button>Save</Button>
+  <Button>Save and close</Button>
+</Dialog.Actions>
+```
+
+```tsx
+// A heading in the body instead of `title`: the dialog has no name.
+<Dialog.Popup title="">
+  <Heading>Rename project</Heading>
+</Dialog.Popup>
+```
+
+## Accessibility
+
+- The trigger has `aria-haspopup="dialog"` and `aria-expanded`. The popup is `role="dialog"` with `aria-modal`, labelled by the title and described by the description.
+- Opening moves focus into the popup; Tab and Shift+Tab cycle inside it, and the page behind is inert. Esc or a backdrop click closes it, and focus returns to the trigger.
+- The panel takes the shared focus ring when focused from the keyboard. Under forced colors it keeps its border, so it stays apart from the page.
+- The backdrop is 40% of the shadow color over the page; it only dims, and carries no text.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Dialog
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `defaultOpen` | `boolean` | no | Whether the dialog is initially open.  To render a controlled dialog, use the `open` prop instead. |
+| `onOpenChange` | `((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)` | no | Event handler called when the dialog is opened or closed. |
+| `onOpenChangeComplete` | `((open: boolean) => void)` | no | Event handler called after any animations complete when the dialog is opened or closed. |
+| `open` | `boolean` | no | Whether the dialog is currently open. |
+
+### Dialog.Actions
+
+No props of its own.
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Dialog.Body
+
+No props of its own.
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Dialog.Close
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `iconEnd` | `ComponentType` | no |  |
+| `iconStart` | `ComponentType` | no |  |
+| `size` | `"lg" \| "med" \| "sm"` | no |  |
+| `variant` | `"primary" \| "secondary"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Dialog.Popup
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `description` | `ReactNode` | no |  |
+| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null)` | no | Determines the element to focus when the dialog is closed.  - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).   Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
+| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null)` | no | Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.  - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).   Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
+| `size` | `"lg" \| "med" \| "sm"` | no |  |
+| `title` | `string \| number \| bigint \| Iterable<ReactNode> \| Promise<AwaitedReactNode> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| ReactPortal` | yes |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Dialog.Trigger
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `handle` | `DialogHandle<unknown>` | no | A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method. |
+| `iconEnd` | `ComponentType` | no |  |
+| `iconStart` | `ComponentType` | no |  |
+| `id` | `string` | no | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop). |
+| `payload` | `unknown` | no | A payload to pass to the dialog when it is opened. |
+| `size` | `"lg" \| "med" \| "sm"` | no |  |
+| `variant` | `"primary" \| "secondary"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/Field.md

@@ -0,0 +1,143 @@
+# Field
+
+## Purpose
+
+Wires one form control to its label, description and error: ids, `htmlFor`, `aria-describedby` and `aria-invalid`. It is input-agnostic: the control inside is Base UI's `Field.Control` or a Base UI control (Checkbox, Combobox), and Base UI does the wiring. The parts are `Field` (the root, a flex column), `Field.Label`, `Field.Description` and `Field.Error`. Built on Base UI `Field` (ADR 0003, 0026, 0046); `@base-ui/react` is a peer dependency, so the app's Base UI controls and Field share one copy of its contexts.
+
+## When to use
+
+- Any form control that needs a visible label, help text or an error, including a control a component builds (Checkbox, MultiSelect build on Field rather than their own wiring).
+- Showing a server validation error from a React Router action next to its control.
+
+## When not to use
+
+- An error about the whole form (a failed save, a network error): put it in a reserved slot at the form level, not on one field.
+- The result of submitting the form ("Profile saved"): use `Toast`; the field's message is for that one input.
+- A group of controls with one legend (a radio group): v0.2 adds `Fieldset`.
+- A styled text input or select: v0.1 has none; they come in v0.2 on this Field.
+
+## Rules
+
+- One control per Field. Put it between the label and the description; order in the DOM is the reading order.
+- Mark the field with `invalid` whenever you pass an error message; the message alone does not set `aria-invalid`.
+- `Field.Error` always renders a slot one line tall, so a one-line error appears without moving anything. A longer message wraps inside the field (even an unbroken URL) and pushes only what is below. Keep messages to one line where you can.
+- `Field.Error` with children shows them; with `match` set to a validity key (`"valueMissing"`), only when that check fails. Without children, it shows the control's native validation message while the control is invalid.
+- `Field.Label` renders a `label`. Keep it for `Field.Control` and for `Checkbox`, whose hidden input the label points at: clicking it toggles the checkbox, as on a native one. For a Base UI control with no input at all, set `nativeLabel={false}`; it renders a `span` that names the control (`aria-labelledby`); clicking it focuses the control.
+- `disabled` on Field disables the control and mutes the label. A message in `Field.Error` still shows while disabled; clear it if the field is locked.
+- `name`, `validate`, `validationMode`, `dirty` and `touched` pass through to Base UI's `Field.Root`. `validate` and event handlers are functions, so set them from a client component.
+- Every part takes style props; the root's `display`, `flexDirection` and `gap` (`"8"`) are defaults you can replace. The label, description and error also take Text's `size`, `font`, `weight`, `leading` and `truncate` over their defaults (`sm`; the label in the `label` font at `medium`). `className` is a string and `style` an object (not Base UI's state functions), and the consumer's come last.
+- The module has no hooks: a server component can render `Field` and its parts (the Base UI parts inside are client components). `render` is not accepted on the parts.
+- On `Field.Error`, style props, `className` and `style` go to the slot; `id`, `ref` and handlers go to the message, which exists only while it shows.
+
+## Do
+
+```tsx
+import { Field as BaseField } from "@base-ui/react/field";
+
+<Field name="email" invalid={Boolean(errors?.email)}>
+  <Field.Label>Email</Field.Label>
+  <BaseField.Control type="email" required defaultValue={values.email} />
+  <Field.Description>We only use it to send receipts.</Field.Description>
+  <Field.Error>{errors?.email}</Field.Error>
+</Field>;
+```
+
+```tsx
+// Native constraints: no children, so Base UI shows the browser's message.
+<Field name="age">
+  <Field.Label>Age</Field.Label>
+  <BaseField.Control type="number" min={18} required />
+  <Field.Error />
+</Field>
+```
+
+## Don't
+
+```tsx
+// An error without `invalid`: it shows, but the control is not marked invalid.
+<Field name="email">
+  <Field.Label>Email</Field.Label>
+  <BaseField.Control />
+  <Field.Error>Enter an email address.</Field.Error>
+</Field>
+```
+
+```tsx
+// A bare input outside Base UI gets no ids: the label and messages are not linked.
+<Field>
+  <Field.Label>Email</Field.Label>
+  <input />
+</Field>
+```
+
+```tsx
+// Placeholder as the label: it disappears on input and is not a label.
+<Field>
+  <BaseField.Control placeholder="Email" />
+</Field>
+```
+
+## Accessibility
+
+- The label is the control's accessible name; clicking it focuses the control.
+- The description and the error join the control's `aria-describedby`, so they are read with it. Base UI adds them after hydration; server HTML has the label link and `aria-invalid`.
+- The error slot is a `role="alert"` live region that stays in the page, so a message is announced when it appears, also after a client-side submit. Several fields failing at once each announce.
+- The error is never color alone: a decorative alert icon (`aria-hidden`, at the text's size) leads the message, so it reads as an error under forced colors too, and the message says what is wrong and how to fix it.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Field
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `actionsRef` | `RefObject<FieldRootActions \| null>` | no | A ref to imperative actions. - `validate`: Validates the field when called. |
+| `dirty` | `boolean` | no | Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library. |
+| `disabled` | `boolean` | no | Whether the component should ignore user interaction. Takes precedence over the `disabled` prop on the `<Field.Control>` component. |
+| `invalid` | `boolean` | no | Whether the field is invalid. Useful when the field state is controlled by an external library. |
+| `name` | `string` | no | Identifies the field when a form is submitted. Takes precedence over the `name` prop on the `<Field.Control>` component. |
+| `touched` | `boolean` | no | Whether the field has been touched. Useful when the field state is controlled by an external library. |
+| `validate` | `((value: unknown, formValues: Record<string, any>) => void \| string \| string[] \| Promise<void \| string \| string[] \| null> \| null)` | no | A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid. Returning nothing, `null`, an empty string, or an empty array means the value is valid. Asynchronous functions are supported, but they do not prevent form submission when using `validationMode="onSubmit"`. |
+| `validationDebounceTime` | `number` | no | How long to wait between `validate` callbacks if `validationMode="onChange"` is used. Specified in milliseconds. |
+| `validationMode` | `"onBlur" \| "onChange" \| "onSubmit"` | no | Determines when the field should be validated. This takes precedence over the `validationMode` prop on `<Form>`.  - `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission. - `onBlur`: triggers validation when the control loses focus. - `onChange`: triggers validation on every change to the control value. |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Field.Description
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `font` | `"body" \| "display" \| "heading" \| "label" \| "mono"` | no |  |
+| `leading` | `"lg" \| "med" \| "sm"` | no |  |
+| `size` | `"2xl" \| "3xl" \| "4xl" \| "lg" \| "med" \| "sm" \| "xl" \| "xs"` | no |  |
+| `truncate` | `boolean` | no |  |
+| `weight` | `"bold" \| "medium" \| "regular" \| "semibold"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Field.Error
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `font` | `"body" \| "display" \| "heading" \| "label" \| "mono"` | no |  |
+| `leading` | `"lg" \| "med" \| "sm"` | no |  |
+| `match` | `boolean \| keyof ValidityState` | no | Determines whether to show the error message according to the field's [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState). Specifying `true` will always show the error message, and lets external libraries control the visibility. |
+| `size` | `"2xl" \| "3xl" \| "4xl" \| "lg" \| "med" \| "sm" \| "xl" \| "xs"` | no |  |
+| `truncate` | `boolean` | no |  |
+| `weight` | `"bold" \| "medium" \| "regular" \| "semibold"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+### Field.Label
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `font` | `"body" \| "display" \| "heading" \| "label" \| "mono"` | no |  |
+| `leading` | `"lg" \| "med" \| "sm"` | no |  |
+| `nativeLabel` | `boolean` | no | Whether the component renders a native `<label>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a label (for example, `<div>`).  This is useful to avoid inheriting label behaviors on `<button>` controls (such as `<Select.Trigger>` and `<Combobox.Trigger>`), including avoiding `:hover` on the button when hovering the label, and preventing clicks on the label from firing on the button. |
+| `size` | `"2xl" \| "3xl" \| "4xl" \| "lg" \| "med" \| "sm" \| "xl" \| "xs"` | no |  |
+| `truncate` | `boolean` | no |  |
+| `weight` | `"bold" \| "medium" \| "regular" \| "semibold"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/Heading.md

@@ -0,0 +1,69 @@
+# Heading
+
+## Purpose
+
+Section and page headings. A `Text` with heading defaults: the `heading` font role, `semibold`, `sm` leading, and balanced line wrapping. The level (`as`) and the look (`size`) are separate, so the outline stays right whatever the design calls for.
+
+## When to use
+
+- Any heading in the document outline: page title, section, card, dialog title.
+
+## When not to use
+
+- Large text that is not a heading (a stat, a hero tagline): use `Text` with `size` and `font="display"`.
+- Bold body text: use `Text` with `weight`.
+
+## Rules
+
+- `as` is the level, `h1` to `h6`; the default is `h2`. Pick it from the outline, not the look.
+- `size` is the look: `sm`, `med`, `lg`, `xl` or `2xl`. Unset, it follows the level: `h1` `2xl`, `h2` `xl`, `h3` `lg`, `h4` `med`, `h5` and `h6` `sm`.
+- Heading takes every other Text prop (`font`, `weight`, `leading`, `color`, `truncate`, style props) and overrides its defaults with them.
+- One `h1` per page; do not skip levels going down.
+
+## Do
+
+```tsx
+<Heading as="h1">Settings</Heading>
+```
+
+```tsx
+// A dialog title in a page's outline is an h2, but looks smaller.
+<Heading as="h2" size="lg">
+  Delete project?
+</Heading>
+```
+
+## Don't
+
+```tsx
+// A level picked for its look breaks the outline; set `size` instead.
+<Heading as="h4">Section</Heading>
+```
+
+```tsx
+// Headings stop at 2xl; for display type use Text.
+<Heading size="4xl" />
+```
+
+## Accessibility
+
+- The element is the level screen reader users navigate by; keep levels in order.
+- A heading that only looks like one is not one: never fake a heading with `Text weight="bold"`.
+- Truncated headings lose words for everyone; prefer wrapping.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Heading
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `as` | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"` | no |  |
+| `font` | `"body" \| "display" \| "heading" \| "label" \| "mono"` | no |  |
+| `leading` | `"lg" \| "med" \| "sm"` | no |  |
+| `size` | `"2xl" \| "lg" \| "med" \| "sm" \| "xl"` | no |  |
+| `truncate` | `boolean` | no |  |
+| `weight` | `"bold" \| "medium" \| "regular" \| "semibold"` | no |  |
+
+Also accepts every `<h2>` attribute (change the element with `as`) and the style props (see `manifest.json` `styleProps`).

package/dist/docs/Icon.md

@@ -0,0 +1,116 @@
+# Icon
+
+## Purpose
+
+The base for every icon: an `<svg>` on a 24-unit grid that draws its children with round 2-unit strokes in `currentColor`. Generated icons from `@jonmilner/ui/icons` (`ArrowRightIcon`, …) wrap it and take the same props, less `children` and `viewBox`. `size` takes a `fontSize` step, so an icon matches the `Text` beside it; `color` takes a color role.
+
+## When to use
+
+- A one-off glyph the icon set lacks: pass its shapes as children.
+- Building a component with an icon slot: render the consumer's icon, or an `Icon`, at the `size` of the component's text.
+- Prefer a generated `<Name>Icon` from `@jonmilner/ui/icons` when one exists.
+
+## When not to use
+
+- Images, illustrations and logos with their own colors: use `img` or a dedicated component.
+- An icon-only control: use `IconButton`, which takes the accessible name.
+- An icon that is the only content of a link or button: name the control, not the icon.
+
+## Rules
+
+- `size` is a `fontSize` step (`xs`–`4xl`), `med` by default; use the step of the text it sits beside. The middle step is `med`, never `md`.
+- `color` is a color role (`fg`, `fgMuted`, `accent`, `danger`, …). Unset, the icon takes the surrounding text color.
+- Shapes inherit `stroke="currentColor"` and `fill="none"`. A filled shape sets `fill="currentColor"`; a fill-only icon passes `stroke="none"`.
+- `viewBox` defaults to `0 0 24 24`; pass another for shapes drawn on a different grid.
+- `label` names the icon. Without a name the icon is decorative and `aria-hidden`; `aria-label` and `aria-labelledby` also name it, and `label` wins over both. Name it with these, not a `<title>` child, which stays hidden.
+- `size` sets the box; there is no `width` or `height`. Use `style` or an unlayered class for a size off the scale.
+- The consumer's `className` comes last, and `style` and other svg attributes pass through; `role`, `aria-hidden` and the name are always set from the rule above.
+- It is a block box that doesn't shrink: place it beside text with `Inline`, not inside a `Text` run.
+- `ref` is a plain prop for the `<svg>`. No hooks or context, so it renders in a server component.
+
+## Do
+
+```tsx
+<Inline gap="8">
+  <ArrowRightIcon size="sm" color="fgMuted" />
+  <Text size="sm" color="fgMuted">
+    Continue
+  </Text>
+</Inline>
+```
+
+```tsx
+<Icon label="Warning" color="danger">
+  <path d="M12 9v4M12 17h.01M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0Z" />
+</Icon>
+```
+
+## Don't
+
+```tsx
+// Raw colors and pixel sizes bypass the tokens; neither type-checks.
+<Icon color="#c00" size="20px" />
+```
+
+```tsx
+// The icon is hidden, so this button has no name.
+<button>
+  <XIcon />
+</button>
+```
+
+```tsx
+// Naming the icon inside a labelled control announces the name twice.
+<Button>
+  <SaveIcon label="Save" /> Save
+</Button>
+```
+
+## Icon set
+
+Generated from `src/icons/svg/` and exported from `@jonmilner/ui/icons`; each takes `Icon`'s props except `children` and `viewBox`. Lucide icons keep their Lucide name.
+
+<!-- icons:start -->
+
+- `ArrowLeftIcon` (`arrow-left.svg`)
+- `ArrowRightIcon` (`arrow-right.svg`)
+- `CheckIcon` (`check.svg`)
+- `ChevronDownIcon` (`chevron-down.svg`)
+- `ChevronRightIcon` (`chevron-right.svg`)
+- `CircleAlertIcon` (`circle-alert.svg`)
+- `CircleCheckIcon` (`circle-check.svg`)
+- `CircleDotIcon` (`circle-dot.svg`)
+- `CircleSlashIcon` (`circle-slash.svg`)
+- `GitMergeIcon` (`git-merge.svg`)
+- `GitPullRequestClosedIcon` (`git-pull-request-closed.svg`)
+- `GitPullRequestDraftIcon` (`git-pull-request-draft.svg`)
+- `GitPullRequestIcon` (`git-pull-request.svg`)
+- `InboxIcon` (`inbox.svg`)
+- `InfoIcon` (`info.svg`)
+- `LoaderCircleIcon` (`loader-circle.svg`)
+- `RefreshCwIcon` (`refresh-cw.svg`)
+- `SearchIcon` (`search.svg`)
+- `SettingsIcon` (`settings.svg`)
+- `XIcon` (`x.svg`)
+
+<!-- icons:end -->
+
+## Accessibility
+
+- Decorative by default: `aria-hidden="true"` and no role, so text beside it carries the meaning.
+- With `label`, it is `role="img"` with that `aria-label`. Use it when the icon alone conveys something, such as a status next to a number.
+- Do not convey state with icon color alone; pair it with a shape change or text.
+- Under forced colors `currentColor` follows the system text color, so the icon stays visible.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Icon
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `color` | `"accent" \| "accentFg" \| "bg" \| "bgMuted" \| "bgRaised" \| "border" \| "borderStrong" \| "danger" \| "dangerFg" \| "fg" \| "fgMuted" \| "focus"` | no |  |
+| `label` | `string` | no |  |
+| `size` | `"2xl" \| "3xl" \| "4xl" \| "lg" \| "med" \| "sm" \| "xl" \| "xs"` | no |  |
+| `strokeWidth` | `number` | no |  |

package/dist/docs/IconButton.md

@@ -0,0 +1,83 @@
+# IconButton
+
+## Purpose
+
+A compact button whose only visible content is an icon, for an action the icon makes plain: close, edit, refresh. A required `label` names it for assistive technology (`aria-label`); the icon is decorative. It is a `<button type="button">` on `Clickable`, so it has the shared focus ring, the 24px minimum target and `aria-disabled` that blocks activation while the button stays focusable. Two variants from Button's fills (`primary`, `secondary`) and three square sizes at Button's heights (`sm`, `med`, `lg`: 32, 40 and 48 px).
+
+## When to use
+
+- A frequent action whose icon is widely understood: close a dialog or panel, edit a row, refresh a list.
+- A dense toolbar or a table row where a labelled `Button` would not fit.
+
+## When not to use
+
+- Space allows a label, or the icon is not universally understood: use `Button`, with `iconStart` or `iconEnd` if the icon helps.
+- A toggle that stays pressed (bold, mute) or a filter choice: use `Chip`, or a pressed icon toggle when it lands; IconButton is not a toggle.
+- Opening a menu: use `Menu.Trigger`; an icon-only trigger is planned separately.
+- A pressable area with its own layout, such as a whole card: use `Clickable`.
+
+## Rules
+
+- `label` is required and is the accessible name: say what the button does ("Close dialog", "Refresh results"), not what the icon shows ("X", "Arrows"). Never pass an empty string: the button would have no name. `aria-label`, `aria-labelledby` and children are not props; a raw one is ignored.
+- `icon` takes an icon component (a generated `XIcon`, or a component that renders `Icon`), not an element: IconButton renders it at the `fontSize` step of its `size`, `aria-hidden`.
+- `variant`: `secondary` (default) for most actions; `primary` for the one action a view or dialog exists for. There is no `danger` in v0.1: a destructive action deserves a labelled `Button`.
+- `size`: `sm`, `med` (default) or `lg`, never `md`. Each is a square of Button's height of the same name, so an IconButton lines up with a Button beside it.
+- `disabled` renders `aria-disabled="true"` and a dashed border, never the native `disabled`. There is no `loading` and no tooltip in v0.1.
+- With `aria-expanded="true"`, as a Dialog trigger sets it, it holds the hover tint and an inset ring while the popup is open, as Button does.
+- Fill (`backgroundColor`), text color (`color`), width (`minInlineSize`), height (`minBlockSize`) and `borderRadius` are default style props: pass one to change it. Change width and height together to keep the square. Hover tints whatever the fill is; a custom fill needs an icon color that passes 3:1 on it (4.5:1 to match Button).
+- `as="a"` with `href` for an icon-only link.
+- Server-safe: IconButton has no hooks; `Clickable` inside it is the client boundary.
+
+## Do
+
+```tsx
+<IconButton label="Close dialog" icon={XIcon} onClick={close} />
+```
+
+```tsx
+<Inline gap="8" alignItems="center">
+  <Button>Export</Button>
+  <IconButton label="Refresh results" icon={RefreshCwIcon} />
+</Inline>
+```
+
+## Don't
+
+```tsx
+// The label names the icon, not the action.
+<IconButton label="X" icon={XIcon} />
+```
+
+```tsx
+// An element: IconButton cannot size it to its step.
+<IconButton label="Close" icon={<XIcon />} />
+```
+
+```tsx
+// An obscure icon with no visible text: use a labelled Button.
+<IconButton label="Reconcile accounts" icon={GitMergeIcon} />
+```
+
+## Accessibility
+
+- The `label` is announced as the button's name; the icon is hidden from assistive technology.
+- The label is not shown on hover or focus. Sighted users who don't recognise the icon get no text, so keep IconButton to widely understood icons.
+- A disabled IconButton stays in the tab order, and Enter and Space do nothing. State is never color alone: disabled adds a dashed border.
+- Every size is at least 24 by 24 CSS px (WCAG 2.2 target size); the icon on each variant passes 4.5:1 at rest and on hover in light and dark modes. Under forced colors it keeps Button's system colors.
+
+## Props
+
+Generated from the TypeScript types.
+
+### IconButton
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `as` | `ElementType` | no |  |
+| `disabled` | `boolean` | no |  |
+| `icon` | `ComponentType` | yes |  |
+| `label` | `string` | yes |  |
+| `size` | `"lg" \| "med" \| "sm"` | no |  |
+| `variant` | `"primary" \| "secondary"` | no |  |
+
+Also accepts every `<button>` attribute (change the element with `as`) and the style props (see `manifest.json` `styleProps`).

package/dist/docs/Inline.md

@@ -0,0 +1,79 @@
+# Inline
+
+## Purpose
+
+A horizontal row of children that wraps onto new lines, with even space between them on both axes. `Inline` is a `Box` with `display="flex"`, `flexDirection="row"`, `flexWrap="wrap"` and `alignItems="center"` as default style props, spaced by a required `gap`. Children render as they are: no wrapper per child.
+
+## When to use
+
+- A group of buttons, tags, pills or badges: `<Inline gap="8">`.
+- Metadata on one line that wraps when narrow: author, date, read time.
+- An icon beside a label, centered on the cross axis.
+
+## When not to use
+
+- A vertical column: use `Stack`.
+- A row that must never wrap and splits space between ends (a toolbar, a header bar): use `Box` with `display="flex"` and `justifyContent="space-between"`, or pass `flexWrap="nowrap"`.
+- A two-dimensional layout: use `Box` with `display="grid"`.
+
+## Rules
+
+- `gap` is required and takes spacing tokens only: px keys (`"8"`) or a responsive object (`{ base: "4", med: "8" }`). The same gap applies between items and between wrapped lines.
+- Space comes from `gap`, never from margins on the children.
+- It takes every `Box` prop, and the layout defaults are style props, so `flexWrap`, `alignItems` and `justifyContent` override them.
+- Children are not wrapped, so each child is a flex item.
+- The consumer's `className` comes last and `style` is passed through; `ref` is a plain prop typed for the `as` element.
+
+## Do
+
+```tsx
+<Inline gap="8">
+  <Button variant="primary">Save</Button>
+  <Button>Cancel</Button>
+</Inline>
+```
+
+```tsx
+<Inline as="ul" gap="4" aria-label="Tags">
+  <li>…</li>
+</Inline>
+```
+
+## Don't
+
+```tsx
+// Margins between items instead of gap; and `gap` is required.
+<Inline>
+  <Pill>One</Pill>
+  <Box marginInlineStart="8">
+    <Pill>Two</Pill>
+  </Box>
+</Inline>
+```
+
+```tsx
+// Reversing a row reorders it visually but not for keyboard or screen reader users.
+<Inline gap="8" flexDirection="row-reverse">
+  <Button>Next</Button>
+  <Button>Back</Button>
+</Inline>
+```
+
+## Accessibility
+
+- Inline adds no role or ARIA. Pick the element with `as`: `ul` with `li` children for a list of tags or links.
+- Visual order is source order; do not reorder meaningful content with `row-reverse`, since reading and focus order follow the source.
+- Wrapping keeps the row usable at 400% zoom and narrow widths; keep `flexWrap="wrap"` unless the content is guaranteed to fit.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Inline
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `as` | `ElementType` | no |  |
+| `gap` | `"0" \| "1" \| "2" \| "4" \| "6" \| "8" \| "12" \| "16" \| "20" \| "24" \| "32" \| "40" \| "48" \| "64" \| "80" \| "96"` (responsive) | yes |  |
+
+Also accepts every `<div>` attribute (change the element with `as`) and the style props (see `manifest.json` `styleProps`).