@jonmilner/ui 0.0.0-stage → 0.1.1

package/dist/docs/Badge.md

@@ -0,0 +1,76 @@
+# Badge
+
+## Purpose
+
+A static label that states the status of, or a short fact about, the thing beside it: "Draft", "Failed", "Beta". A `span` with a fill from the color roles around a `Text` in the `label` font. It has no role and is never focusable.
+
+## When to use
+
+- The status of a row, card or page title: "Draft", "Published", "Failed".
+- Short metadata next to a name: "Beta", "Admin", "v2".
+
+## When not to use
+
+- A category or topic label on content: use `Tag` (#101).
+- A filter or choice the user toggles: use `Chip` (#102).
+- Anything pressable: compose `Clickable`; Badge has no click, hover or focus state.
+- A count or dot on another element (unread messages on an icon): not Badge's job.
+- A sentence or a message: use `Text`, or a field's error on the field.
+- The brief result of an action ("Saved"): use `Toast`; a badge stays put and says nothing new.
+
+## Rules
+
+- `variant`: `neutral` (default, `fgMuted` on `bgMuted`) for most statuses and facts; `accent` (`accentFg` on `accent`) to draw the eye; `danger` (`dangerFg` on `danger`) for a failure or a blocked state. `success` and `warning` arrive with their color roles.
+- `size`: `sm` or `med` (default), the label's `fontSize` step.
+- The label states the state. Color is never the only cue (WCAG 1.4.1): under forced colors every variant is the same outlined box, and some readers cannot tell the fills apart. Write "Failed", not a red badge reading "3".
+- Keep it to one or two words; it never wraps. With no children it renders nothing.
+- Fill, text color, padding, radius and `display` (`inline-block`) are default style props on the outer `span`; a consumer's win. `className`, `style` and `ref` go to it, `className` last. The box holds inside a `Text` or `Heading` too.
+- The module has no hooks, so a server component can render it.
+- Migrating from the inbox's `Pill`: `Pill tone=…` is `Badge variant=…`; `pillLink` has no Badge equivalent (compose `Clickable`).
+
+## Do
+
+```tsx
+<Inline gap="8" alignItems="center">
+  <Heading as="h2">Quarterly report</Heading>
+  <Badge>Draft</Badge>
+</Inline>
+```
+
+```tsx
+<Badge variant="danger" size="sm">
+  Failed
+</Badge>
+```
+
+## Don't
+
+```tsx
+// Color alone carries the state; under forced colors this is an outlined "Build".
+<Badge variant="danger">Build</Badge>
+```
+
+```tsx
+// A badge is not a button; compose Clickable for anything pressable.
+<Badge onClick={retry}>Retry</Badge>
+```
+
+## Accessibility
+
+- It is plain text in a `span`: screen readers read the label in line with what is around it, so the label must make sense there ("Quarterly report Draft").
+- No role, no `aria-live`: a badge that changes is not announced. If a status change matters right away, announce it elsewhere (a toast).
+- Each variant's text and fill pass AA (4.5:1) in light and dark mode; the pairs are in `contrastPairs` (ADR 0033).
+- Under forced colors every badge is `CanvasText` on `Canvas` with a `CanvasText` outline, so the box survives and the variants look alike; the label carries the meaning. The role fills are not kept: `accent` would take the link color, on something that is not a link, and the browser's backplate would hide the filled variants' text.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Badge
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `size` | `"med" \| "sm"` | no |  |
+| `variant` | `"accent" \| "danger" \| "neutral"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/Box.md

@@ -0,0 +1,87 @@
+# Box
+
+## Purpose
+
+The base element every component builds on: one element, chosen with `as`, styled with style props. Style props are the token-backed classes from `@layer atoms`: layout (`display`, flex, `gap`, logical padding, margin and sizing), color roles, `borderRadius`, `boxShadow`, `position`, `zIndex`, `overflow` and `textAlign`.
+
+## When to use
+
+- Layout and surfaces that need tokens but no behavior: a padded panel, a flex row, a sticky bar.
+- A semantic element (`as="section"`, `as="nav"`, `as="ul"`) that needs style props.
+- Building a new component: render a `Box` and pass its tunable values as default style props.
+
+## When not to use
+
+- Text: use `Text` or `Heading`; all visible text goes through them.
+- Stacks and rows of children with a gap: use `Stack` or `Inline`.
+- Anything interactive: use `Button` or a link component, which bring focus and states.
+
+## Rules
+
+- Style props take token keys only. Spacing keys are px values (`"16"`); the middle step is `med`, never `md`.
+- Properties are logical: `paddingInline`, `marginBlockStart`, `inlineSize`. There is no `paddingLeft` or `width`.
+- Sizing keys `xs`, `sm`, `med`, `lg` and `xl` are control heights, 24 to 56px: `maxInlineSize="lg"` is 48px wide. For a page or panel width use a container width, on `inlineSize`, `minInlineSize` and `maxInlineSize` only: `prose` (40rem, a reading column), `page` (64rem) or `wide` (80rem). `full`, `fit`, `min`, `max` and `auto` work on every sizing prop.
+- Only layout props are responsive: `{ base: "none", med: "flex" }` with breakpoints `sm`, `med`, `lg`, `xl`. Color and the rest take one value.
+- There are no hover, focus or active props; states belong in component CSS.
+- `null` and `false` leave a prop unset, so `paddingInline={dense && "8"}` works.
+- The consumer's `className` comes last and `style` is passed through, so consumer values win.
+- `ref` is a plain prop and is typed for the `as` element.
+
+## Do
+
+```tsx
+<Box as="section" display={{ base: "block", med: "flex" }} gap="16" paddingInline="24">
+  …
+</Box>
+```
+
+```tsx
+<Box backgroundColor="bgRaised" borderRadius="med" boxShadow="sm" padding="16" />
+```
+
+```tsx
+// A centered page: full width on small screens, at most 64rem on wide ones.
+<Box as="main" maxInlineSize="page" marginInline="auto" padding={{ base: "16", med: "32" }}>
+  …
+</Box>
+```
+
+## Don't
+
+```tsx
+// Physical property, `md`: neither type-checks.
+<Box paddingLeft="16" gap="md" />
+```
+
+```tsx
+// `lg` is a control height: this page is 48px wide.
+<Box as="main" maxInlineSize="lg" marginInline="auto" />
+```
+
+```tsx
+// `style` is not checked: raw values here bypass the tokens.
+<Box style={{ color: "#333" }} />
+```
+
+```tsx
+// A clickable Box has no focus ring, role or keyboard support.
+<Box onClick={open}>Open</Box>
+```
+
+## Accessibility
+
+- Box adds no role or ARIA. Pick the element with `as` so the structure is right: `nav`, `main`, `ul`, `section` with a label.
+- `display="none"` hides content from assistive tech as well as from sight.
+- Do not make a Box interactive; use the component built for it.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Box
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `as` | `ElementType` | no |  |
+
+Also accepts every `<div>` attribute (change the element with `as`) and the style props (see `manifest.json` `styleProps`).

package/dist/docs/Button.md

@@ -0,0 +1,98 @@
+# Button
+
+## Purpose
+
+The labelled action: a `<button type="button">` with the house look, or a link styled as one with `as="a"` (or a router's link). Three variants (`primary`, `secondary`, `danger`), three sizes (`sm`, `med`, `lg`, 32, 40 and 48 px high), a `loading` state that keeps its width, and icon slots before and after the label. It is built on `Clickable`, so it has the shared focus ring, the 24px minimum target and `aria-disabled` / `aria-busy` states that block activation while the button stays focusable.
+
+## When to use
+
+- Any action a user takes with a labelled control: save, cancel, open a dialog, submit a form (`type="submit"`).
+- A link that should look like an action, such as "Create report" leading to a new page: `as="a"` with `href`.
+
+## When not to use
+
+- An icon with no visible label: use `IconButton`.
+- A link inside running text: use a plain `<a>` (or the link component).
+- A toggle, a choice between options, or a menu trigger: use the component for that widget (Checkbox, Tabs, Menu), which handles its keyboard and state.
+- A one-off pressable area, such as a whole card: use `Clickable`.
+
+## Rules
+
+- `primary` marks the one action a view or dialog exists for; everything else is `secondary`, the default. One primary per group.
+- `danger` (`dangerFg` on `danger`, ADR 0060) replaces `primary` when that action destroys data or cannot be undone, such as a confirm dialog's "Delete project". It takes `primary`'s place, so a group has one `primary` or one `danger`, not both. The label names the consequence ("Delete project", not "OK"): under forced colors `danger` looks like `primary`, so the word carries the meaning, not the color. Confirm before an irreversible action runs; `danger` does not.
+- Sizes are `sm`, `med` (default) and `lg`, never `md`. The label and the icons take the `fontSize` step of the same name.
+- `loading` renders `aria-busy="true"`, blocks clicks, Enter and Space, and swaps the label for three pulsing dots in the same space: the width never changes, and the label stays the accessible name. A label narrower than the dots (one character, such as a page number) widens by a few pixels; give such buttons a fixed `minInlineSize`. Announce the outcome elsewhere (a toast or a status message); `aria-busy` alone is not announced.
+- `disabled` renders `aria-disabled="true"` and a dashed border, never the native `disabled`: the button stays focusable and announced. Say why it is disabled nearby when it is not obvious.
+- `iconStart` and `iconEnd` take an icon component (a generated `ArrowRightIcon`, or a component that renders `Icon`), not an element: Button renders it at its text size. The icons are decorative; the label names the button.
+- Children are the label, rendered inside `Text`; pass a string, not your own `Text` or `Icon`.
+- Fill (`backgroundColor`), text color (`color`), height (`minBlockSize`), `paddingBlock` (which keeps a wrapped label off the border), `paddingInline`, `borderRadius` and `gap` (between icons and label) are default style props: pass one to change it. Hover tints whatever the fill is (not under forced colors, where hover keeps only the pointer cue); the disabled look is component CSS keyed off `aria-disabled`, so it wins over a custom fill. A custom fill needs a text color that passes 4.5:1 on it.
+- With `aria-expanded="true"` (a Menu or Dialog trigger while its popup is open, or your own disclosure button), a live button holds the hover tint and draws a 1px inset ring in its text color: a shape cue, kept under forced colors, that takes no layout space (ADR 0063). While open, the ring replaces a custom `boxShadow`.
+- `type="submit"` for a form's submit button; otherwise it is `type="button"`.
+- Server-safe: Button has no hooks; `Clickable` inside it is the client boundary.
+
+## Do
+
+```tsx
+<Inline gap="8">
+  <Button variant="primary" loading={saving} onClick={save}>
+    Save
+  </Button>
+  <Button onClick={cancel}>Cancel</Button>
+</Inline>
+```
+
+```tsx
+<Button as={RouterLink} to="/reports/new" iconEnd={ArrowRightIcon}>
+  Create report
+</Button>
+```
+
+## Don't
+
+```tsx
+// Changing the label while loading moves the layout and the accessible name; `loading` keeps both.
+<Button disabled={saving}>{saving ? "Saving…" : "Save"}</Button>
+```
+
+```tsx
+// An element in the slot: Button cannot size it to the text.
+<Button iconStart={<ArrowLeftIcon />}>Back</Button>
+```
+
+```tsx
+// Red for emphasis on a safe action: `danger` means the action destroys something.
+<Button variant="danger">Publish</Button>
+```
+
+```tsx
+// Two primaries compete; one action leads.
+<Button variant="primary">Save</Button>
+<Button variant="primary">Publish</Button>
+```
+
+## Accessibility
+
+- A button that goes somewhere is a link (`as="a"` with `href`); one that does something is a button.
+- Disabled and loading buttons stay in the tab order, so keyboard and screen reader users find them; Enter and Space do nothing while either is set.
+- State is never color alone: disabled adds a dashed border, loading shows the dots. Under forced colors the button keeps its system colors (`LinkText` fill for `primary` and `danger`, a `CanvasText` border for `secondary`) and a disabled one is `GrayText`. Hover draws no tint there, so the system pairs keep their contrast.
+- Under reduced motion the dots hold still.
+- Text on every variant passes 4.5:1 at rest and on hover in light and dark modes.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Button
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `aria-busy` | `"false" \| "true" \| boolean` | no |  |
+| `as` | `ElementType` | no |  |
+| `disabled` | `boolean` | no |  |
+| `iconEnd` | `ComponentType` | no |  |
+| `iconStart` | `ComponentType` | no |  |
+| `loading` | `boolean` | no |  |
+| `size` | `"lg" \| "med" \| "sm"` | no |  |
+| `variant` | `"danger" \| "primary" \| "secondary"` | no |  |
+
+Also accepts every `<button>` attribute (change the element with `as`) and the style props (see `manifest.json` `styleProps`).

package/dist/docs/Checkbox.md

@@ -0,0 +1,107 @@
+# Checkbox
+
+## Purpose
+
+A two-state choice, with a third mixed state for a "select all" over a partly selected list. Built on Base UI `Checkbox` (ADR 0003, 0046): a `span` with `role="checkbox"` and `aria-checked`, plus a hidden `<input type="checkbox">` that submits with the form. The span is a 24 by 24 CSS px target (WCAG 2.2) with the shared focus ring; the 16px box inside fills and shows a tick when checked, a dash when mixed. It composes `Field` for its label, description and error (ADR 0026).
+
+## When to use
+
+- An on/off choice that takes effect when the form is submitted ("Accept the terms", "Email me receipts").
+- Selecting rows or items in a list, with an indeterminate "select all".
+
+## When not to use
+
+- A setting that applies the moment it flips: v0.2 adds `Switch`.
+- One choice out of several: v0.2 adds `Radio`.
+- Picking several options from a long list in a popup: use `MultiSelect`.
+
+## Rules
+
+- Give it a name: a `Field.Label` in a `Field` (preferred), or `aria-label` when the context shows the meaning (a table row's checkbox).
+- In a `Field`, keep the default native `Field.Label`. It points at the hidden input, so clicking the label toggles the checkbox, as on a native one. `nativeLabel={false}` would only focus it.
+- Put `name` on the `Field` (or on the Checkbox outside one). A checked box submits `value` (default `"on"`); an unchecked one submits nothing unless you set `uncheckedValue`.
+- `checked` with `onCheckedChange` controls it; `defaultChecked` leaves it uncontrolled.
+- `indeterminate` shows the dash and sets `aria-checked="mixed"`, whatever `checked` is. Clear it yourself when the user clicks: Base UI toggles `checked` but leaves `indeterminate` as you pass it.
+- `disabled` takes it out of the tab order and dashes the border; `readOnly` keeps it focusable and announced (`aria-readonly`) but unchangeable; it looks like an editable one apart from the cursor and no hover, so say nearby why it cannot change. Set `disabled` on the `Field` to disable the checkbox and mute the label together.
+- Space toggles it; Enter submits the form it is in, as on a native checkbox.
+- For an error, set `invalid` on the `Field` with the message in `Field.Error`; the box border thickens and turns `danger`, and the message says what is wrong.
+- Layout and the target are default style props (`display="inline-flex"`, centered, `flexShrink={0}`, `minInlineSize` and `minBlockSize` `"xs"`, 24px). Raise them freely; never set them below `"xs"`. The box is 16px; there are no sizes yet.
+- `className` is a string and `style` an object (not Base UI's state functions); they go to the span, after the defaults. `render` and `nativeButton` are not accepted.
+- The module has no hooks, so a server component can render it. `onCheckedChange` is a function: set it from a client component.
+- Style states off the ARIA attributes (`[aria-checked='true']`, `'mixed'`, `[aria-disabled='true']`, `[aria-invalid='true']`), not Base UI's `data-*` attributes.
+
+## Do
+
+```tsx
+<Field name="terms" invalid={Boolean(errors?.terms)}>
+  <Inline gap="8" alignItems="center">
+    <Checkbox required />
+    <Field.Label>Accept the terms</Field.Label>
+  </Inline>
+  <Field.Description>You can withdraw any time.</Field.Description>
+  <Field.Error>{errors?.terms}</Field.Error>
+</Field>
+```
+
+```tsx
+// "Select all": mixed while some rows are selected.
+<Checkbox
+  aria-label="Select all issues"
+  checked={rows.length > 0 && selected.length === rows.length}
+  indeterminate={selected.length > 0 && selected.length < rows.length}
+  onCheckedChange={(checked) => setSelected(checked ? rows.map((row) => row.id) : [])}
+/>
+```
+
+## Don't
+
+```tsx
+// No name: a screen reader hears only "checkbox, not checked".
+<Checkbox />
+```
+
+```tsx
+// A bare text node beside it is not its label: clicking it does nothing, and it is not the name.
+<Inline gap="8">
+  <Checkbox />
+  <Text>Accept the terms</Text>
+</Inline>
+```
+
+```tsx
+// Shrinks the target below 24px.
+<Checkbox minInlineSize="auto" minBlockSize="auto" />
+```
+
+## Accessibility
+
+- Role `checkbox` with `aria-checked` `"true"`, `"false"` or `"mixed"`; `aria-disabled`, `aria-readonly` and `aria-required` follow the props, and `aria-invalid` the `Field`.
+- The label, description and error reach it through `aria-labelledby` and `aria-describedby`, which Base UI adds after hydration; server HTML has the label's `for`.
+- Checked and mixed are a filled box with a tick or a dash, invalid a thicker border, disabled a dashed one, so no state is color alone. The box border is `borderStrong` (3:1 on every surface).
+- Under forced colors the box keeps its role colors' system mappings: the fill is `LinkText` and the mark `Canvas` when checked, the border `CanvasText`, the focus ring `Highlight`.
+- The target is 24 by 24 CSS px; the focus ring wraps the target, not the box.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Checkbox
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `checked` | `boolean` | no | Whether the checkbox is currently ticked.  To render an uncontrolled checkbox, use the `defaultChecked` prop instead. |
+| `defaultChecked` | `boolean` | no | Whether the checkbox is initially ticked.  To render a controlled checkbox, use the `checked` prop instead. |
+| `disabled` | `boolean` | no | Whether the component should ignore user interaction. |
+| `form` | `string` | no | Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form. |
+| `id` | `string` | no | The id of the input element. |
+| `indeterminate` | `boolean` | no | Whether the checkbox is in a mixed state: neither ticked, nor unticked. |
+| `inputRef` | `Ref<HTMLInputElement>` | no | A ref to access the hidden `<input>` element. |
+| `name` | `string` | no | Identifies the field when a form is submitted. |
+| `onCheckedChange` | `((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element \| undefined; }) => void)` | no | Event handler called when the checkbox is ticked or unticked. |
+| `parent` | `boolean` | no | Whether the checkbox controls a group of child checkboxes.  Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group). |
+| `readOnly` | `boolean` | no | Whether the user should be unable to tick or untick the checkbox. |
+| `required` | `boolean` | no | Whether the user must tick the checkbox before submitting a form. |
+| `uncheckedValue` | `string` | no | The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior. |
+| `value` | `string` | no | The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on". |
+
+Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/Chip.md

@@ -0,0 +1,92 @@
+# Chip
+
+## Purpose
+
+A toggle that filters content or picks an option: "Unread", "Starred", "Medium". A `<button>` with `aria-pressed` on `Clickable`, built on Base UI `Toggle`; `ChipGroup` is a Base UI `ToggleGroup` of chips that share one state. If it changes state when clicked, it's a chip.
+
+## When to use
+
+- Filters over a list: "Unread", "Starred", "Has attachments" (`ChipGroup multiple`).
+- A compact choice of one option among a few: a size, a time range (`ChipGroup`).
+- One on/off option beside a list: a lone `Chip`.
+
+## When not to use
+
+- A status or fact: use `Badge`.
+- A category or topic label on content: use `Tag` (#101).
+- A one-off action: use `Button`.
+- Switching between views of the same content: use `Tabs`.
+- A form field with a required single answer: a radio group (not yet in the library); a `ChipGroup` can be cleared.
+- Picking several values from a list too long to show: use `MultiSelect`.
+
+## Rules
+
+- `pressed` or `defaultPressed`, with `onPressedChange`, for a lone chip. In a `ChipGroup`, give every chip a `value`; the group's `value` or `defaultValue` is the array of pressed values, and `onValueChange` reports it.
+- `ChipGroup` is single selection by default: pressing a chip releases the rest, and pressing the pressed chip releases it, so the group can be empty. For a choice that is never empty, control `value` and ignore an empty array. `multiple` lets any number be pressed.
+- Name every `ChipGroup` with `aria-label` or `aria-labelledby`.
+- `size`: `sm` (24px) or `med` (32px, default). The label and the check are `sm` at both; 24px is the minimum target (WCAG 2.2).
+- Pressed is `accentFg` on `accent` with a check ahead of the label; pressing widens the chip by the check. Released is `fg` on `bg` with a `borderStrong` border.
+- `disabled` renders `aria-disabled` and blocks toggling. A lone disabled chip stays in the tab order; in a group the arrow keys skip it. `ChipGroup` has no `disabled`: disable the chips one by one.
+- Keep the label to a word or two. Chips wrap onto new lines in a group; a label wider than the group wraps inside its chip.
+- Released fill, text color, radius (`full`), padding (the block padding keeps a wrapped label off the border), gap and height are default style props on the button; a consumer's win. The pressed and disabled looks and the border are the chip's own and beat style props. `className`, `style` and `ref` go to it, `className` last. `ChipGroup` is a wrapping flex row `Box` (`gap="8"`), a column when `orientation="vertical"`.
+- The module has no hooks, so a server component can render it; Base UI's parts are the client components.
+
+## Do
+
+```tsx
+<ChipGroup aria-label="Filters" multiple value={filters} onValueChange={setFilters}>
+  <Chip value="unread">Unread</Chip>
+  <Chip value="starred">Starred</Chip>
+  <Chip value="attachments">Attachments</Chip>
+</ChipGroup>
+```
+
+```tsx
+<ChipGroup aria-label="Range" defaultValue={["week"]}>
+  <Chip value="day">Day</Chip>
+  <Chip value="week">Week</Chip>
+  <Chip value="month">Month</Chip>
+</ChipGroup>
+```
+
+## Don't
+
+```tsx
+// A chip is a toggle, not an action: this never changes state. Use Button.
+<Chip onClick={archive}>Archive</Chip>
+```
+
+```tsx
+// An unnamed group: a screen reader announces "group" with nothing to say what it filters.
+<ChipGroup multiple>
+  <Chip value="unread">Unread</Chip>
+</ChipGroup>
+```
+
+## Accessibility
+
+- Each chip is a toggle button: screen readers announce its label with "pressed" or "not pressed". The group is a `group` named by its label.
+- Keyboard: a lone chip is one tab stop; Enter or Space toggles. A `ChipGroup` is one tab stop, landing on the first chip (not the pressed one), then on the last focused chip; Left and Right (Up and Down when vertical) move focus, looping (`loopFocus={false}` stops at the ends); Home and End jump; Enter or Space toggles. Moving focus never changes the selection.
+- The focus ring is Clickable's shared ring on `:focus-visible`.
+- Pressed is never color alone: the check shows. Released text (`fg` on `bg`) and pressed text (`accentFg` on `accent`) pass AA (4.5:1), and the released border (`borderStrong`) passes 3:1, in light and dark mode; the pairs are in `contrastPairs` (ADR 0033).
+- Under forced colors, pressed is `HighlightText` on `Highlight` with the check, released is the page's colors with a `CanvasText` border, and disabled is `GrayText` with a dashed border.
+- Disabled is a dashed border and muted colors, not opacity alone. A pressed chip that is disabled keeps its check but takes the disabled colors.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Chip
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `defaultPressed` | `boolean` | no | Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`. |
+| `disabled` | `boolean` | no |  |
+| `onPressedChange` | `((pressed: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element \| undefined; }) => void)` | no | Callback fired when the pressed state is changed. |
+| `pressed` | `boolean` | no | Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`. |
+| `size` | `"med" \| "sm"` | no |  |
+| `value` | `string` | no | A unique string that identifies the toggle when used inside a toggle group. |
+
+Also accepts the style props (see `manifest.json` `styleProps`).
+
+Also exports `ChipGroup`.

package/dist/docs/Clickable.md

@@ -0,0 +1,82 @@
+# Clickable
+
+## Purpose
+
+The low-level base for everything a user presses: a `<button type="button">` by default, or a link with `as="a"` (or a router's link component). It brings the shared focus ring, a 24 by 24 CSS px minimum target (WCAG 2.2), `disabled` and `busy` states as ARIA attributes, and no look of its own: the button and link chrome is stripped. `Button`, `IconButton` and link components are built on it.
+
+## When to use
+
+- Building a new pressable component: render `Clickable` and pass its look as default style props and its own CSS.
+- A one-off pressable area that no component covers, such as a whole card that opens a detail view.
+
+## When not to use
+
+- An ordinary action: use `Button`, or `IconButton` for an icon alone. They add variants, sizes and loading.
+- A link inside running text: use a plain `<a>` (or the link component); the 24px target and stripped underline are wrong in a sentence, and WCAG exempts inline links.
+- Menus, tabs, checkboxes and other widgets: use the component built on Base UI, which handles the keyboard.
+
+## Rules
+
+- `disabled` renders `aria-disabled="true"`, never the native `disabled`: the control stays focusable and announced, and clicks, Enter and Space are blocked (`preventDefault`, so a link does not navigate, a middle-click does not open it in a new tab, and a submit button does not submit). The context menu can still open a disabled link; keep a destination that must be unreachable off the `href`.
+- `busy` renders `aria-busy="true"` and blocks activation the same way. Pair it with a visible change (a spinner or new label).
+- Set state with `disabled` and `busy`, not `aria-disabled` and `aria-busy`. A raw attribute still blocks the click, since JSX cannot reject hyphenated attributes, but the props are the API.
+- `as="button"` gets `type="button"`; pass `type="submit"` for a form's submit button. A component passed as `as` gets no `type`; it sets its own.
+- Only `onClick` is blocked. Do not put actions in `onPointerDown`, `onMouseDown` or `onKeyDown`.
+- Layout and the target size are default style props (`display="inline-flex"`, centered, `minInlineSize` and `minBlockSize` `"xs"`, 24px). Raise them freely; never set them below `"xs"`.
+- Style props win over the stripped chrome, so `padding`, `color` and `backgroundColor` apply as given.
+- The focus ring is the library's one ring (`outline` in the `focus` color, `Highlight` under forced colors). Do not restyle `:focus-visible` or `outline`.
+- A client component (`'use client'`): it wraps `onClick`. Server components can render it with serializable props.
+
+## Do
+
+```tsx
+<Clickable onClick={open} paddingInline="12" borderRadius="med">
+  <Text as="span">Open</Text>
+</Clickable>
+```
+
+```tsx
+<Clickable as={RouterLink} to="/reports" disabled={!canView}>
+  <Text as="span">Reports</Text>
+</Clickable>
+```
+
+## Don't
+
+```tsx
+// Use `disabled`, the API for this state.
+<Clickable aria-disabled onClick={save} />
+```
+
+```tsx
+// A clickable Box has no focus ring, role or keyboard support.
+<Box onClick={open}>Open</Box>
+```
+
+```tsx
+// Shrinks the target below 24px.
+<Clickable minBlockSize="auto" minInlineSize="auto">
+  ×
+</Clickable>
+```
+
+## Accessibility
+
+- A pressable thing that goes somewhere is a link (`as="a"` with `href`); one that does something is a button. Do not give a button an `href` or a link an action with no destination.
+- An icon-only Clickable needs an accessible name (`aria-label`).
+- `aria-disabled` keeps the control discoverable; say why it is disabled nearby when it is not obvious.
+- The ring passes 3:1 against `bg`, `bgMuted` and `bgRaised` in both modes, and is `Highlight` under forced colors.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Clickable
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `as` | `ElementType` | no |  |
+| `busy` | `boolean` | no |  |
+| `disabled` | `boolean` | no |  |
+
+Also accepts every `<button>` attribute (change the element with `as`) and the style props (see `manifest.json` `styleProps`).