@sableui/react 0.0.0-stage → 0.1.1

package/llms/components/form.md

@@ -0,0 +1,111 @@
+# Form
+
+**Status:** stable
+
+A styled <form> plus Field — the form orchestration layer, built on Base UI Form and Field. Field wires a label, control, helper text, and error message together with correct a11y (htmlFor, aria-labelledby, aria-describedby, aria-invalid, required) automatically, around any Sable control. Validation-library-agnostic: pass each Field an error string, or let Form check native constraints and Field validate functions on submit.
+
+**Keywords:** form, field, label, validation, error, required, settings, input
+
+## Usage
+
+Use Form and Field as the default wrapper for Sable form controls. Field owns the label, description, required state, and error wiring so agents do not hand-roll inconsistent label/input relationships.
+
+### Best practices
+
+- Do: Wrap each control in Field unless a specialized component already owns its label and error semantics.
+- Do: Use Field error for validation messages so aria-invalid and aria-describedby are wired together.
+- Do: For built-in checks, put required / type="email" / minLength on the control (or a validate function on Field) inside a Form: on submit the message appears under the field and the first invalid control is focused. Pass server errors to Form errors, keyed by Field name.
+- Do: Use horizontal Field orientation only for one-line boolean controls like Checkbox, Switch, or Radio.
+- Don't: Use placeholder text as the only label. A visible label should identify the field.
+- Don't: Wrap multiple controls in one Field. Field expects a single child control and wires that one control (an Input or Textarea nested in a wrapper is still found through context).
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Form | yes | The native form element (Base UI Form) with vertical field spacing; validates its Fields on submit. |
+| Field | yes | The label/control/helper/error wrapper for one control. |
+| Control | yes | The single Sable control. Base UI-backed controls register with Field through context; the child is also cloned with the same wiring. |
+| Error | no | Validation copy associated with the control: the error prop when set, otherwise the Base UI validation message (native constraint, validate function, or Form errors). |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| Field | { label?: ReactNode; description?: ReactNode; error?: ReactNode; required?: boolean; disabled?: boolean; name?: string; validate?: (value, formValues) => string \| string[] \| null \| Promise<…>; validationMode?: "onSubmit" \| "onBlur" \| "onChange"; validationDebounceTime?: number; orientation?: "vertical" \| "horizontal"; className?: string; children: ReactElement } | Wraps a single control element (e.g. <Input />) on Base UI Field and wires label (htmlFor + aria-labelledby), helper text and error (aria-describedby), aria-invalid, and required onto it automatically. Base UI-backed controls (Input, Textarea, Select, Combobox, NumberField, Checkbox, Switch, Slider, OtpField…) register through context; the child is also cloned so plain elements keep the same wiring. error renders a destructive message and takes precedence; without it the slot shows Base UI's validation message when the field fails (native constraint, validate, or Form errors). required adds the native attribute plus a visual asterisk (defaults to false). disabled disables the control and dims the label. name keys the field in Form errors / onFormSubmit. validationMode overrides the Form's. orientation defaults to "vertical" (label → control); "horizontal" places control then label inline for a single checkbox / switch / radio — the control centres on the label's first line (it stays there when the label wraps) and description/error sit in the label's column. The root, label, description, error and control carry data-invalid / data-valid, data-touched, data-dirty, data-filled, data-focused and data-disabled for state styling. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Form | { validationMode?: "onSubmit" \| "onBlur" \| "onChange"; errors?: Record<string, string \| string[]>; onFormSubmit?: (values, details) => void; actionsRef?: RefObject<Form.Actions> } + ComponentPropsWithRef<"form"> | — | A <form> laid out as a vertical column with comfortable field spacing (override with className, e.g. gap-4). On submit it validates every Field (native constraints plus Field validate), shows each message under its field, focuses the first invalid control, and only then calls onSubmit. validationMode defaults to "onSubmit" (then live re-validation on change). errors shows external (e.g. server) messages keyed by Field name and clears one when its field is edited. onFormSubmit receives the named Field values and prevents the native submit. A control outside any Field is still checked by the browser before onSubmit runs; pass noValidate to skip that. |
+| validationMode | "onSubmit" \| "onBlur" \| "onChange" | "onSubmit" | When Fields validate. After the first submit, fields re-check as the user edits. A Field's own validationMode wins. |
+| errors | Record<string, string \| string[]> | — | External (e.g. server) messages keyed by Field name, shown under that field. Each clears when its field is edited. |
+| onFormSubmit | (values: Record<string, unknown>, details) => void | — | Called with the named Field values after validation passes; prevents the native submit. |
+| actionsRef | RefObject<{ validate(name?: string): void }> | — | Imperative handle to validate every field, or one by name. |
+
+## Tokens used
+
+`muted-foreground`, `destructive`
+
+## Accessibility
+
+- Field auto-wires label htmlFor ↔ control id, aria-describedby (description + error), and aria-invalid — so the label, helper, and error are all announced for the control.
+- required adds the native `required` attribute (not just a visual asterisk); the asterisk is aria-hidden.
+- Error text is associated via aria-describedby and reinforced by the destructive color, not color alone.
+- Inside Form, a failed submit focuses the first invalid control and shows its message inline instead of a browser bubble.
+
+## Related
+
+- Components: Input, Textarea, Select, Checkbox, Switch, Button
+- Patterns: SettingsPage, AuthPage
+
+## Examples
+
+### Text field
+
+```tsx
+import { Field, Input } from "@sableui/react"
+
+<Field label="Email" description="We'll never share it." required><Input type="email" /></Field>
+```
+
+### Field with an error
+
+```tsx
+import { Field, Input } from "@sableui/react"
+
+<Field label="Password" error="Must be at least 8 characters."><Input type="password" /></Field>
+```
+
+### Validated on submit
+
+```tsx
+import { Button, Field, Form, Input } from "@sableui/react"
+
+<Form onSubmit={handleSubmit}><Field label="Handle" required validate={(value) => String(value).length < 3 ? "At least 3 characters." : null}><Input name="handle" /></Field><Button type="submit">Claim</Button></Form>
+```
+
+### Server errors
+
+```tsx
+import { Field, Form, Input } from "@sableui/react"
+
+<Form errors={serverErrors}><Field label="Email" name="email"><Input type="email" /></Field></Form>
+```
+
+### Form
+
+```tsx
+import { Button, Checkbox, Field, Form, Input } from "@sableui/react"
+
+<Form onSubmit={handleSubmit}><Field label="Name"><Input /></Field><Field label="Subscribe" orientation="horizontal"><Checkbox /></Field><Button type="submit">Save</Button></Form>
+```
+
+### Settings form
+
+```tsx
+import { Button, Field, Form, Input, Select, SelectContent, SelectItem, SelectTrigger } from "@sableui/react"
+
+<Form onSubmit={handleSubmit}><Field label="Display name" description="Shown on your profile."><Input defaultValue="Nova Reed" /></Field><Field label="Visibility"><Select defaultValue="public"><SelectTrigger /><SelectContent><SelectItem value="public">Public</SelectItem><SelectItem value="private">Private</SelectItem></SelectContent></Select></Field><Button type="submit">Save changes</Button></Form>
+```

