@flood-md/agent 0.2.9 → 0.2.11

package/dist/materials/component-accordion.md

@@ -0,0 +1,42 @@
+# Accordion
+
+Related disclosure sections with optional single or multiple expansion.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Accordion } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Accordion label="Questions" items={[{value:"install",title:"How do I install Flood?",content:"Install the packages and import the stylesheet."}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Headings contain native disclosure buttons. Set headingLevel for the surrounding document.
+- Enter/Space toggle. Tab visits available triggers and open panel contents. ArrowUp/Down and Home/End move among enabled top-level triggers without opening panels.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly AccordionItem[]` | `Required` |
+| `expansionMode` | `"single" \| "multiple"` | `"single"` |
+| `value` | `readonly string[]` | `—` |
+| `defaultValue` | `readonly string[]` | `[]` |
+| `onValueChange` | `(value: string[]) => void` | `—` |
+| `disabled` | `boolean` | `false` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-alert-dialog.md

@@ -0,0 +1,46 @@
+# AlertDialog
+
+A focused confirmation with explicit cancel and continue actions.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, AlertDialog, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AlertDialog title="Archive this project?" description="You can restore it from the archive." confirmLabel="Archive project" trigger={props => <Button {...props}>Archive project</Button>} onConfirm={() => { /* Archive in the host application. */ }} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses the original Flood Dialog modal layer with role=alertdialog, a required message and initial focus on Cancel. Tab stays inside the modal; Escape cancels and restores trigger focus. Outside clicks do not dismiss it. There is no extra close action competing with the explicit Cancel button.
+- onConfirm is a host callback followed by a close request. onCancel handles the Cancel button and Escape, not confirmation. Use open/onOpenChange for host-controlled state and confirmDisabled to prevent confirmation while unavailable. Async work/errors belong to the host; callbacks are not awaited.
+- Translate title, description, confirmLabel and cancelLabel. Use ordinary Dialog for forms and exploratory content. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `description` | `string` | `Required` |
+| `confirmLabel` | `string` | `"Continue"` |
+| `cancelLabel` | `string` | `"Cancel"` |
+| `confirmDisabled` | `boolean` | `false` |
+| `onConfirm` | `() => void` | `Required` |
+| `onCancel` | `() => void` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">, "children" \| "role" \| "description" \| "closeLabel" \| "closeOnOutsideClick" \| "initialFocusRef">` | `Forwarded` |

package/dist/materials/component-alert.md

@@ -0,0 +1,41 @@
+# Alert
+
+An inline message with a quiet boundary and explicit announcement priority.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Alert } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Alert tone="warning" title="Storage is almost full">
+        Free some space before your next upload.
+      </Alert>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- announcement defaults off: a static message does not automatically interrupt a screen reader. Polite uses role=status; assertive uses role=alert.
+- Use assertive for newly inserted urgent messages, and verify with actual assistive technology. No focus movement, timeout or automatic dismissal is implemented.
+- Title is optional. Icons are original decorative glyphs; pass icon={null} to omit or supply noninteractive artwork. Meaning must remain in the text.
+- Native div props and ref target the message root. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `—` |
+| `tone` | `"neutral" \| "error" \| "warning" \| "success" \| "info"` | `"info"` |
+| `icon` | `ReactNode` | `—` |
+| `announcement` | `"off" \| "polite" \| "assertive"` | `"off"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "title" \| "role" \| "aria-live">` | `Forwarded` |

package/dist/materials/component-app-shell.md

@@ -0,0 +1,47 @@
+# AppShell
+
+A workspace layout with optional navigation, top bar and footer, plus a keyboard skip target.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, AppShell, AppTopBar, PageHeader, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AppShell topBar={<AppTopBar start={<Text>Workspace</Text>} />}><PageHeader title="Projects" /></AppShell>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Content scrolling keeps navigation, top bar and footer outside the work scrollport. Use scroll="page" for a document that scrolls as a whole.
+- Supply Sidebar for docked navigation. Set navigationDrawer with a shell-width threshold and Drawer content to swap automatically. Share accepted route and branch state between the two presentations.
+- Use mainAs="section" only when embedding a shell inside an existing main landmark.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `navigation` | `ReactNode` | `—` |
+| `navigationSide` | `"start" \| "end"` | `"start"` |
+| `navigationDrawer` | `AppShellNavigationDrawer` | `—` |
+| `topBar` | `ReactNode \| (navigationTrigger: ReactNode) => ReactNode` | `—` |
+| `footer` | `ReactNode` | `—` |
+| `scroll` | `"content" \| "page"` | `"content"` |
+| `mainId` | `string` | `—` |
+| `mainAs` | `"main" \| "section"` | `"main"` |
+| `mainLabel` | `string` | `—` |
+| `mainRef` | `Ref<HTMLElement>` | `—` |
+| `scrollLabel` | `string` | `—` |
+| `scrollOrientation` | `ScrollAreaProps["orientation"]` | `—` |
+| `skipLabel` | `string` | `—` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

package/dist/materials/component-app-top-bar.md

@@ -0,0 +1,36 @@
+# AppTopBar
+
+Application context and global actions in two independent, wrapping slots.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, AppTopBar, Text, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AppTopBar start={<Text>Workspace</Text>} end={<Button size="sm">Search</Button>} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use in AppShell or in a host-owned layout. Use PageHeader for the current page's title and actions.
+- The start and end groups wrap on narrow hosts without changing keyboard order. Use bordered only where the toolbar needs a visible boundary.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `start` | `ReactNode` | `—` |
+| `end` | `ReactNode` | `—` |
+| `bordered` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children">` | `Forwarded` |

package/dist/materials/component-aspect-ratio.md

@@ -0,0 +1,36 @@
+# AspectRatio
+
+Reserved media proportions that respond to their containing width.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, AspectRatio, Image } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AspectRatio ratio={16 / 9}><Image src="/flood-mark.png" alt="Flood logo" fit="contain" /></AspectRatio>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- ratio must be finite and positive. The root reserves media geometry before image loading.
+- Direct img/video/iframe children fill the reserved box. Content can overflow; the component does not clip focus, menus or arbitrarily tall text.
+- Host media owns alt, captions, controls and loading. Native props/ref target the outer div.
+- Available in 0.2.4; use matching installed declarations.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `ratio` | `number` | `16 / 9` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