package/llms/components/gliding-highlight.md

@@ -0,0 +1,84 @@
+# GlidingHighlight
+
+**Status:** stable
+
+One highlight that travels to the active item, instead of each item toggling its own background. Measured, not assumed, so rows of unequal height stay exact.
+
+**Keywords:** highlight, active, selection, indicator, menu, list, glide, slide, thumb, hover
+
+## Usage
+
+Use GlidingHighlight for a set of items where one is active at a time and the pointer or arrow keys move between them — a menu, an option list, a command palette, a segmented control. It replaces per-item `hover:bg-*` with a single element that moves.
+
+### Best practices
+
+- Do: Pass `hovered ?? selected`. The fallback is what makes the pointer leaving a menu return the highlight to the current choice instead of dropping it, so the reader's place is never lost.
+- Do: Reach for it wherever a list is keyboard-navigable. The gain is largest for arrow keys: a background that teleports between rows makes the eye re-find the highlight at every step, where one that moves can be tracked while it travels — which is what keeps a long list readable in motion rather than only at rest.
+- Do: Keep selection semantics on the items — `aria-selected`, `aria-current`, `data-selected`. The highlight is `aria-hidden` decoration over whatever the children already announce.
+- Don't: Do not use it for items that are not mutually exclusive. A travelling highlight says 'one of these, and it is this one'; over a multi-select list it contradicts the checkboxes beside it, and only one of the two can be right.
+- Don't: Do not put non-item chrome among the direct children — a group heading, a separator, a footer hint. Every direct child is a measurable row, so `active` counts them, and the highlight lands one row off from the index the caller is reasoning about. Wrap the items in their own GlidingHighlight, or move the chrome outside.
+- Don't: Do not drive it from a scroll position or a timer. It is an affordance for a set with a discrete active member; a highlight that moves without an item becoming active reads as the interface selecting things on its own.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Container | yes | Positioning context for the highlight. Each direct child is measured as one item. |
+| Highlight | yes | The travelling element. `aria-hidden`, absolutely positioned, invisible until something is active. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| active | number \| null | — | Index of the item the highlight sits behind, or `null` for none. Pass `hovered ?? selected`. |
+| orientation | "vertical" \| "horizontal" | — | Deprecated and ignored: the highlight measures both axes, so a horizontal row needs no flag. |
+| onPointerLeave | PointerEventHandler (and every other div prop) | — | The container is a plain div, so its props pass through. For a hover-following list, reset the hovered index here so the highlight returns to the selected row when the pointer leaves. |
+| highlightClassName | string | — | Class for the travelling highlight itself, for changing its fill or radius. The radius defaults to `sable-frame-inner`, so inside a `sable-frame` container it nests concentrically; in any other rounded, inset container pass `rounded-concentric-<outer>/<inset>` here and on the rows. The container's own `className` styles the list. |
+
+## Tokens used
+
+`accent`
+
+## Motion
+
+- **arrival** · Highlight · _no motion_ — It deliberately does not animate in. Fading it up at rest position — usually row 0 — makes a menu look like it opened with the first item pre-selected, which is a claim about state that is not true. It stays invisible until something is genuinely active.
+- **response** · Container · _no motion_ — The container is not the control; the items are, and they own their own pointer states. This draws the result.
+- **transition** · Highlight · `motion-interactive` — The travel IS the component — a highlight that jumps is just a background toggle with extra machinery. Position, size and opacity ride one declaration so a tall row's height cannot catch up after its position has, which would read as the highlight stretching into place rather than moving.
+- **activity** · Highlight · _no motion_ — Nothing here is indeterminate. A list still loading its options shows a Skeleton in place of the rows.
+
+## Accessibility
+
+- The highlight is `aria-hidden` and carries no semantics — it renders selection, it does not declare it. Keep `aria-selected` / `aria-current` on the items themselves.
+- Pointer-free by construction (`pointer-events-none`), so it can never intercept a click meant for the item beneath it.
+- Works with roving-tabindex and `aria-activedescendant` lists alike: it reads an index the caller already owns, and does not manage focus.
+- Under reduced motion or with MotionProvider off, the highlight moves instantly rather than gliding — the active item is still shown, which is the part that carries meaning.
+
+## Related
+
+- Components: Menu, Select, Combobox, CommandMenu, SideNav
+
+## Examples
+
+### A hoverable menu, returning home on leave
+
+```tsx
+import { GlidingHighlight } from "@sableui/react"
+
+<GlidingHighlight active={hovered ?? selected} className="sable-frame sable-surface sable-surface-popover sable-frame-popover" onPointerLeave={() => setHovered(null)}>{items.map((item, i) => (<button key={item.id} type="button" className="sable-frame-inner px-2 py-1.5 text-start" onPointerEnter={() => setHovered(i)} onClick={() => setSelected(i)}>{item.label}</button>))}</GlidingHighlight>
+```
+
+### Horizontal, as a segmented control
+
+```tsx
+import { GlidingHighlight } from "@sableui/react"
+
+<GlidingHighlight active={tab} className="sable-well flex gap-1 rounded-md p-1" highlightClassName="rounded-concentric-md/1">{tabs.map((t, i) => (<button key={t} type="button" className="rounded-concentric-md/1 px-3 py-1" onClick={() => setTab(i)}>{t}</button>))}</GlidingHighlight>
+```
+
+### Keyboard navigation — the case it exists for
+
+```tsx
+import { GlidingHighlight } from "@sableui/react"
+
+<GlidingHighlight active={cursor} onKeyDown={(e) => { if (e.key === "ArrowDown") setCursor((c) => (c + 1) % rows.length) }}>{rows.map((r) => (<div key={r.id} role="option" aria-selected={false}>{r.label}</div>))}</GlidingHighlight>
+```

package/llms/components/inline-status.md

@@ -0,0 +1,62 @@
+# InlineStatus
+
+**Status:** stable
+
+A borderless single-line status message — a leading semantic icon + one line of text over the canonical tone scale (neutral/info/success/warning/destructive). The non-boxed sibling of Note for inline affirmations, errors, and progress; pass a custom icon (e.g. a Spinner) for a pending row.
+
+**Keywords:** inline status, state, message, availability
+
+## Usage
+
+Use InlineStatus for short state messages placed near the thing they describe.
+
+### Best practices
+
+- Do: Use it beside inputs, rows, actions, or settings that need local status.
+- Do: Keep the message brief and pair color with text.
+- Don't: Do not use InlineStatus for global announcements or page-level alerts.
+- Don't: Do not use tone as the only signal. Colour alone fails for colour-blind users — the leading icon is what carries the meaning, so never hide it.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| tone | "neutral" \| "info" \| "success" \| "warning" \| "destructive" | "neutral" | Severity tone — drives the leading icon (name + color) and the text color. The shared status-tone vocabulary (STATUS_TONES). |
+| size | "sm" \| "md" | "sm" | Text size: sm (text-body-sm) or md (text-body-md). sm is the default for inline placement under a control; md matches surrounding body copy. |
+| icon | ReactNode | — | Override the leading glyph (e.g. a <Spinner />); otherwise the tone selects it. |
+
+## Variants
+
+- **tone**: neutral, info, success, warning, destructive
+- **size**: sm, md
+
+## Tokens used
+
+`tone-info`, `success`, `tone-warning`, `destructive`, `muted-foreground`
+
+## Accessibility
+
+- Color reinforces, never replaces, meaning — the leading icon and the message text carry the status.
+- For a live status (e.g. a form submit result), render it in an aria-live region or pair it with the field's error wiring so the change is announced.
+
+## Related
+
+- Components: StatusDot, Badge, Banner, Note
+
+## Examples
+
+### Tones
+
+```tsx
+import { InlineStatus, Stack } from "@sableui/react"
+
+<Stack gap={1}><InlineStatus tone="success">Top-up confirmed.</InlineStatus><InlineStatus tone="destructive">Insufficient balance.</InlineStatus></Stack>
+```
+
+### Pending (custom icon)
+
+```tsx
+import { InlineStatus, Spinner } from "@sableui/react"
+
+<InlineStatus tone="neutral" icon={<Spinner size="sm" />}>Preparing transaction…</InlineStatus>
+```