package/dist/materials/component-autocomplete.md

@@ -0,0 +1,54 @@
+# Autocomplete
+
+A free text field with optional suggestions; accepts values outside the list.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Field, Autocomplete } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Team">{control => <Autocomplete {...control} name="team" options={[{value:"design",label:"Design",group:"Product"},{value:"engineering",label:"Engineering",group:"Product"},{value:"operations",label:"Operations",group:"Business"}]} />}</Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The submitted value is text, not an option ID. Use Combobox for fixed choices.
+- Manual suggestions use controlled value and optionsQuery; stale results cannot be chosen. Network ownership remains with the host.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `options` | `readonly ComboboxOption[]` | `Required` |
+| `clearable` | `boolean` | `—` |
+| `emptyMessage` | `string` | `—` |
+| `listLabel` | `string` | `—` |
+| `toggleLabel` | `string` | `—` |
+| `clearLabel` | `string` | `—` |
+| `invalidSelectionMessage` | `string` | `—` |
+| `filtering` | `"local" \| "manual"` | `—` |
+| `optionsQuery` | `string` | `—` |
+| `loadState` | `"ready" \| "loading" \| "error"` | `—` |
+| `loadingMessage` | `string` | `—` |
+| `errorMessage` | `string` | `—` |
+| `onRetry` | `() => void` | `—` |
+| `retryLabel` | `string` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `""` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `onOptionSelect` | `(option: ComboboxOption) => void` | `—` |
+| `Native HTML props` | `Omit<Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "children">, "query" \| "onQueryChange" \| "selectedOptions" \| "value" \| "defaultValue" \| "onValueChange">` | `Forwarded` |

package/dist/materials/component-avatar-group.md

@@ -0,0 +1,39 @@
+# AvatarGroup
+
+A compact collection of avatars with an accessible overflow count.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, AvatarGroup } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AvatarGroup label="Project collaborators" items={[{id:"alex",name:"Alex Morgan"},{id:"sam",name:"Sam Lee"},{id:"june",name:"June Park"}]} max={2} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The native list composes Flood Avatar. IDs and names must be nonempty and unique IDs remain stable. max is a positive integer; the default shows four people.
+- Overflow is a static count, not a hidden interactive menu. Translate overflowLabel when needed; visible avatars retain their individual accessible names. Size follows Avatar. Intentional overlap never applies to interactive targets.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `items` | `readonly AvatarGroupItem[]` | `Required` |
+| `label` | `string` | `Required` |
+| `max` | `number` | `4` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `overflowLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLUListElement>, "children">` | `Forwarded` |

package/dist/materials/component-avatar.md