package/llms/components/input.md

@@ -0,0 +1,127 @@
+# Input
+
+**Status:** stable
+
+Styled native text input. Soft-square (rounded-sm), card surface, 2px focus ring; aria-invalid raises the destructive error treatment.
+
+**Keywords:** input, text input, field, form, email, search, file, invalid, validation
+
+## Usage
+
+Use Input for short freeform text, search, email, password, file, and native input types. In forms, wrap Input in Field so label, description, required state, and validation messaging stay accessible and consistent.
+
+### Best practices
+
+- Do: Pair every Input with a visible label through Field or an explicit label/htmlFor connection.
+- Do: Use type, inputMode, autoComplete, and placeholder as progressive hints, not as the only label.
+- Do: Set aria-invalid or use Field error copy when validation fails.
+- Do: Keep a focusable field at 16px or larger on mobile. iOS Safari zooms the whole page when a focused input computes under 16px and never zooms back out. Input handles this itself — below the sm breakpoint it renders text-body-lg (17px) and returns to text-body-md at sm and up. Build a custom field the same way: a second paired tier under a max-sm: variant, never a hand-set font-size.
+- Don't: Override an Input's type with a page tier below 16px (text-body-md, text-body-sm, text-label-*) without a >=16px mobile arm — that reintroduces the iOS focus zoom.
+- Don't: Use placeholder text as the label; it disappears once the user types and is not enough context.
+- Don't: Use Input for long body copy. Use Textarea for multi-line content.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Input | yes | The native input element with Sable surface, disabled, focus, and invalid styling. |
+| Label | yes | Usually provided by Field or a separate Label. It gives the input its visible purpose. |
+| Description | no | Optional helper copy connected through aria-describedby when using Field. |
+| Error | no | Validation message paired with aria-invalid and destructive styling. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| size | "md" \| "xs" | "md" | md is the form field. xs is the dense inset field of a tool panel (an inset canvas fill, no outline, tight padding) — the same ladder as Select and Combobox. Use it instead of overriding the height with className. |
+| type | string | "text" | Native input type (text, email, password, search, number, file, …). type="file" themes the native selector button via file: token utilities. |
+| disabled | boolean | false | Dims the control and blocks pointer interaction. |
+| aria-invalid | boolean | — | Surfaces the destructive border + ring. Base UI form fields set this automatically. |
+| ...props | ComponentPropsWithRef<"input"> | — | All native input attributes (placeholder, value, onChange, ref, …) pass through. |
+
+## Variants
+
+- **size**: md, xs
+
+## Tokens used
+
+`input`, `card`, `foreground`, `muted-foreground`, `ring`, `destructive`
+
+## Accessibility
+
+- Renders a native <input> — labels, keyboard, and form semantics come for free.
+- Renders through Base UI's Input (Field.Control): inside a Field it picks up the label, description, error and validity wiring from context, even when nested in a wrapper.
+- Always associate a <label htmlFor> (or wrap) — placeholder text is not a label.
+- Focus-visible ring uses the --ring token at 40% opacity.
+- Set aria-invalid='true' on error so the destructive treatment is conveyed, not color-only.
+
+## Related
+
+- Components: Field, Form, Textarea, SearchInput, NumberField
+- Patterns: SettingsPage, AuthPage
+
+## Examples
+
+### Default
+
+```tsx
+import { Input } from "@sableui/react"
+
+<Input placeholder="Search posts" />
+```
+
+### With a label
+
+```tsx
+import { Field, Input } from "@sableui/react"
+
+<Field label="Email"><Input type="email" placeholder="you@example.com" /></Field>
+```
+
+### Field with helper text
+
+```tsx
+import { Field, Input } from "@sableui/react"
+
+<Field label="Display name" description="Shown on your public profile."><Input placeholder="Nova Reed" /></Field>
+```
+
+### Field error
+
+```tsx
+import { Field, Input } from "@sableui/react"
+
+<Field label="Email" error="Enter a valid email address."><Input type="email" defaultValue="not-an-email" /></Field>
+```
+
+### Search input
+
+```tsx
+import { Field, Input } from "@sableui/react"
+
+<Field label="Search posts"><Input type="search" placeholder="Search by title, creator, or tag" /></Field>
+```
+
+### Invalid
+
+```tsx
+import { Input } from "@sableui/react"
+
+<Input aria-invalid defaultValue="not-an-email" />
+```
+
+### File
+
+```tsx
+import { Input } from "@sableui/react"
+
+<Input type="file" accept="image/*" />
+```
+
+### Disabled
+
+```tsx
+import { Input } from "@sableui/react"
+
+<Input disabled placeholder="Disabled" />
+```

package/llms/components/kbd.md

@@ -0,0 +1,57 @@
+# Kbd
+
+**Status:** stable
+
+A keyboard key indicator. Renders a styled <kbd> key cap in monospace; compose several with a + between to show a shortcut combo. `mod` renders the platform modifier (⌘ or Ctrl).
+
+**Keywords:** keyboard, shortcut, key, kbd
+
+## Usage
+
+Use Kbd to display keyboard keys or shortcuts in help text, menus, and docs.
+
+### Best practices
+
+- Do: Use it only for literal keyboard input such as Cmd, Enter, or Esc.
+- Do: Keep multi-key shortcuts readable by separating individual keys.
+- Don't: Do not use Kbd as a decorative badge or button replacement.
+- Don't: Do not hardcode ⌘ or Ctrl. The modifier differs by platform; use `<Kbd mod />`, which renders ⌘ on macOS/iOS and Ctrl elsewhere, or Windows users read Mac keys.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| mod | boolean | false | Render the platform's shortcut modifier in place of children: ⌘ on macOS and iOS, Ctrl everywhere else. Server-rendered as Ctrl and corrected on hydration. |
+| className | string | — | Merge additional classes onto the key cap. |
+| ...props | ComponentPropsWithRef<"kbd"> | — | All native <kbd> attributes (children, ref, etc.). |
+
+## Tokens used
+
+`border`, `muted`, `muted-foreground`
+
+## Accessibility
+
+- Uses the semantic <kbd> element so assistive tech announces keyboard input.
+- Monospace key text keeps single keys and symbols legible at small sizes.
+
+## Related
+
+- Components: Code, Menu, CommandMenu
+
+## Examples
+
+### Single keys
+
+```tsx
+import { Kbd } from "@sableui/react"
+
+<Kbd>Esc</Kbd>
+```
+
+### Combo
+
+```tsx
+import { Kbd, Row } from "@sableui/react"
+
+<Row gap={1}><Kbd mod /><span>+</span><Kbd>K</Kbd></Row>
+```