@@ -0,0 +1,40 @@
+# Avatar
+
+A stable identity image with initials or an explicit text fallback.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Avatar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Avatar name="Alex Morgan" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Name supplies the accessible image name; decorative suppresses duplicate naming next to an equivalent visible name.
+- Fallback remains visible until the image loads and after a load error. Changing src starts a fresh load lifecycle.
+- Native span props and ref target the root. Size and shape do not change during loading. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `name` | `string` | `Required` |
+| `src` | `string` | `—` |
+| `fallback` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `shape` | `"circle" \| "rounded"` | `"circle"` |
+| `decorative` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "role" \| "aria-label" \| "aria-hidden">` | `Forwarded` |

package/dist/materials/component-badge.md

@@ -0,0 +1,37 @@
+# Badge
+
+A compact, noninteractive label for status and metadata.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Badge } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Badge tone="success">Active</Badge>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use text to communicate status; color is supplementary.
+- Tone, size and visual variant are independent. This is not a selectable or removable chip.
+- Available in 0.2.4. Use FloodRoot for the neutral dark recipe.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `tone` | `"neutral" \| "accent" \| "error" \| "warning" \| "success" \| "info"` | `"neutral"` |
+| `variant` | `"subtle" \| "outline"` | `"subtle"` |
+| `Native HTML props` | `HTMLAttributes<HTMLSpanElement>` | `Forwarded` |

package/dist/materials/component-blockquote.md

@@ -0,0 +1,35 @@
+# Blockquote
+
+A quoted passage with an optional compact attribution.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Blockquote } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Blockquote attribution="The Flood team">Good interfaces make room for what matters.</Blockquote>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses native blockquote; cite remains a source URL, while attribution is visible host-authored credit. Rich quote content and attribution are supported.
+- The logical leading rule follows RTL. Supply quotation punctuation as part of your actual content; the component does not invent a quotation or source.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `attribution` | `ReactNode` | `—` |
+| `Native HTML props` | `BlockquoteHTMLAttributes<HTMLQuoteElement>` | `Forwarded` |

package/dist/materials/component-breadcrumb.md

@@ -0,0 +1,36 @@
+# Breadcrumb
+
+A wrapping hierarchy of native links with an explicit current page.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Breadcrumb } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Breadcrumb items={[{label:"Workspace",href:"/"},{label:"Projects",href:"/projects"},{label:"Flood"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The last item is current, with or without an href. Separators are decorative and not focusable.
+- Links keep browser navigation semantics. The host owns actual routes and client routing.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `items` | `readonly BreadcrumbItem[]` | `Required` |
+| `label` | `string` | `"Breadcrumb"` |
+| `separator` | `string` | `"/"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children">` | `Forwarded` |

package/dist/materials/component-bulk-action-bar.md

@@ -0,0 +1,52 @@
+# BulkActionBar
+
+A single-row selection command capsule with adaptive overflow.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, BulkActionBar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <BulkActionBar label="Selected projects" selectionCount={2}
+        items={[{id:"archive",label:"Archive",priority:10},{id:"pause",label:"Pause"},{id:"activate",label:"Set active"}]}
+        onAction={(id) => console.log(id)} onClear={() => console.log("clear")} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The default is a pill-shaped single row with at most two visible commands. maxVisibleActions accepts 1, 2 or 3; available space can reduce that number further.
+- Lower-priority commands move to More. selectionLabel, clearLabel and moreLabel support localized content; selectionCount=0 renders nothing.
+- pending disables commands and clearing. The host owns selected IDs, accepted updates, confirmation and focus after removal.
+- The component is inline by default. A floating host supplies bounded viewport positioning, safe-area spacing and scroll clearance. Use a stable width so adaptive measurement does not depend on the currently visible commands.
+- counter accepts label (default), number or none. Visible counters reserve a stable width across digit changes; counterWidth adapts that reservation to a localized label. Numeric mode retains the complete accessible selectionLabel. Hidden mode removes the slot.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `selectionCount` | `number` | `Required` |
+| `selectionLabel` | `string` | `—` |
+| `counter` | `"label" \| "number" \| "none"` | `—` |
+| `counterWidth` | `CSSProperties["inlineSize"]` | `—` |
+| `items` | `readonly OverflowAction[]` | `Required` |
+| `onAction` | `(id: string) => void` | `—` |
+| `onClear` | `() => void` | `Required` |
+| `clearLabel` | `string` | `—` |
+| `moreLabel` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `maxVisibleActions` | `1 \| 2 \| 3` | `—` |
+| `disabled` | `boolean` | `—` |
+| `pending` | `boolean` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onAction">` | `Forwarded` |

package/dist/materials/component-button-group.md

@@ -0,0 +1,39 @@
+# ButtonGroup
+
+Connected actions with shared edges and ordinary keyboard focus.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, ButtonGroup, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ButtonGroup label="Editing actions">
+        <Button variant="subtle">Undo</Button>
+        <Button variant="subtle">Redo</Button>
+      </ButtonGroup>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use direct Button/IconButton children with compatible sizes. The group owns connected radii and single separators; actions keep their props and handlers.
+- label names the group. Tab follows normal button order; this is not a toolbar, menu or selection group.
+- Horizontal is default; vertical stacks actions. Content can wrap within a button. Conditional/hidden actions preserve the visible end corners. No clipping masks focus.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | `Forwarded` |

package/dist/materials/component-button.md

@@ -0,0 +1,44 @@
+# Button
+
+Native actions with a clear prominence, size and interaction state.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Inline, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Inline gap="2">
+        <Button>Save changes</Button>
+        <Button variant="subtle">Cancel</Button>
+        <Button loading>Saving</Button>
+      </Inline>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Button defaults to type="button". Set submit or reset deliberately inside forms.
+- Loading disables activation and sets aria-busy. The host owns completion announcements.
+- Prefer subtle for standalone secondary actions; ghost belongs in a clear parent context.
+- Buttons use content width, including inside Stack. Opt into a full-width action with style={{ inlineSize: "100%" }} only when the composition calls for it.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"solid"` |
+| `tone` | `"default" \| "danger"` | `"default"` |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
+| `loading` | `boolean` | `false` |
+| `type` | `Inherited native HTML prop` | `"button"` |
+| `Native HTML props` | `ButtonHTMLAttributes<HTMLButtonElement>` | `Forwarded` |