package/llms/components/label.md

@@ -0,0 +1,73 @@
+# Label
+
+**Status:** stable
+
+Styled native <label>. Paired label typography via a size step (xs / sm / md / lg, all sentence case) or an uppercase eyebrow (eyebrow), non-selectable, dims when its peer control is disabled. Optional hint adds a dotted-underline tooltip affordance.
+
+**Keywords:** label, form label, control, accessibility
+
+## Usage
+
+Use Label to name a form control and create a clear accessible relationship with that control.
+
+### Best practices
+
+- Do: Use explicit, persistent labels for inputs, selects, textareas, and grouped controls.
+- Do: Place helper text separately so the label stays short and direct.
+- Don't: Do not rely on placeholder text as the only label for a control.
+- Don't: Do not use it as a bare styled span. A Label without htmlFor or a wrapped control looks like a label and does nothing — clicking it will not focus the field, which is the entire point.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| htmlFor | string | — | Associates the label with a control by its id (native <label for>). |
+| size | "xs" \| "sm" \| "md" \| "lg" | "lg" | Paired label typography step, all sentence case. xs is simply the smallest; for an uppercase eyebrow use eyebrow. |
+| eyebrow | boolean | false | Set the label as an eyebrow: the uppercase, letter-spaced text-overline tier (themeable to sentence case). Replaces size. For a kicker above a group, not an ordinary field label. |
+| hint | ReactNode | — | When set, the label gets a dotted-underline affordance and reveals this content in a tooltip on hover/focus. |
+| className | string | — | Merge or override classes via cn(). |
+
+## Variants
+
+- **size**: xs, sm, md, lg
+
+## Tokens used
+
+`foreground`, `muted-foreground`
+
+## Accessibility
+
+- Renders a native <label> — clicking it focuses/activates the associated control.
+- Associate with a control via htmlFor (matching the control's id) or by wrapping the control.
+- In a form, use Field: it renders this Label, wires htmlFor/id, and dims the label when the field is disabled. Hand-wired outside a Field, the label only dims via peer-disabled when the control carries `peer` AND precedes the Label in the DOM (Tailwind peer-* only matches a later sibling).
+- With `hint`, the label becomes focusable and the help text is announced via the tooltip's aria-describedby — so the affordance works for keyboard and screen-reader users, not just hover.
+
+## Related
+
+- Components: Input, Textarea, Fieldset, Form, Field
+
+## Examples
+
+### With control
+
+```tsx
+import { Input, Label, Stack } from "@sableui/react"
+
+<Stack gap={1}><Label htmlFor="name">Display name</Label><Input id="name" /></Stack>
+```
+
+### In a form
+
+```tsx
+import { Field, Input } from "@sableui/react"
+
+<Field label="Display name" disabled><Input /></Field>
+```
+
+### With hint
+
+```tsx
+import { Label } from "@sableui/react"
+
+<Label htmlFor="royalty" hint="A percentage of every resale, paid to you.">Royalty</Label>
+```

package/llms/components/marker.md

@@ -0,0 +1,99 @@
+# Marker
+
+**Status:** stable
+
+A non-message row in a conversation: streaming status, system note, bordered notice, or a labelled rule for date breaks. Quieter than the message tier by design.
+
+**Keywords:** chat status, typing indicator, thinking, streaming, tool call, system message, date separator, date break, conversation divider
+
+## Usage
+
+Everything in a conversation that is not a message. Date breaks, "Carla joined", "Thinking…", "Ran search — 3 results", "Message failed to send". One component because they share one job: annotate the stream without competing with it.
+
+### Best practices
+
+- Do: Use `status` with `icon="spinner" spin` for work in flight, and add `shimmer` while text is actually streaming. The shimmer is scale-aware, so it freezes with the rest of the system under reduced motion.
+- Do: Use `variant="separator"` for date breaks. The label sits between two rules, which reads as a division of the transcript rather than as another thing someone said.
+- Do: Replace a status marker's text as the work progresses — "Thinking…" → "Searching the docs" → "Writing the answer". It is a live region, so each change is announced.
+- Do: Reach for `bordered` only when a note needs containing — an error, an escalation, a retention notice. Boxing routine system events makes a transcript look like a list of alerts.
+- Don't: Do not style a Marker up to message weight. Its whole value is being below that tier; a marker as loud as a message competes with the conversation it is annotating.
+- Don't: Do not leave a status marker mounted after the work finishes. A permanent "Thinking…" is a live region that never resolves, which is worse than no status at all.
+- Don't: Do not use it for a message from a person or an assistant. That is `Message` + `Bubble` — a marker has no author and no side.
+- Don't: Do not set `live` on a `separator` or on a run of `note` markers. Announcing every date break and join event turns the live region into noise and buries the status that mattered.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| variant | "status" \| "note" \| "bordered" \| "separator" | "status" | `status` for live activity, `note` for a system event, `bordered` for a note that needs containing, `separator` for a labelled rule. |
+| icon | string | — | Semantic icon name shown before the label, resolved through IconProvider. |
+| spin | boolean | false | Spin the icon — pair with `icon="spinner"` for work in flight. |
+| shimmer | boolean | false | Sweep the label while something is streaming, via the scale-aware `motion-text-shimmer` recipe (freezes under reduced motion). |
+| live | boolean | true for `status`, false otherwise | Announce the label to assistive tech as it changes. On for `status`, because a screen-reader user otherwise gets silence for the whole generation and no way to tell a slow answer from a dead one. |
+| ...div props | ComponentPropsWithRef<"div"> | — | Spread onto the row. |
+
+## Variants
+
+- **variant**: status, note, bordered, separator
+
+## Tokens used
+
+`muted-foreground`, `muted`, `border`, `foreground`
+
+## Accessibility
+
+- `status` markers render as `role="status"` with `aria-live="polite"`, so a change of activity is announced without interrupting whatever is being read.
+- The other variants are silent by default and can opt in with `live` — announcing every date break and join event would bury the status that mattered.
+- The separator's rules are `aria-hidden`, leaving only the label in the accessibility tree; the shimmer is decoration over readable text, not a replacement for it.
+- `motion-text-shimmer` keeps the label opaque through every frame — the gradient runs muted-foreground → foreground rather than fading to transparent, so the text never becomes unreadable mid-animation, and `--motion-scale` freezes it entirely under reduced motion.
+
+## Related
+
+- Components: Message, Bubble, MessageScroller, InlineStatus, Separator
+
+## Examples
+
+### Streaming status
+
+```tsx
+import { Marker } from "@sableui/react"
+
+<Marker icon="spinner" spin shimmer>Thinking…</Marker>
+```
+
+### Date break
+
+```tsx
+import { Marker } from "@sableui/react"
+
+<Marker variant="separator">Yesterday</Marker>
+```
+
+### System note
+
+```tsx
+import { Marker } from "@sableui/react"
+
+<Marker variant="note" icon="user">Carla joined the conversation</Marker>
+```
+
+### A notice that needs containing
+
+```tsx
+import { Marker } from "@sableui/react"
+
+<Marker variant="bordered" icon="warning">This conversation will be archived in 7 days.</Marker>
+```
+
+### In a transcript
+
+```tsx
+import { Bubble, Marker, Message, MessageScroller } from "@sableui/react"
+
+<MessageScroller className="h-96">
+	<Marker variant="separator">Today</Marker>
+	<Message messageId="m1"><Bubble>Can you summarise the release?</Bubble></Message>
+	<Marker variant="note" icon="sparkles">Ran changelog — 12 entries</Marker>
+	<Marker icon="spinner" spin shimmer>Writing the answer</Marker>
+</MessageScroller>
+```