props)): - `children?: ReactNode`. Kbd elements, modifiers first. - `className?: string`. Merged last. ### Label - Level: Atom - Category: Inputs - Status: Stable - Import: `@oration/canon/components/label` - Exports: `Label` - Docs: /design/components/label Label is the visible name of a form control: a native `` in Control type (14px, weight 500) that points at its control with `htmlFor`, or wraps it. Clicking it focuses or toggles the control, and screen readers announce it as the control's name. Inside a form, reach for Field, whose FieldLabel is this Label with field spacing and states. The common mistake is a label that isn't linked: text that looks like a label but names nothing. When to use: - To name an Input, Textarea, Select or Combobox, above it, with `htmlFor` set to the control's `id`. - To wrap a Checkbox or Radio with its text, so the whole line is one click target. - Beside a Switch whose name is longer than the Switch's own `label` prop should carry, with `htmlFor`. - As the named element a Slider or custom control points at with `aria-labelledby`. - In dense sheets and settings rows at 13px, passing `text-[13px]` through `className`. When not to use: - Inside a form layout with descriptions and errors. FieldLabel adds the spacing, the invalid color and the disabled dimming. Use /design/components/field instead. - To name a group of radios or checkboxes. A group is named by a fieldset legend, not by a label. Use /design/components/radio-group instead. - For a section heading above several fields. That is a Title, set as a heading. Use /design/components/section-header instead. - For a value on a record, such as a stage or a tier. Use /design/components/tag instead. - For a read-only key and value pair in a record rail. Use /design/components/meta instead. Rules: - Every field has a label: Every control carries a name, visible or screen-reader only. A placeholder is not a label: it disappears as soon as someone types and is read inconsistently by assistive tech. - Mark the optional, not the required: Most fields in Oration are required, so mark the exceptions with a muted (optional) after the label. No red asterisks. Anatomy: - Label text: Control type: 14px at weight 500, `leading-none`, sentence case. The color is inherited, so it reads as Graphite Ink on the plane. - Optional marker: A muted (optional) in weight 400 after the text, for the few fields that can stay empty. - Wrapped control: When the label wraps a Checkbox or Radio, the label is a flex row with an 8px gap, so text and control align on their centers. - Linked control: With `htmlFor`, the control sits outside the label. Clicking the text focuses the input or toggles the checkbox. States: - Rest: Inherited ink at weight 500. Labels have no hover style. - Disabled: Drops to 50% opacity and stops pointer events when an ancestor with the `group` class carries `data-disabled="true"`, or when a preceding `peer` control is `:disabled`. FieldLabel does this for you inside a disabled Field. - Invalid: Label itself stays ink. Inside a Field with `data-invalid`, the field turns its text Signal Red, and the error message below carries the reason. Behavior: - A native ``: clicking it moves focus to the linked input or textarea, and clicks the linked checkbox, radio or switch. - Base UI's Checkbox, Radio and Switch keep a hidden input with the `id` you pass, so `` links to them the same way it links to an Input. - `select-none` stops a double-click on the label from selecting its text, since the click already goes to the control. - `leading-none` keeps a one-line label tight to its control. A label that wraps needs `leading-snug`, which FieldLabel sets. Do and don't: - Do: Put a visible label above the field and use the placeholder for an example value. - Don't: Use the placeholder as the only label. It vanishes on the first keystroke. - Do: Wrap the checkbox and its text in one Label, so the whole line toggles. - Don't: Set the text in a plain span beside the checkbox. It looks the same and does nothing when clicked. - Do: Mark the one optional field with a muted (optional). - Don't: Put a red asterisk on every required field. It adds noise to nearly every label on the page. Content: - Name the thing, not the action: Remit-to email, not Enter your remit-to email. - Sentence case, no trailing colon, no punctuation. - Keep it to one to four words. Put the explanation in a description below the field, not in the label. - Use the words the supplier or the ERP uses: Tax ID (EIN), PO number, Payment terms. - For a checkbox, write the label as the true statement the box turns on: Email remittance advice to the supplier. Accessibility: - `htmlFor` must match the control's `id`. Generate it with `React.useId()` so two copies of the form on one page don't collide. - A label gives the control its accessible name; don't also set an `aria-label` that says something different. - When a visible label would repeat a nearby heading, keep the name and hide it with `sr-only` rather than dropping it. - Name a radio or checkbox group with a fieldset and legend, and each option with its own label. - Controls that aren't labelable elements, such as the Slider's thumbs, take the label's `id` through `aria-labelledby`. Known gaps (follow the system, not the gap): - Label's own disabled styles rarely fire. `peer-disabled:` needs a native `:disabled` control before the label with the `peer` class, and Base UI's Checkbox, Radio and Switch are spans that are never `:disabled`. `group-data-[disabled=true]:` needs an unnamed `group` ancestor, and Field uses the named `group/field`. Dim the label yourself, or use FieldLabel in a disabled Field. - Product call sites pass `text-13` through `className`. Label merges with the `cn` package, which treats `text-13` as a color, so `text-sm` is kept alongside it and the size depends on stylesheet order. Use `text-[13px]`. - `leading-none` gives a wrapping label zero leading, so a two-line label collides with itself. Add `leading-snug` or use FieldLabel. API `Label` (extends `` (`React.ComponentProps<"label">`)): - `htmlFor?: string`. The `id` of the control it names. Omit it when the label wraps the control. - `className?: string`. Merged after the base classes. Use `text-[13px]`, not `text-13`, to step down to dense type. - `children?: React.ReactNode`. The label text, and the control itself when wrapping. ### Input - Level: Atom - Category: Inputs - Status: Stable - Import: `@oration/canon/components/input` - Exports: `Input` - Docs: /design/components/input Input is the single-line text field: 32px tall, 10px corners, a 1px Field Stroke, a transparent fill and an indigo caret. It holds names, emails, amounts, IDs and search terms across every form and sheet in Oration, and it is built on Base UI Input, so it joins Base UI Field validation when it sits in one. Width is set by its container. The thing people get wrong is naming: an Input always has a Label, and the placeholder only ever shows an example. When to use: - For short free text a person types: a supplier's legal name, a remit-to email, an invoice number. - For numbers and amounts that are typed rather than stepped, with `inputMode="decimal"` and `tabular-nums`. - For machine strings such as a vendor ID, an EIN or a routing number, in `font-mono`. - Inside a Field, with a label above, an optional description and an inline error. - For a file picker in a plain form, with `type="file"`, when a Dropzone would be too much. When not to use: - For more than one line of text, such as a note to a supplier. Use /design/components/textarea instead. - For a search box with an icon and a clear button. Use /design/components/search-field instead. - For a prefix or suffix inside the field, such as $ or @cedarline.io. Use /design/components/input-group instead. - For a secret such as an API key or a password. Use /design/components/password-input instead. - For choosing from a known list of values. Use /design/components/select instead. - For a verification code typed one character at a time. Use /design/components/input-otp instead. Rules: - Inputs use 16px below 768px: The field is `text-base` (16px) on small screens and `text-sm` (14px) from 768px. Mobile Safari zooms the page when a focused field is under 16px, so never pin a smaller size below `md`. - Every field has a label: A visible Label above, or an `sr-only` one when the context names the field. A placeholder is an example value, never the name. Anatomy: - Container: 32px tall, full width, 10px corners, a 1px Field Stroke border and a transparent fill (the input color at 30% in dark). - Value: 16px below 768px and 14px above, with 10px side padding. The caret is Quiet Indigo. - Placeholder: Slate Meta, for an example value such as ap@northwindfreight.com. Gone once the field has a value. - Focus ring: On keyboard and pointer focus: an indigo border and a 3px Focus Indigo ring at 50%. States: - Rest: Field Stroke border on a transparent fill. No hover style. - Placeholder: Slate Meta example text until the first keystroke. - Focus: Indigo border and a 3px ring at 50%. `focus-visible` matches every focus on a text field, pointer included. - Invalid: With `aria-invalid`, a Signal Red border and a 3px red ring at 20% (50% border and 40% ring in dark). The ring stays until the value is fixed. - Disabled: 50% opacity on a faint input-tinted fill, no pointer events. The value is not submitted with the form. - Read-only: `readOnly` keeps the value selectable and submitted but draws exactly like rest. See known gaps. Behavior: - Renders a native `` through Base UI Input. Inside a Base UI Field it reports dirty, touched and validity to the field; on its own it is a plain input. - Width comes from the container: the field is `w-full` and `min-w-0`, so size it with the column or a `max-w-*` on its wrapper. - Border and fill transition over 150ms. The ring is a box-shadow and appears at once. - `type="file"` styles the browser's file button as 14px medium text on no fill, so the field reads like the others. - Pick the keyboard with `type` and `inputMode` (`email`, `decimal`, `numeric`, `tel`), and help autofill with `autoComplete`. Do and don't: - Do: Size the field to the value it holds: a ZIP code gets a short field, an email a long one. - Don't: Stretch every field to the full width of the form. A 5-digit ZIP in a 40rem field reads as a long answer. - Do: Keep the field at 16px below 768px and step down with `md:text-[13px]` in dense layouts. - Don't: Pin the field to 13px at every width. Mobile Safari zooms the page on focus. - Do: Explain a disabled field beside it, so people know what would unlock it. - Don't: Disable a field with no reason. It looks broken, and screen readers skip it entirely. Content: - Placeholders show the format, not the instruction: ap@northwindfreight.com, 12-3456789. Never Enter email. - Put rules the value must follow (format, length, units) in the description, where they stay visible while typing. - Errors say what to do: Enter a 9-digit EIN, like 12-3456789. Not Invalid input. - Units and currency go beside the value, in an Input group, not inside the placeholder. Accessibility: - Name every Input with a Label linked by `htmlFor`, or an `sr-only` label. `aria-label` is the last resort. - Set `aria-invalid` and point `aria-describedby` at the error message, so the reason is announced with the field. - On submit, move focus to the first invalid field. - Use `autoComplete` tokens (`email`, `organization`, `postal-code`) so browsers and password managers can fill the form. - Disabled inputs leave the tab order. If people need to read or copy the value, use `readOnly` instead. - The 16px size below 768px also prevents the zoom that disorients low-vision users on phones. - Tab: Moves focus into the field; the caret lands at the end. - Enter: Submits the surrounding form. - Escape: Clears the value when `type="search"`. Known gaps (follow the system, not the gap): - `readOnly` has no style of its own, so a read-only field is indistinguishable from an editable one until someone tries to type. - The props are typed as `React.ComponentProps<"input">`, so Base UI's `onValueChange` works at runtime but isn't in the type. Use `onChange`. - `disabled:cursor-not-allowed` never shows, because `disabled:pointer-events-none` stops the pointer from reaching the field. API `Input` (extends Base UI `Input` (typed as `React.ComponentProps<"input">`)): - `type?: React.HTMLInputTypeAttribute` = "text". The native input type. `email`, `url`, `tel`, `search`, `number`, `file` and `date` all take the same box. - `value?: string | number | readonly string[]`. Controlled value. Pair with `onChange`. - `defaultValue?: string | number | readonly string[]`. Initial value when uncontrolled. - `onChange?: React.ChangeEventHandler`. Fires on every edit. - `placeholder?: string`. An example value in Slate Meta. Not a label. - `aria-invalid?: boolean`. Draws the red border and ring. Set it with the error message. - `disabled?: boolean` = false. Dims to 50%, blocks input and leaves the value out of the form. - `readOnly?: boolean` = false. Keeps the value focusable, selectable and submitted, but not editable. - `className?: string`. Merged after the base classes. Override the size with `md:text-[13px]` so the 16px mobile size stays. ### Textarea - Level: Atom - Category: Inputs - Status: Stable - Import: `@oration/canon/components/textarea` - Exports: `Textarea` - Docs: /design/components/textarea Textarea is the multi-line text field. It shares Input's stroke, corners, focus ring and invalid state, starts at 64px and grows with its content through `field-sizing: content`. In Oration it holds notes to suppliers, dispute reasons, macro bodies and agent instructions. What people get wrong is the ceiling: without a `max-h-*` a long paste pushes the rest of the form off screen. When to use: - For free text that can run past one line: a note on a remittance, a reason for rejecting an invoice. - For a message template or an agent instruction that people edit in place. - When the length limit matters, paired with a live character count. - Inside a Field, with a label above and a description or error below. When not to use: - For a short value such as a name, an email or an ID. Use /design/components/input instead. - For a composer with send, attachments, mentions and slash commands. Use /design/components/prompt-bar instead. - For a template with variables that need to be inserted and highlighted. Use /design/components/prompt-editor instead. - For editing a single value on the record in place, where the text becomes a field on click. Use /design/components/editable-text instead. - For a list of short values such as email addresses or keywords. Use /design/components/tag-input instead. Rules: - Grow, then scroll: Let the field grow with what people type, and cap it with `max-h-*` so it scrolls inside once it passes a comfortable height. The form's footer and buttons should never be pushed off screen. - Every field has a label: A visible Label above, or an `sr-only` one. The placeholder shows an example of a good answer, never the name of the field. Anatomy: - Container: Full width, at least 64px tall, 10px corners, a 1px Field Stroke and a transparent fill (the input color at 30% in dark). - Text: 16px below 768px and 14px above, with 10px side and 8px top padding, and an indigo caret. - Placeholder: Slate Meta, for an example answer. - Resize handle: The browser's own corner grip. It resizes in both directions unless you set `resize-y` or `resize-none`. States: - Rest: Field Stroke border on a transparent fill. No hover style. - Focus: Indigo border and a 3px Focus Indigo ring at 50%. - Growing: Height follows the content from 64px up to any `max-h-*` you set, then the field scrolls. - Invalid: With `aria-invalid`, a Signal Red border and a 3px red ring at 20% (50% and 40% in dark). - Disabled: 50% opacity on a faint input-tinted fill with a not-allowed cursor. The value is not submitted. - Read-only: Draws like rest. See known gaps. Behavior: - A native `

`, not a Base UI component, so it doesn't report dirty or touched state to a Base UI Field.
- `field-sizing: content` sizes the box to its text. Browsers without it keep the height of `rows` (two lines by default, lifted to 64px by `min-h-16`) and scroll.
- Set `min-h-*` to start taller, such as `min-h-28` for a reason field, and `max-h-*` to stop growing.
- Enter inserts a new line; it never submits the form.
- Border and fill transition over 150ms; the focus ring appears at once.

Do and don't:
- Do: Cap the height with `max-h-*` so a long paste scrolls inside the field.
- Don't: Let the field grow without limit, pushing the footer and its buttons off screen.
- Do: Show a live count when a hard limit exists, such as the 80 characters an ACH addenda carries.
- Don't: Cut the text off with `maxLength` and no count. People paste, lose the end and never know.

Content:
- Label the field with the thing it holds: Note to supplier, Reason, Message.
- Use the placeholder for a short example of a good answer: Duplicate of INV-20417, already paid on Sep 18.
- Put who sees the text in the description: Northwind Freight sees this on the remittance advice.
- Counts read 42 of 80 characters, in tabular figures, and turn Signal Red only past the limit.

Accessibility:
- Name the field with a linked Label, and link the description, the count and any error with `aria-describedby`.
- Don't announce every keystroke of a character count. Put `aria-live="polite"` on a message that only changes near the limit, or leave the count as a description read on focus.
- Set `aria-invalid` with the error, and move focus to the field on a failed submit.
- Keep 16px below 768px so phones don't zoom on focus; override only the `md:` size in dense layouts.
- Tab: Moves focus into and out of the field.
- Enter: Inserts a new line.
- Shift + Tab: Moves focus back without inserting anything.

Known gaps (follow the system, not the gap):
- There is no default `max-h-*`, so an unbounded paste grows the field until the page scrolls. Every call site has to remember the cap.
- The browser's resize grip is left on in both directions; a horizontal drag can push the field past its column. Set `resize-y` or `resize-none`.
- `readOnly` has no style of its own, the same gap as Input.
- Unlike Input, it is a plain `<textarea>` rather than Base UI's, so it doesn't take part in Base UI Field validity.

API `Textarea` (extends `<textarea>` (`React.ComponentProps<"textarea">`)):
- `value?: string`. Controlled value. Pair with `onChange`.
- `defaultValue?: string`. Initial value when uncontrolled.
- `onChange?: React.ChangeEventHandler<HTMLTextAreaElement>`. Fires on every edit.
- `placeholder?: string`. An example answer in Slate Meta.
- `rows?: number` = 2. Starting height in browsers without `field-sizing`. `min-h-*` is the better control.
- `maxLength?: number`. A hard cap. Pair it with a visible count.
- `aria-invalid?: boolean`. Draws the red border and ring.
- `disabled?: boolean` = false. Dims to 50% and blocks input.
- `readOnly?: boolean` = false. Focusable and selectable, not editable.
- `className?: string`. Merged after the base classes. Use it for `min-h-*`, `max-h-*`, `resize-*` and `md:text-[13px]`.

### Checkbox

- Level: Atom
- Category: Selection
- Status: Stable
- Import: `@oration/canon/components/checkbox`
- Exports: `Checkbox`
- Docs: /design/components/checkbox

Checkbox is a 16px square with 4px corners for choices that are independently on or off: a consent, an option in a list, a row in a table. Checked and indeterminate fill Quiet Indigo with a white check or dash. It is built on Base UI Checkbox, supports an `indeterminate` parent for select-all, and widens its hit area past the 16px box. The common mistake is using it for a setting that applies the moment it flips; that is a Switch.

When to use:
- For an independent yes or no that is saved with the form: Require a second approver over $25,000.
- For picking any number of options from a short visible list, such as the documents a supplier must send.
- For selecting rows in a list or table, with an indeterminate select-all in the header.
- For a parent option over a set of children, such as a group of notification events.
- For a consent or confirmation the person must tick before a submit: The bank details match the supplier's letter.

When not to use:
- For a setting that takes effect immediately, without a save. Use /design/components/switch instead.
- For exactly one choice out of several. Use /design/components/radio-group instead.
- For a choice that needs a title, a description and room to compare, drawn as a card. Use /design/components/choice-card instead.
- For a pressed state on a toolbar button, such as bold or wrap. Use /design/components/toggle instead.
- For filtering a list by several values from a long set. Use /design/components/filter-chip instead.

Rules:
- Checkbox saves, Switch applies: A checkbox is part of a form: its value is sent when the person saves. If flipping it changes something right away, it is a Switch.
- The Quiet Indigo Rule: Checked is selection, one of the few places indigo is spent. The fill is the only color; the label beside it stays ink.

Anatomy:
- Box: 16px, 4px corners, a 1px Field Stroke border. In dark it takes the input color at 30%.
- Indicator: A 14px lucide check, or a dash when `indeterminate`, in Indigo Paper on the Quiet Indigo fill.
- Hit area: An invisible `::after` that extends 12px left and right and 8px up and down, so the target is 40 by 32px.
- Label: A Label that wraps the box or points at it with `htmlFor`, 8px away. Clicking it toggles the box.

States:
- Unchecked: Field Stroke border, transparent fill.
- Checked: Quiet Indigo border and fill with a white check.
- Indeterminate: Quiet Indigo fill with a white dash. Announced as mixed. Set it when some, not all, children are checked.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 50%. Inside a choice-card FieldLabel, the card draws the ring instead.
- Invalid: With `aria-invalid`, a red border and a 3px red ring at 20%. A checked invalid box keeps its indigo border.
- Disabled: 50% opacity with a not-allowed cursor, checked or not. Inside a Field that contains a disabled control, it dims with the field.
- Read-only: `readOnly` blocks changes and sets `data-readonly`, with no visual change.

Behavior:
- Base UI renders a `<span role="checkbox">` with a hidden `<input type="checkbox">` beside it that carries the `id`, `name` and `value`, so it submits with a native form and links to a `<Label htmlFor>`.
- Controlled with `checked` and `onCheckedChange(checked, eventDetails)`, or uncontrolled with `defaultChecked`.
- `indeterminate` is controlled by you. Clicking an indeterminate box calls `onCheckedChange` with the opposite of `checked`, so a select-all with `checked={false}` selects everything.
- Space toggles. Enter does not, so pressing Enter in a form with a checkbox focused won't flip it.
- The fill and border change over 150ms; the check itself appears with no transition.
- For row selection, show row checkboxes on row hover or focus, and keep them visible once any row is selected.

Do and don't:
- Do: Use a checkbox for a choice that is saved with the rest of the form.
- Don't: Use a checkbox for a setting that applies the moment it's clicked. People look for a save button that never comes.
- Do: Show an indeterminate select-all when some rows are selected, and say how many.
- Don't: Leave the select-all unchecked while rows below it are checked. It reads as nothing selected.
- Do: Write the label as the statement that becomes true when checked.
- Don't: Write a negative label, such as Don't email remittance advice. Checking a box to turn something off is a double negative.

Content:
- Write labels as positive statements that the check makes true: Email remittance advice to the supplier.
- Sentence case, no trailing period, unless the label is a full sentence of consent.
- Keep the label on one line where you can; put the consequence in a description below it.
- A select-all needs no visible text in a table header, but it needs an `aria-label`: Select all invoices.

Accessibility:
- Every checkbox needs a name: a wrapping Label, a `<Label htmlFor>`, or `aria-label` for row checkboxes (Select INV-20417).
- `indeterminate` is announced as mixed through `aria-checked="mixed"`.
- Group related checkboxes in a fieldset with a legend so the group's question is announced once.
- The 16px box has a 40 by 32px hit area through its `::after`, so leave at least 8px between stacked rows.
- Row checkboxes that appear on hover must also appear on keyboard focus, or keyboard users select rows blind.
- Don't disable a required checkbox to force order; leave it enabled and explain the error on submit.
- Tab: Moves focus to the checkbox.
- Space: Toggles it. From indeterminate, sets it to the opposite of `checked`.
- Enter: Does nothing, by design.

Known gaps (follow the system, not the gap):
- There is no hover style. The box doesn't change until it is pressed, where DESIGN.md gives every control a hover response.
- packages/canon doesn't wrap Base UI's `CheckboxGroup`, so every select-all in the product computes `indeterminate` by hand.
- `readOnly` looks identical to an editable checkbox.

API `Checkbox` (extends Base UI `Checkbox.Root` (`<span>`)):
- `checked?: boolean`. Controlled checked state.
- `defaultChecked?: boolean` = false. Initial state when uncontrolled.
- `onCheckedChange?: (checked: boolean, eventDetails: Checkbox.Root.ChangeEventDetails) => void`. Called with the next state.
- `indeterminate?: boolean` = false. Shows the dash and announces mixed. You compute it from the children.
- `disabled?: boolean` = false. Dims to 50% and blocks changes.
- `readOnly?: boolean` = false. Blocks changes but stays focusable.
- `required?: boolean` = false. Must be checked for the form to submit.
- `id?: string`. Set on the hidden input, for `<Label htmlFor>`.
- `name?: string`. Form field name.
- `value?: string`. Value submitted when checked.
- `uncheckedValue?: string`. Value submitted when unchecked. Omitted, nothing is submitted.
- `parent?: boolean` = false. Marks the parent of a Base UI `CheckboxGroup`, which then manages indeterminate for you. Not wrapped in packages/canon.
- `inputRef?: React.Ref<HTMLInputElement>`. Ref to the hidden input.
- `className?: string`. Merged after the base classes, on the box.

### Radio group

- Level: Atom
- Category: Selection
- Status: Stable
- Import: `@oration/canon/components/radio-group`
- Exports: `RadioGroup`, `RadioGroupItem`
- Docs: /design/components/radio-group

Radio group is a set of mutually exclusive options where every choice stays visible: picking one clears the others. Each item is a 16px circle that fills Quiet Indigo with a white 8px dot when checked. It is built on Base UI RadioGroup and Radio, so arrow keys move and select, and the group submits one value. The mistake to avoid is a group with no name: the group needs a legend or `aria-labelledby`, and every option its own label.

When to use:
- For choosing exactly one of two to six options when seeing all of them helps the choice: ACH, Check, Virtual card.
- When each option needs a line of explanation beside it, such as how a queue routes work.
- For a setting with a default that is always one of a fixed set: When a W-9 expires.
- As the control inside choice cards, where the whole card is the label.

When not to use:
- For more than six options, or options that don't need to be compared side by side. Use /design/components/select instead.
- For switching the mode of a view, such as List or Board. Use /design/components/segmented-control instead.
- For a large, descriptive option with an icon or illustration, drawn as a card. Use /design/components/choice-card instead.
- For a single on or off choice. Use /design/components/checkbox instead.
- For choosing several options at once. Use /design/components/checkbox instead.

Rules:
- One is always chosen: Start the group with a sensible default selected, usually the most common or the safest option. A group with nothing selected can't be returned to that state once someone clicks, so don't rely on it to mean none.
- The Quiet Indigo Rule: The checked circle is selection, one of the few places indigo is spent. Option labels and descriptions stay ink and Slate Meta.

Anatomy:
- Group: A `role="radiogroup"` grid with an 8px gap, named by a legend or `aria-labelledby`.
- Circle: 16px, round, a 1px Field Stroke border. In dark it takes the input color at 30%.
- Dot: An 8px Indigo Paper dot, centered, on the Quiet Indigo fill when checked.
- Option label: A Label beside the circle, with an optional Slate Meta description below it. Clicking either selects the option.

States:
- Unchecked: Field Stroke border, transparent fill.
- Checked: Quiet Indigo border and fill with the 8px white dot.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 50%, on the focused item. In a FieldLabel choice card, the card draws the ring instead.
- Invalid: With `aria-invalid` on the items, a red border and a 3px red ring at 20%. A checked invalid item keeps its indigo border.
- Disabled: 50% opacity and a not-allowed cursor. Disable one item for an option that isn't available, or the group to lock them all.
- Read-only: `readOnly` on the group blocks changes with no visual change.

Behavior:
- Base UI renders each item as a `<span role="radio">` with a hidden radio input, so the group submits one value under `name` in a native form.
- Controlled with `value` and `onValueChange(value, eventDetails)`, or uncontrolled with `defaultValue`. The wrapper types the value as `any`, so narrow it (`String(value)` or a union check) before storing it.
- Tab moves into the group on the checked item (or the first, if none is checked) and out again in one stop. Arrow keys move between items and select as they go.
- Enter does nothing, so pressing it in a form won't change the choice.
- Items have an invisible `::after` 12px wider and 8px taller on each side, a 40 by 32px target.
- The group is a one-column grid by default; set `grid-cols-*` or `flex` on it for a row.

Do and don't:
- Do: Start with the most common option selected.
- Don't: Start with nothing selected. Once someone clicks, there's no way back to none, and a required group fails silently.
- Do: Name the group with a legend that asks the question, and give each option a short label.
- Don't: Leave the group unnamed with a heading nearby. Screen readers announce Radio group with no question.

Content:
- The legend asks the question or names the setting: Payment method, When a W-9 expires.
- Option labels are parallel and short, one to three words: ACH, Check, Virtual card.
- Put the difference between options in a Slate Meta description: 2 business days, Same day, 2.5% fee.
- Order options by frequency or by a natural scale (fastest to slowest), not alphabetically.

Accessibility:
- Name the group with `aria-labelledby` pointing at its heading, or put it in a fieldset with a legend.
- Each item needs its own label: a wrapping `<label>` or a `<Label htmlFor>` pointing at the item's `id`.
- Link an option's description with `aria-describedby` on the item, so it is read with the label.
- A disabled item stays visible and is skipped by arrow keys. Say why it's unavailable in its description.
- For an error, set `aria-invalid` on the items and put the message after the group, linked from the group with `aria-describedby`.
- Tab: Moves focus into the group, onto the checked item, and out again.
- ↓ + →: Moves to the next enabled item and selects it.
- ↑ + ←: Moves to the previous enabled item and selects it.
- Space: Selects the focused item.

Known gaps (follow the system, not the gap):
- There is no hover style on the circle, so a pointer gets no response until it clicks.
- The product's queue routing cards hand-roll the choice-card pattern (a `label` with `has-data-checked:ring-2`) instead of using Choice card or a FieldLabel card.
- `RadioGroup` and `RadioGroupItem` take Base UI's props without the `Value` generic, so values are `any` and every call site casts back to its union (`value as Queue["routing"]`) with no type checking.

API `RadioGroup` (extends Base UI `RadioGroup` (`<div role="radiogroup">`)):
- `value?: any`. The selected value, controlled.
- `defaultValue?: any`. The initially selected value, uncontrolled.
- `onValueChange?: (value: any, eventDetails: RadioGroup.ChangeEventDetails) => void`. Called with the newly selected item's value.
- `name?: string`. Form field name for the submitted value.
- `disabled?: boolean` = false. Disables every item.
- `readOnly?: boolean` = false. Blocks changes; items stay focusable.
- `required?: boolean` = false. A value must be chosen for the form to submit.
- `inputRef?: React.Ref<HTMLInputElement>`. Ref to the hidden input.
- `className?: string`. Merged after `grid w-full gap-2`; set columns here.

API `RadioGroupItem` (extends Base UI `Radio.Root` (`<span role="radio">`)):
- `value: any`. The value this option stands for.
- `id?: string`. For a `<Label htmlFor>`.
- `disabled?: boolean` = false. Disables this option only.
- `readOnly?: boolean` = false. Blocks selecting this option.
- `required?: boolean` = false. Marks the option's input required.
- `inputRef?: React.Ref<HTMLInputElement>`. Ref to this option's hidden input.
- `className?: string`. Merged after the base classes, on the circle.

### Switch

- Level: Atom
- Category: Selection
- Status: Stable
- Import: `@oration/canon/components/switch`
- Exports: `Switch`
- Docs: /design/components/switch

Switch is an on and off setting that takes effect the moment it flips, with no save. The track fills Quiet Indigo when on, and the white thumb springs across, stretches into a pill on hover and can be dragged. It is the control for settings rows, display menus and per-row enablement across Oration. The distinction people miss is immediate versus submit: if the change waits for a Save button, the control is a Checkbox.

When to use:
- For a setting that applies right away and says so: Email remittance advice, Autopay.
- In a settings row, with the label and description on the left and the switch at the right edge.
- In a display or view menu, with the `label` prop and the compact size: Show paid invoices.
- To enable or pause one item in a list, such as a webhook endpoint or an API key, with an `aria-label` that names the row.

When not to use:
- For a choice that is saved with the rest of a form. Use /design/components/checkbox instead.
- For choosing between two named modes, such as Monthly and Annual. Use /design/components/segmented-control instead.
- For a pressed state on a toolbar button, such as bold or wrap lines. Use /design/components/toggle instead.
- For selecting rows or items. Use /design/components/checkbox instead.
- For an action with a result, such as Send or Sync now. A switch has no result to wait for. Use /design/components/button instead.

Rules:
- Switch applies, Checkbox saves: A switch changes the setting the moment it flips and confirms it in place or with a toast. Never put switches in a form that has a Save button; the person can't tell which changes already happened.
- The Quiet Indigo Rule: An on switch is one of the few places indigo is spent. The label beside it stays ink, and the switch never carries a second color for danger or success.

Anatomy:
- Track: 34 by 20px at the default size, 28 by 16px compact, fully round. Quiet Indigo when on, the accent gray when off.
- Thumb: A white circle, 16px (12px compact), 2px inside the track, with a small shadow. It stretches 2px on hover and 4px, squashed 4px shorter, while pressed.
- Label: Optional, through the `label` prop: 13px (12px compact), ink when on and Slate Meta when off. Omit it when a Label or row title already names the switch.

States:
- Off: Accent gray track, thumb at the start.
- On: Quiet Indigo track, thumb at the end.
- Hover: Mouse only. The track darkens (indigo mixed with 10% black, or gray with 10% ink) and the thumb stretches 2px into a pill toward the center.
- Pressed: The thumb stretches 4px and squashes 4px shorter (3px compact) while the pointer is down.
- Dragging: After 2px of travel the thumb follows the pointer. On release it settles on whichever side of the midpoint it is on.
- Focus visible: A 1px Focus Indigo ring at 50%, 2px outside the track.
- Disabled: The whole switch and its label at 50% opacity, with no pointer events.
- Read-only: Ignores clicks, drags and keys, with no visual change.

Behavior:
- Controlled only: pass `checked` and update it in `onCheckedChange(next)`. `onToggle()` fires after every change without the value.
- Base UI renders the track as `<span role="switch">` with a hidden checkbox input that carries `id`, `name`, `value` and `uncheckedValue`, so `<Label htmlFor>` works and the value submits with a native form.
- The thumb moves on the house moderate spring: 160ms with no bounce. Pass `thumbTransition` to change it. The track color changes over 80ms.
- Clicking the label text, the track or anywhere on the wrapper toggles it. A drag that ends on the same side doesn't.
- Omit `size` and the switch follows the nearest SizeProvider; `"sm"` is kept as an alias for `"compact"`.
- With `label`, the wrapper becomes a padded row (12px sides and 8px top and bottom by default) built for menus and lists.

Do and don't:
- Do: Apply the change when the switch flips and confirm it in place.
- Don't: Put switches in a form with a Save button. Nobody can tell which settings already changed.
- Do: Name the setting in the label and let the track show the state.
- Don't: Label the switch with its state, such as On or Enabled. The label then contradicts itself every time it flips.

Content:
- Name the setting as a noun phrase or a short verb phrase: Autopay, Email remittance advice.
- Don't write On, Off, Enabled or Disabled next to a switch; the track already says it.
- Put the consequence in the description, and update it with the state when that helps: Suppliers get a PDF after every payment run.
- Confirm changes that affect other people with a toast that names what changed: Autopay on for Northwind Freight.

Accessibility:
- Name every switch: the `label` prop, a `<Label htmlFor>` pointing at its `id`, or an `aria-label` that names the row (Autopay for Northwind Freight).
- Link a description with `aria-describedby`; it is passed to the switch element.
- Screen readers announce the role as switch and the state as on or off from `aria-checked`.
- The track is 20px tall at the default size and 16px compact. In touch layouts, keep the default size and put the switch in a row whose label also toggles it.
- The thumb's slide uses `animate()` directly, which the app's `MotionConfig reducedMotion="user"` doesn't govern, so it still springs with reduced motion on. The spring is short and has no bounce.
- Tab: Moves focus to the switch.
- Space: Toggles it.
- Enter: Toggles it.

Known gaps (follow the system, not the gap):
- The switch is controlled only. `checked` defaults to `false` and is always passed to Base UI, so `defaultChecked` is ignored and an uncontrolled `<Switch />` never moves.
- The track is 34 by 20px; DESIGN.md specifies 32 by 18px.
- The off track reads `--accent`, and its hover mixes in the legacy `--overlay` token. DESIGN.md makes the unchecked track Field Stroke (`--input`).
- Focus is a 1px ring at a 2px offset, not the 3px ring at 40 to 50% every other control uses.
- The thumb is hard-coded `bg-white` in both themes.
- The label turns Slate Meta when off, which can read as a disabled setting next to other ink labels.

API `Switch` (extends `<div>` (`HTMLAttributes<HTMLDivElement>` without `onToggle`)):
- `checked?: boolean` = false. Whether it is on. Always pass it; the switch is controlled.
- `onCheckedChange?: (checked: boolean) => void`. Called with the next value on click, key or drag.
- `onToggle?: () => void`. Called after a change, without the value.
- `label?: string`. Text beside the track, which also names it. Omit it when an external label names the switch.
- `size?: "default" | "compact" | "sm"`. 34 by 20px or 28 by 16px. Omitted, it follows the surrounding SizeProvider. `"sm"` maps to `"compact"`.
- `disabled?: boolean` = false. Dims the switch and its label to 50% and blocks interaction.
- `readOnly?: boolean`. Blocks changes without dimming.
- `thumbTransition?: Transition` = spring.moderate. A motion transition for the thumb.
- `defaultChecked?: boolean`. Forwarded to Base UI, but has no effect because `checked` is always set. See known gaps.
- `id?: string`. Set on the hidden input, for `<Label htmlFor>`.
- `name?: string`. Form field name.
- `value?: string`. Submitted when on.
- `uncheckedValue?: string`. Submitted when off.
- `form?: string`. The `id` of a form outside the switch's tree.
- `required?: boolean`. Must be on for the form to submit.
- `inputRef?: Ref<HTMLInputElement>`. Ref to the hidden input.
- `aria-label?: string`. The name when there is no `label` and no linked Label.
- `className?: string`. Merged onto the wrapper, not the track.

### Slider

- Level: Atom
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/slider`
- Exports: `Slider`
- Docs: /design/components/slider

Slider picks a value, or a range with two thumbs, by dragging along a 4px track. The filled part of the track is Quiet Indigo and each thumb is a 12px white circle with an indigo edge and a 28px hit area. It is built on Base UI Slider, so it handles pointer drag, arrow keys, Page and Home keys, and form submission. It has no label or readout of its own: pair it with a visible value, or use Slider field, and always pass `value` or `defaultValue` as an array.

When to use:
- For a setting where the rough position matters more than the exact number: a daily sending limit, a monthly credit budget.
- For a bounded range filter with two thumbs, such as invoice amounts between $1,000 and $25,000.
- In a table row, to tune one value per item with the readout beside it.
- When the effect of the value can be shown live as it changes.

When not to use:
- For a setting that needs a label, a readout, min and max hints and a reset. Slider field has all four. Use /design/components/slider-field instead.
- For an exact number, such as an invoice amount or a PO number. Type it. Use /design/components/input instead.
- To show a read-only amount or progress. That is a meter, in ink. Use /design/components/meter instead.
- For a duration in hours and minutes. Use /design/components/duration-picker instead.
- For a handful of named steps, such as Low, Medium and High. Use /design/components/segmented-control instead.

Rules:
- Show the value: A slider always travels with its current value in text, in tabular figures, next to its label or at the end of the track. People shouldn't have to guess what the thumb position means.
- The Ink Fill Rule: The indigo fill belongs to the control you drag. When the bar only reports a quantity, such as credits used, draw it as a Meter in ink steps instead.

Anatomy:
- Track: 4px tall and fully round, in Well Gray (`--muted`).
- Range: The Quiet Indigo fill, from the start to the thumb or between two thumbs.
- Thumb: A 12px white circle with a 1px Focus Indigo edge. It sits inside the track's ends (`thumbAlignment="edge"`), so it never overhangs the container.
- Hit area: An invisible `::after` 8px past the thumb on every side, a 28px target.
- Readout: Not part of the component: a 13px tabular value beside the label or at the end of the track.

States:
- Rest: Well Gray track, indigo range, white thumb with an indigo edge.
- Hover: A 3px Focus Indigo ring at 50% around the thumb.
- Focus visible: The same 3px ring, on keyboard focus.
- Dragging: The ring stays while the thumb is held (`active:`), and the range follows the pointer.
- Disabled: The whole control at 50% opacity, with no pointer events on the thumbs.

Behavior:
- Controlled with `value` and `onValueChange(value, eventDetails)`, or uncontrolled with `defaultValue`. Pass arrays: the wrapper renders one thumb per array item.
- `onValueCommitted` fires once when the pointer is released or a key press ends, so save or toast there, not on every change.
- Clicking the track moves the nearest thumb to that point and starts a drag.
- `step` snaps values, `largeStep` (10 by default) is the jump for Page Up, Page Down and Shift with an arrow, and `minStepsBetweenValues` keeps two thumbs apart.
- `orientation="vertical"` stands the track up, at least 160px tall.
- Each thumb is a visually hidden `<input type="range">`, so `name` submits the value with a native form.
- The ring on the thumb eases in with `transition-[color,box-shadow]` at the default 150ms.

Do and don't:
- Do: Show the value beside the slider and update it as the thumb moves.
- Don't: Leave a bare track. Nobody can tell whether the thumb means 40 or 60 emails a day.
- Do: Save once in `onValueCommitted`, when the thumb is released.
- Don't: Save or toast in `onValueChange`. A single drag fires dozens of saves.

Content:
- Label the setting, not the gesture: Daily sending limit, not Drag to set limit.
- Write the value with its unit: 40 a day, 4,500 credits, $1,000 to $25,000.
- When the value changes the outcome, say how in a line below: Pauses the agent once 4,500 credits are used.

Accessibility:
- Name the slider with `aria-labelledby` on the Slider pointing at a visible label. Base UI passes it to each thumb's range input. `aria-label` on the Slider does not reach the thumbs.
- Screen readers read the value from `aria-valuenow`; set `format` (Intl number options) so it is announced with its unit, such as currency.
- Keep the readout in `aria-live="polite"` only if it adds information the value text doesn't, such as a warning.
- The 12px thumb has a 28px hit area. In a dense row, leave room either side so the target doesn't overlap another control.
- Every value must be reachable by keyboard: step with arrows, jump with Page keys, and reach the ends with Home and End.
- → + ↑: Increases by `step`.
- ← + ↓: Decreases by `step`.
- Shift + →: Increases by `largeStep`. Shift with ← or ↓ decreases.
- Page Up: Increases by `largeStep`.
- Page Down: Decreases by `largeStep`.
- Home: Sets the minimum, or in a range, the lowest value the thumb can reach.
- End: Sets the maximum, or in a range, the highest value the thumb can reach.

Known gaps (follow the system, not the gap):
- A plain number for `value` or `defaultValue` renders two thumbs. The wrapper counts thumbs from the array, and without one it falls back to `[min, max]`, while Base UI tracks a single value. Always pass an array.
- Thumbs can't be named one by one, because the wrapper doesn't expose Base UI's `getAriaLabel`. Both thumbs of a range share the slider's label, with no Minimum and Maximum.
- The thumb is hard-coded `bg-white`, so in dark it is the brightest thing on screen.
- There is no built-in label or readout; product call sites hand-roll both (`aria-labelledby` on an `sr-only` span, a tabular value beside the track). Slider field covers the common case.

API `Slider` (extends Base UI `Slider.Root` (`<div role="group">`)):
- `value?: number | readonly number[]`. Controlled value. Pass an array, one number per thumb. A plain number still renders two thumbs; see known gaps.
- `defaultValue?: number | readonly number[]`. Initial value when uncontrolled. Also pass an array.
- `onValueChange?: (value: number | number[], eventDetails: Slider.Root.ChangeEventDetails) => void`. Called on every change while dragging or stepping.
- `onValueCommitted?: (value: number | number[], eventDetails: Slider.Root.CommitEventDetails) => void`. Called once when the pointer is released or a key press ends.
- `min?: number` = 0. The smallest value.
- `max?: number` = 100. The largest value.
- `step?: number` = 1. The increment values snap to.
- `largeStep?: number` = 10. The jump for Page Up, Page Down and Shift with an arrow.
- `minStepsBetweenValues?: number` = 0. The closest two thumbs can get, in steps.
- `thumbCollisionBehavior?: "push" | "swap" | "none"` = "push". What happens when one thumb is dragged into another.
- `orientation?: "horizontal" | "vertical"` = "horizontal". Vertical tracks are at least 160px tall.
- `thumbAlignment?: "center" | "edge" | "edge-client-only"` = "edge". Where the thumb sits at the ends. The wrapper sets `edge`.
- `format?: Intl.NumberFormatOptions`. Formats the value for `aria-valuetext`.
- `disabled?: boolean` = false. Dims to 50% and blocks interaction.
- `name?: string`. Form field name.
- `aria-labelledby?: string`. The `id` of the visible label. Passed through to every thumb.
- `className?: string`. Merged onto the root.

### Toggle

- Level: Atom
- Category: Actions
- Status: Experimental
- Import: `@oration/canon/components/toggle`
- Exports: `Toggle`, `toggleVariants`
- Docs: /design/components/toggle

Toggle is a button that stays pressed: one click turns an option on, the next turns it off, and the state is exposed as `aria-pressed`. It is for formatting and view options in toolbars, such as bold in a note editor or wrapping long memos in a table. It is built on Base UI Toggle and shares its look with Toggle group, which is how the product uses it today. People get two things wrong: they reach for it where a Switch belongs, and they ship icon-only toggles without a name.

When to use:
- For formatting in an editor toolbar: Bold, Italic, Bulleted list.
- For a view option that changes how the current screen draws, right away: Wrap memos, Show cents.
- For a single on and off control that sits among buttons and should look like one.
- As the building block of a Toggle group, when several toggles share a toolbar.

When not to use:
- For a setting in a settings page or a form row. Use /design/components/switch instead.
- For a set of toggles that belong together, or a choice of exactly one. Use /design/components/toggle-group instead.
- For choosing one of two to five view modes, such as List and Board. Use /design/components/segmented-control instead.
- For an icon action with a tooltip and an active state, such as pinning a record. Use /design/components/icon-action instead.
- For an action that does something once, such as Export. Use /design/components/button instead.
- For an active filter on a list. Use /design/components/filter-chip instead.

Rules:
- The label never changes: A toggle's label and icon stay the same in both states; only the pressed fill changes. If the label would need to flip (Show and Hide), use a Switch or a Button whose action changes.
- Toggles change the view, not the data: Use a toggle for how something is drawn or formatted. A change that is saved for everyone, or that people would expect to undo, belongs to a Switch or a Button.

Anatomy:
- Container: 32px tall and at least 32px wide, 10px corners, transparent, or with a 1px Field Stroke in the outline variant.
- Icon: 16px (14px at `sm`), with `data-icon="inline-start"` tightening the padding on that side by 2px.
- Label: Optional, 14px at weight 500, 4px from the icon.
- Pressed fill: Well Gray (`--muted`) while `aria-pressed` is true.

States:
- Off: Transparent, or a Field Stroke outline.
- Hover: Well Gray fill and ink text, over 150ms.
- Pressed (on): Well Gray fill, the same as hover. See known gaps.
- Focus visible: A 3px Focus Indigo ring at 50%, and an indigo border on the outline variant.
- Disabled: 50% opacity and no pointer events, in either state.

Behavior:
- Renders a native `<button type="button">` through Base UI with `aria-pressed` and `data-pressed` when on.
- Controlled with `pressed` and `onPressedChange(pressed, eventDetails)`, or uncontrolled with `defaultPressed`.
- Inside a Toggle group, the group owns the state and each toggle's `value` identifies it.
- The change is immediate: whatever the toggle controls should update in the same frame, with no save.
- `toggleVariants` is exported so a Toggle group item, or another element, can take the same classes.

Do and don't:
- Do: Give an icon-only toggle an `aria-label` and a tooltip with the same words.
- Don't: Ship a bare icon. Screen readers announce Toggle button, pressed, with no name.
- Do: Keep the label fixed and let the pressed fill show the state.
- Don't: Swap the label between Show cents and Hide cents. Combined with the pressed state, it reads backwards half the time.

Content:
- Name the option, not the action: Wrap memos, Show cents, Bold.
- Keep text toggles to one or two words; most toolbar toggles are icon-only with a tooltip.
- Tooltips match the `aria-label` and may add the shortcut: Bold, then the ⌘B keys.

Accessibility:
- `aria-pressed` tells screen readers the state; don't also put on or off in the label.
- Icon-only toggles need an `aria-label` and a tooltip. Mark the icon `aria-hidden="true"`.
- The hover and pressed fills are the same Well Gray, so check the pressed state reads without a pointer over it. Pair a toggle with a visible effect on the content.
- The sm size is 28px, the smallest a pointer target should be. Use the default 32px on touch layouts.
- If a toggle has a keyboard shortcut, expose it with `aria-keyshortcuts` and show it in the tooltip.
- Tab: Moves focus to the toggle.
- Space: Toggles it.
- Enter: Toggles it.

Known gaps (follow the system, not the gap):
- Pressed and hover draw the same Well Gray fill, and nothing else changes when a toggle is on. A hovered off toggle looks on, and an on toggle under the pointer gives no feedback when clicked off.
- `data-[state=on]:bg-muted` is a Radix attribute; Base UI sets `data-pressed`, so that class never applies (`aria-pressed:bg-muted` does the work).
- `aria-invalid` sets a red ring color with no ring width, so an invalid toggle only shows a red border, and only in the outline variant.
- The icon-to-label gap is 4px at every size; Button uses 6px at its default size and DESIGN.md asks for 6 to 8px inside controls.
- No product screen uses Toggle directly yet; it ships through Toggle group.

API `Toggle` (extends Base UI `Toggle` (native `<button>`)):
- `variant?: "default" | "outline"` = "default". Transparent, or with a 1px Field Stroke border.
- `size?: "sm" | "default" | "lg"` = "default". 28, 32 or 36px tall, and at least as wide.
- `pressed?: boolean`. Controlled pressed state.
- `defaultPressed?: boolean` = false. Initial state when uncontrolled.
- `onPressedChange?: (pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void`. Called with the next state.
- `value?: string`. Identifies the toggle inside a Toggle group.
- `disabled?: boolean` = false. Dims to 50% and blocks interaction.
- `aria-label?: string`. Required for icon-only toggles.
- `className?: string`. Merged into the variant classes.

### Separator

- Level: Atom
- Category: Layout
- Status: Beta
- Import: `@oration/canon/components/separator`
- Exports: `Separator`
- Docs: /design/components/separator

Separator is a 1px Hairline rule that divides content horizontally, or vertically between items in a row. It renders a Base UI Separator, so it is exposed as `role="separator"` with its orientation. In Oration hairlines are structural: they split sections inside a surface, rule table rows and divide groups in a toolbar or header. The mistake is decoration: using a separator to outline a card, or ruling content that spacing already groups.

When to use:
- To split two sections inside one card or sheet, such as remittance details and bank account.
- Vertically, between the sidebar toggle and the breadcrumbs in a page header, at 16px tall.
- Between groups of controls in a toolbar, so the groups read as separate.
- Between groups of items in a list or menu, where a heading would be too much.

When not to use:
- As the edge of a card, panel or popover. Raised surfaces take their edge from the hairline lift shadow. Use /design/components/card instead.
- For a labelled split such as the or between two sign-in options. Use /design/components/field instead.
- Between rows of a table or list you build. A `border-b border-border` or `divide-y` on the container is simpler and draws the same line. Use /design/components/table instead.
- For a quiet note that also divides, with an icon or a short label. Use /design/components/marker instead.
- Between buttons joined into one control. Use /design/components/button-group instead.

Rules:
- The Hairline-and-Lift Rule: A raised surface takes its edge and its lift from one composite shadow, never from a CSS border or a separator plus a shadow. Hairlines are for structural dividers only: table rules, header bottoms and section splits.
- Space first, rule second: Most groups are separated well enough by 12 to 32px of space. Add a separator when two regions sit flush, or when spacing alone would leave it unclear where one ends.

Anatomy:
- Rule: 1px of Hairline (`--border`), full width when horizontal, or full height of its row when vertical.
- Spacing: Not part of the component. Add margin with the layout: 16px around a section split in a card, 4 to 8px beside a vertical separator in a header or toolbar.

States:
- Horizontal: `h-px w-full`. The default orientation.
- Vertical: `w-px self-stretch`. It fills the height of its flex row; set `data-vertical:h-4 data-vertical:self-center` for a shorter rule.

Behavior:
- Renders a `<div role="separator">` with `aria-orientation` and `data-orientation`, which the `data-horizontal:` and `data-vertical:` classes read.
- It doesn't take focus and isn't interactive.
- `shrink-0` keeps it from collapsing in a flex row.
- In dark, the Hairline is white at 7.5%, so the rule stays faint on both planes.

Do and don't:
- Do: Use one hairline to split two distinct sections inside a card.
- Don't: Rule every line of a short list whose spacing already groups it. The page turns into a ledger of lines.
- Do: Lift a card with `shadow-border` and split its inside with a separator.
- Don't: Draw the card's edge with borders or separators. It breaks The Hairline-and-Lift Rule and doubles the edge.

Content:
- A separator has no text. If the split needs a word, use a heading, a Field separator or a Marker.

Accessibility:
- Screen readers may announce separator. Use it where the split is meaningful, such as between groups of toolbar controls.
- For a purely visual line inside a component that already groups its content, a CSS border avoids an extra announcement.
- Inside a `role="toolbar"`, separators tell assistive tech where one group of controls ends.
- Don't rely on the rule alone to show grouping; keep the spacing and headings that make the structure clear.

Known gaps (follow the system, not the gap):
- Only one product screen, the page header, uses Separator. Elsewhere apps/web draws the same line with `border-t border-border`, `border-b border-border` or `divide-y` (over 230 files).
- There is no decorative option: the rule is always exposed as `role="separator"`, even where it is only visual.

API `Separator` (extends Base UI `Separator` (`<div role="separator">`)):
- `orientation?: "horizontal" | "vertical"` = "horizontal". Draws a 1px row or a 1px column, and sets `aria-orientation`.
- `className?: string`. Merged after the base classes. Use `data-vertical:h-4` and `data-vertical:self-center` for a short vertical rule, or margins for spacing.
- `render?: ReactElement | (props, state) => ReactElement`. Render as another element, such as an `<hr>` or an `<li>` in a list.

### Skeleton

- Level: Atom
- Category: Feedback
- Status: Stable
- Import: `@oration/canon/components/skeletons`
- Exports: `Skeleton`, `SkeletonText`, `SkeletonRows`, `SkeletonTable`, `SkeletonCard`, `SkeletonStat`, `SkeletonChart`, `SkeletonList`
- Docs: /design/components/skeleton

Skeletons stand in for data while it loads, drawn in the shape of what will replace them so the swap moves nothing. Every data component in Oration owns its own loading state, so a page renders its chrome at once and only the regions still fetching show bones. Reach for a preset first (`SkeletonText`, `SkeletonRows`, `SkeletonTable`, `SkeletonCard`, `SkeletonStat`, `SkeletonChart`, `SkeletonList`) and compose from `SkeletonBone` when the shape differs. The common mistake is a generic block or a spinner that has nothing to do with the final layout, so everything jumps when the data lands.

When to use:
- For any list, table, card, stat strip or chart whose data arrives after first paint, as the `skeleton` of a Data state.
- When the final layout is known: rows of suppliers, a grid of invoices, a remittance card, a chart plot.
- For enrichment cells that are queued: an 8px bone whose width varies by row.
- When a load can take longer than about 300ms. Faster than that, render nothing and let the content arrive.

When not to use:
- For work the person started, such as saving or testing a connection. Show progress on the control that started it. Use /design/components/pending-button instead.
- For a small inline wait with no layout to preview, such as checking a slug. Use /design/components/spinner instead.
- For an AI model thinking or drafting. It has its own pixel shimmer and elapsed time. Use /design/components/ai-loader instead.
- For a task with a known amount done, such as importing 1,240 suppliers. Use /design/components/progress instead.
- For a place that loaded and has nothing in it. Say what it is for and offer the first action. Use /design/components/empty instead.

Rules:
- Skeletons match the final layout: A skeleton takes the row height, padding, tile size and column template of the content it stands in for, so the reveal to content moves nothing. A 52px supplier row loads as a 52px bone row, a 36px grid row as a 36px bone row.
- Never gate a whole page: Each data component owns its loading, empty and error states. Titles, filters and actions render immediately; only the data region shows bones.
- Skeletons leave through the skeleton reveal: Hand every loading skeleton to `DataState`'s `skeleton` prop, or to `SkeletonReveal`'s `skeleton` prop when the load isn't a query (a lazy mount, a link check, a `loading` flag). Never render it from your own `loading ? … : …`. See The Skeleton Reveal Rule.

Anatomy:
- Leading tile: A 32px bone (24px on one-line rows), round for people and `rounded-lg` for companies and agents via `avatar`.
- Title bone: 12px tall, round-ended, with a width taken from a fixed ragged sequence so rows don't look stamped.
- Secondary bone: 10px tall and shorter than the title. Only on two-line rows (`lines={2}`).
- Meta bone: A 48px trailing bone for the amount, date or count. Turn it off with `meta={false}`.
- Row: 52px minimum for two lines and 36px for one, with 8px side padding and a 12px gap: the same box as the real row.

States:
- Loading: Bones on Well Gray with a light sweep every 1.6s. `background-attachment: fixed` lines every bone up to one sweep across the viewport.
- Reduced motion: The sweep stops (`motion-reduce:animate-none` plus the global `.skeleton-shimmer` rule). Bones stay as still Well Gray shapes.
- Base skeleton: The plain `Skeleton` pulses its opacity with `animate-pulse` instead of shimmering, and keeps pulsing under reduced motion.
- Loaded: The parent swaps bones for content through the skeleton reveal (`DataState` or `SkeletonReveal`): the bones pulse, then cross-fade out with a 2px blur over 400ms as the content sharpens in. Data that is already warm renders with no skeleton at all.

Behavior:
- Presets are server-safe function components with no state. They render bones only; the parent decides when to show them.
- Widths come from a fixed ragged sequence (92%, 70%, 84%, 58%…), so renders are deterministic and never cause hydration mismatches.
- `SkeletonTable` uses the grid template `minmax(0, 2fr) repeat(n - 1, minmax(0, 1fr))`: a wider first column with a 20px tile, and the last column right-aligned like a numeric column.
- `SkeletonStat` is cell for cell with Stat strip: two columns below 640px, one row of equal cells above, hairlines between cells.
- `SkeletonCard` draws its own card (12px corners, hairline lift). Don't wrap it in another card.
- `SkeletonChart` rules four gridlines (three dashed, the baseline solid) and draws bars from a fixed height sequence, or a flat curve at 10% ink for `type="line"`.
- Inside Data state, a sr-only Loading and `aria-busy` are added for you. Hand-rolled loading regions must add both.

Do and don't:
- Do: Load a list as rows of the same height, tile and padding as the real rows.
- Don't: Park a spinner in a box of a made-up height. The card jumps when the rows arrive.
- Do: Keep the title, filters and actions real and skeleton only the data region.
- Don't: Turn the whole card, headings and buttons included, into bones. People lose their place and can't act.
- Do: Build custom shapes from `SkeletonBone` so every bone shares one sweep.
- Don't: Mix pulsing `Skeleton` blocks, shimmering bones and a spinner in one region. Three rhythms read as three problems.
- Do: Pass the bones as `skeleton` to `DataState` or `SkeletonReveal`, so they pulse and then cross-fade into the content.
- Don't: Write `loading ? <SkeletonRows /> : <List />`. The content snaps in with no reveal.

Content:
- Skeletons carry no visible text. Don't write Loading… inside the bones.
- Name what is loading for screen readers: a sr-only Loading remittances beats a bare Loading.
- If a load runs long, add one quiet line beside the bones after a delay (`useDelayedFlag`), such as Still loading invoices, rather than a bigger animation.
- When the load fails, replace the skeleton with an error that says what failed and offers Retry, never with an empty state.

Accessibility:
- Every preset and `SkeletonBone` inside them is `aria-hidden="true"`: bones are decoration.
- The base `Skeleton` is a plain `<div>` with no ARIA. Mark hand-rolled compositions `aria-hidden="true"`.
- The region that is loading carries `aria-busy` and a sr-only status naming what is loading. Data state does both.
- Don't move focus into or out of a loading region; when content arrives, focus stays where it was.
- The shimmer stops under `prefers-reduced-motion`. The base Skeleton's pulse does not; prefer bones.

Known gaps (follow the system, not the gap):
- The base `Skeleton` pulses with `animate-pulse` and has no reduced-motion guard, while every preset shimmers and stops. About 18 files in apps/web still use the base block directly, so two loading rhythms coexist. Use `SkeletonBone` for custom shapes.
- The base `Skeleton` is not `aria-hidden`. Hand-rolled compositions must add `aria-hidden="true"` themselves.
- `Skeleton` is exported from `@oration/canon/components/skeleton`, not from `skeletons` where the presets live, and `SkeletonBone` is not in the registry's export list.
- `SkeletonBone` accepts only `className` and `style`; other `<div>` props are dropped.

API `Skeleton` (extends <div>):
- `className?: string`. Size and shape, such as `h-3 w-2/5` or `size-8 rounded-lg`.

API `SkeletonBone`:
- `className?: string`. Size and corner overrides, such as `h-5 w-16 rounded-md`.
- `style?: React.CSSProperties`. Merged after `backgroundAttachment: fixed`, for computed widths.

API `SkeletonText`:
- `lines?: number` = 3. Number of lines. The last of several ends at 58%.
- `widths?: (string | number)[]`. Width per line. Numbers are percentages; strings pass through (`"9rem"`).
- `size?: "body" | "caption"` = "body". 10px bones on 20px lines, or 8px bones on 16px lines.
- `className?: string`. On the wrapper.

API `SkeletonRows`:
- `rows?: number` = 5. Row count.
- `avatar?: boolean | "circle" | "square"` = "circle". Leading tile shape. `true` is a circle, `false` removes it.
- `lines?: 1 | 2` = 2. One line (36px rows, 24px tile) or two (52px, 32px).
- `meta?: boolean` = true. Trailing 48px bone.
- `divided?: boolean` = false. Hairline dividers between rows.
- `className?: string`. On the wrapper.

API `SkeletonTable`:
- `rows?: number` = 8. Body rows.
- `columns?: number` = 5. Columns, including the wide first one.
- `header?: boolean` = true. Draw the header row.
- `className?: string`. On the wrapper.

API `SkeletonCard`:
- `lines?: number` = 2. Body lines. `0` draws only the header.
- `media?: boolean` = false. A 16:9 well above the header.
- `footer?: boolean` = false. Two tag bones and a trailing meta bone.
- `className?: string`. On the card.

API `SkeletonStat`:
- `count?: number` = 4. Cells.
- `trend?: boolean` = false. A trailing sparkline bone per cell, hidden below 640px.
- `className?: string`. On the strip.

API `SkeletonChart`:
- `type?: "bar" | "line"` = "bar". Placeholder bars, or a flat curve at 10% ink.
- `height?: number` = 160. Plot height in pixels.
- `bars?: number` = 12. Bar count.
- `axis?: boolean` = true. Five tick bones under the plot.
- `className?: string`. On the wrapper.

API `SkeletonList`:
- `items?: number` = 5. Items.
- `icon?: boolean` = true. Leading 16px icon bone.
- `className?: string`. On the wrapper.

### Spinner

- Level: Atom
- Category: Feedback
- Status: Stable
- Import: `@oration/canon/components/spinner`
- Exports: `Spinner`
- Docs: /design/components/spinner

Spinner is a 16px rotating arc for work a person just started and is waiting on: testing a connection, syncing bills, checking a URL. It sits inside or beside the control that started the work, in the icon slot, while the label says what is happening. It is not a content loader. Lists, tables and cards load as a Skeleton in their final shape, and a spinner parked in an empty box is the most common misuse.

When to use:
- In the leading icon slot of a button while its action runs, marked `data-icon="inline-start"`, with the label changed to what is happening: Testing connection.
- In place of the icon on an icon button while it works, such as refreshing a bank feed.
- Beside a short inline status line, such as Checking availability under a URL field.
- Only after a short delay. Hold it back 200ms with `useDelayedFlag` so fast work never flashes a spinner.

When not to use:
- For content that is loading. Show bones in the final layout instead. Use /design/components/skeleton instead.
- For a submit button whose width must not change while it works. Use /design/components/pending-button instead.
- For an AI model thinking or drafting, where elapsed time matters. Use /design/components/ai-loader instead.
- For work with a known amount done, such as an import at 62%. Use /design/components/progress instead.
- For a live state such as a running workflow or a call in progress. That is a labelled status, not a wait. Use /design/components/status-label instead.

Rules:
- Spinners belong to actions: A spinner answers the person who pressed something: it lives on that control or next to it. Data the page fetched on its own loads as a skeleton in its final shape.
- The label carries the state: Keep a text label beside the spinner and change it to the present tense of the action (Syncing bills, Testing connection). The spinner alone says nothing about what is happening.

Anatomy:
- Arc: Lucide `Loader2Icon`, a three-quarter circle at the 1.75 stroke, drawn in `currentColor` so it takes the text color of its control.
- Box: 16px by default (`size-4`). Inside buttons the button sizes it: 16px, 14px at `sm`, 12px at `xs`.
- Name: `role="status"` and `aria-label="Loading"` by default. Pass `aria-hidden="true"` when a visible label already says what is happening.

States:
- Spinning: `animate-spin`: one full turn per second, linear, for as long as it is mounted.
- In a disabled control: Takes the control's 50% opacity. Prefer `aria-disabled` or Pending button so the control keeps focus.
- Reduced motion: Keeps rotating. It is the one indicator that something is still working, so it is treated as essential motion.

Behavior:
- Renders the SVG directly; all props, including `aria-label`, `role` and `className`, spread onto it after the defaults, so each one can be overridden.
- Mounting it starts the rotation; unmount it or swap it back to the icon when the work finishes. It has no paused or done state of its own.
- Inside a Button, `data-icon="inline-start"` tightens the leading padding by 2px exactly like a normal icon, so the swap from icon to spinner doesn't move the label.
- Changing the label changes the button's width. When the width must hold, use Pending button, which fades the label and centers the spinner over it.
- `useDelayedFlag(pending, 200)` from Data state returns true only once `pending` has stayed true for 200ms. Gate the spinner on it.

Do and don't:
- Do: Load content as a skeleton in its final shape, and keep the spinner for actions.
- Don't: Center a spinner in an empty card while its rows load. The card jumps when they arrive.
- Do: Keep a label beside the spinner that says what is happening: Saving supplier.
- Don't: Replace the whole label with a spinner. The button shrinks and nothing names the work.
- Do: Hold the spinner back 200ms so fast work finishes without a flash.
- Don't: Show a spinner for every request, however quick. A 100ms flicker reads as a glitch.

Content:
- Change the label to the present participle of the action: Test connection becomes Testing connection, Sync bills becomes Syncing bills.
- Name the object when there are several on screen: Refreshing bank feed in the accessible name, even if the tooltip says Refresh.
- When the work finishes, confirm it with a toast or an inline result (cedarline-ap is available), not by the spinner simply disappearing.
- Don't write Please wait or Loading… next to a spinner in a button. The verb already says it.

Accessibility:
- By default the SVG is `role="status"` with `aria-label="Loading"`. Inside a labelled button that label joins the button's name ("Loading Testing connection"), so pass `aria-hidden="true"` there and let the changed label speak.
- A newly mounted status element is not reliably announced. For waits the person should hear about, update the text of a live region that already exists, as the URL check does with `aria-live="polite"`.
- Keep the control focusable while it works. `aria-disabled` keeps focus in place; native `disabled` drops it to the body.
- Icon buttons that swap to a spinner update their `aria-label` too: Refresh bank feed becomes Refreshing bank feed.
- The spinner keeps turning under reduced motion because it is the only sign the work is still running. It is small, slow and never flashes.

Known gaps (follow the system, not the gap):
- The default `role="status"` and `aria-label="Loading"` add "Loading" to the name of any button it sits in. Most call sites (`<Spinner data-icon="inline-start" />` in about a dozen dialogs and settings rows) don't pass `aria-hidden`.
- Pending button renders the spinner with its defaults over a label that is only faded to 0 opacity, so its name reads as the label plus "Loading".
- There is no built-in delay. Every caller has to gate the spinner with `useDelayedFlag` itself, and most don't.

API `Spinner` (extends <svg> (lucide icon props)):
- `className?: string` = "size-4 animate-spin". Merged after the defaults. Set size and color here: `size-3.5`, `text-muted-foreground`.
- `aria-label?: string` = "Loading". The status name. Override it with what is loading, or hide the spinner when a label says it.
- `role?: AriaRole` = "status". Exposed as a status. Override only with good reason.
- `aria-hidden?: boolean`. Set inside labelled buttons and inline hints, where the text already speaks.
- `data-icon?: "inline-start" | "inline-end"`. Inside a Button, tightens the padding on that side like any icon.

### Status label

- Level: Atom
- Category: Feedback
- Status: Stable
- Import: `@oration/canon/components/status-dot`
- Exports: `StatusDot`, `StatusLabel`, `StatusTone`
- Docs: /design/components/status-label

Status label is an 8px dot and a short word that together say what state something is in: Running, Paid, At risk, Failed. It is how Oration shows status in table cells, record headers and list rows, and it is the only sanctioned way to put a status color on screen. `StatusDot` is the dot alone, for layouts where the words sit in their own element. The mistake to avoid is the dot without the words: color alone never carries status.

When to use:
- For the state of a record or process in a table cell: payment runs, test runs, agents, imports, integrations.
- Beside a record's name in its header, for the one state that matters most: W-9 on file, Bank change pending.
- For live states that carry a label, in the primary tone with `pulse`: Running, On a call.
- `StatusDot` alone when the label is richer than one line, such as a checklist item with a title and detail, and the words sit right beside it.

When not to use:
- For a select-option value the person picks, such as a stage, tier or lifecycle. Use /design/components/tag instead.
- For a count or a short label attached to a control. Use /design/components/badge instead.
- For a message that needs a sentence and maybe an action. Use /design/components/alert instead.
- For an AI agent's identity with its live ring. Use /design/components/agent-avatar instead.
- For how far along something is. Show the amount done. Use /design/components/progress instead.

Rules:
- The Label-Beside-Color Rule: Status is never color alone. A dot, tint or ring always travels with a text label (On track, At risk, Running, Passed), so the state reads in grayscale.
- The Quiet Indigo Rule: The primary tone is indigo, and indigo is spent only on live state that carries a label: running, active, on a call, upcoming. Done, paid and passed are success, not primary.

Anatomy:
- Dot: 8px round, filled with the tone. Always `aria-hidden`.
- Pulse: Optional. A copy of the dot at 60% that scales out and fades on `animate-ping`, only when motion is allowed.
- Gap: 6px between dot and label (`gap-1.5`).
- Label: One or two words in Graphite Ink, meant to be Body Dense (13px), on one line (`whitespace-nowrap`).

States:
- Neutral: Faint Slate dot. Not started, off, skipped, draft, archived.
- Primary (live): Quiet Indigo dot. Running, on a call, active, upcoming. Usually with `pulse`.
- Success: Ledger Green. Paid, passed, connected, on track.
- Warning: Caution Amber. At risk, needs approval, invited, pending.
- Danger: Signal Red. Failed, stalled, rejected, disconnected.
- Info: Note Blue. Scheduled, informational.
- Pulsing: The ring scales to 2x and fades over 1s, forever, while `pulse` is set.
- Reduced motion: The ring is behind `motion-safe:`, so it never renders its animation. The dot and label stay.

Behavior:
- Both components are plain spans with no state. The parent picks the tone and label from the record's data.
- `StatusLabel` renders `StatusDot` then its children, so any `className` you pass lands on the outer span: `text-xs text-muted-foreground` sets a meta-row variant.
- The label never wraps (`whitespace-nowrap`). Give the column room or shorten the word.
- `StatusDot` accepts a `className` for alignment, such as `mt-1.5` to sit on the first line of a two-line item.
- When a status changes while the person watches, put the label inside a `role="status"` region so the new word is announced.

Do and don't:
- Do: Pair every dot with the word for the state.
- Don't: Show a column of colored dots and expect people to learn the colors. In grayscale, or to a screen reader, they say nothing.
- Do: Pulse only live states, such as the run that is running now.
- Don't: Pulse every status. When everything moves, nothing reads as live.
- Do: Keep the label to the state and put the reason beside it.
- Don't: Write a sentence in the label. It won't wrap, and a status should scan in a column.

Content:
- One or two words, sentence case, no punctuation: Paid, Needs approval, On a call.
- Name the state, not the action: Paid, not Pay; Failed, not Retry.
- Use the present participle for live states: Running, Syncing, Dialing.
- Keep one word per state across the product. If it is Failed in the payment runs table, it is Failed in the run's header and in the toast.
- Put reasons and counts in the next element, not in the label: Failed with Halcyon's bank rejected the ACH file beneath.

Accessibility:
- The dot is `aria-hidden`. The label text is what assistive technology reads, so it must name the state on its own.
- Because the words carry the state, the dot is decorative and doesn't need 3:1 contrast. Amber on white is well under that, which is one more reason the label is required.
- For status that changes live, wrap it in a `role="status"` region that exists before the change.
- Pulse is off under `prefers-reduced-motion` (`motion-safe:animate-ping`).
- In tables, the column header (Status) gives the label its context; don't repeat Status: in every cell.

Known gaps (follow the system, not the gap):
- `StatusLabel` merges its classes with `cn` from the `cn` package, which reads `text-13` as a text color and drops it in favor of `text-foreground`. The label renders at its parent's size, not 13px. It looks right inside 13px table cells; elsewhere pass `text-[13px]`, as the record header example does.
- The live tone is named `primary` in code, while DESIGN.md and the registry call it live.
- The pulse is Tailwind's default `animate-ping` (1s, `cubic-bezier(0, 0, 0.2, 1)`), not a Canon motion token.
- The flows table pulses its success tone (`pulse={status.tone === "success"}`). Pulse belongs to the primary live tone.

API `StatusLabel` (extends <span>):
- `tone?: "neutral" | "primary" | "success" | "warning" | "danger" | "info"` = "neutral". The state's color. `primary` is the live tone.
- `pulse?: boolean` = false. Adds the ping ring, for live states only.
- `children: React.ReactNode`. The state in one or two words.
- `className?: string`. On the outer span. `text-xs text-muted-foreground` for meta rows.

API `StatusDot` (extends <span>):
- `tone?: StatusTone` = "neutral". The state's color.
- `pulse?: boolean` = false. Adds the ping ring.
- `className?: string`. Alignment, such as `mt-1.5`.

API `StatusTone`:

### Avatar

- Level: Atom
- Category: Identity
- Status: Stable
- Import: `@oration/canon/components/avatar`
- Exports: `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarGroup`, `AvatarBadge`
- Docs: /design/components/avatar

Avatar puts a person in a circle: their photo when there is one, their initials when there isn't. It marks who owns, approved, attended or was mentioned on something, beside their name in rows, headers and comment threads, and stacks into a group when several people share a record. Circles are for people only. Agents get an Agent avatar and companies get a Monogram tile. The common mistake is an avatar standing in for a name: without the name beside it, or an accessible name on the group, nobody can tell Priya from Wen.

When to use:
- Beside a person's name in a row, cell, comment or record header: the owner of a supplier, the approver of a payment run.
- For a signed-in person's own identity in the user menu and profile settings, with their photo if they uploaded one.
- As a stack of overlapping circles for the people on a meeting, a team or an approval chain, with a `+n` count past four.
- With `AvatarBadge` for a person's presence, when a text label for the same state sits nearby.

When not to use:
- For an AI agent. Agents have a Bayer mark in a rounded tile, and a live ring on a call. Use /design/components/agent-avatar instead.
- For a company, supplier or provider. Organizations get a square letter tile, never a circle. Use /design/components/monogram-tile instead.
- For a record without a person or photo, such as a cohort or an anonymous caller. Use /design/components/identicon instead.
- As the only way to say who something belongs to in a dense table. Write the name; add the avatar if there is room. Use /design/components/table instead.

Rules:
- The Option Hue Rule: The ten categorical hues belong to select-option values and to identity tints on avatars and monogram tiles. An initials fallback may take a person's identity tint; it never takes a status color or Quiet Indigo.
- The Label-Beside-Color Rule: A presence badge is a colored dot, so it always travels with words: Available, In a meeting, Away. The dot alone doesn't say which.

Anatomy:
- Root: A round `<span>`, 32px by default (24px at `sm`, 40px at `lg`). An `::after` hairline in `--border`, blended with `mix-blend-darken` (lighten in dark), rims photos that would otherwise bleed into the page.
- Image: `AvatarImage`, a square `<img>` cropped to the circle with `object-cover`. Base UI mounts it only once the file has loaded.
- Fallback: `AvatarFallback`, shown until the image loads or when there is none: initials on Well Gray in Slate Meta, 14px (12px at `sm`). Tint it with the person's identity hue.
- Badge: Optional `AvatarBadge` at the bottom right, 8, 10 or 12px by avatar size, with a 2px ring in the plane color so it reads as cut out.

States:
- No image: The fallback renders at once with the person's initials.
- Loading: The fallback shows while the photo loads. Pass `delay` on the fallback (for example 300ms) to skip a flash of initials on a fast connection.
- Loaded: Base UI swaps in the image and unmounts the fallback. `data-[slot=avatar]` and the root's loading status are available for styling.
- Error: If the photo fails, the image never mounts and the fallback stays. Nothing breaks and no broken-image glyph appears.
- With badge: `AvatarBadge` sits in the corner. At `sm` it's a plain 8px dot and hides any icon; at default and `lg` it can hold an 8px icon.
- Grouped: Inside `AvatarGroup`, avatars overlap by 8px and each gets a 2px ring in the plane color so the edges stay legible.

Behavior:
- Base UI tracks the image's loading status on the root (`idle`, `loading`, `loaded`, `error`) and renders the image or the fallback, never both. `onLoadingStatusChange` on `AvatarImage` reports it.
- Swapping `src` restarts loading; the fallback returns until the new photo is ready.
- Avatars are not interactive. To open a profile, wrap the avatar and the name together in one link or button so there is one target with a real name.
- `AvatarGroup` is a flex row with `-space-x-2`. Tighten the overlap with `-space-x-1.5` at 24px. Later avatars sit on top of earlier ones.
- `AvatarGroupCount` matches the group's size through `group-has-data-[size=…]`, so a count next to `lg` avatars is 40px without extra props.
- The size prop sets `data-size` on the root, which the fallback and badge read to scale their text and dot.

Do and don't:
- Do: Keep the name beside the avatar, or give the group an accessible list of names.
- Don't: Show a row of initials with no names. Two people with the same initials become the same person.
- Do: Stop the stack at four and count the rest with `AvatarGroupCount`.
- Don't: Stack every attendee. The circles shrink to slivers and the row stops scanning.
- Do: Tint an initials fallback with the person's identity hue, pale fill and deep ink.
- Don't: Fill initials with Quiet Indigo or a status color. Indigo means selected or live, and red means something failed.

Content:
- Initials are two letters, first and last name: MO for Maya Okafor, TF for Tomás Ferreira. One letter only when there is one name.
- Photos use `alt=""` when the name is written beside them, and the person's name when it isn't.
- Presence labels are short states in sentence case: Available, In a meeting, Away, Offline.
- Counts read as `+3`, and the accessible text names everyone: Attendees: Maya Okafor, Priya Raman, Jordan Lee and 3 others.

Accessibility:
- The root has no role. When the name is visible beside it, hide the avatar with `aria-hidden="true"` so initials aren't read as a word (MO).
- When the avatar stands alone, give the image an `alt` with the person's name, or put an `sr-only` name next to the fallback.
- Hide an `AvatarGroup` with `aria-hidden` and put the full list of names in an `sr-only` span beside it, as the meetings list does.
- A presence badge is decorative color. Pair it with visible text, or an `sr-only` state such as , available.
- Tinted initials use the same fill and ink pairs as tags, which are drawn for 12px text. Don't set initials smaller than 11px.

Known gaps (follow the system, not the gap):
- The product rarely renders `Avatar` directly. `PersonAvatar` in `components/records/avatars.tsx` wraps it with its own 16, 20, 24, 32 and 48px ramp, a 24px default and tag tints from the record's `color`. The contact center has a second `PersonAvatar` in `components/contact-center/ui.tsx` that skips `Avatar` entirely and draws its own presence dot. Three avatar recipes coexist.
- Call sites override the root's rim to `after:border-black/5 dark:after:border-white/10` because the default `--border` rim reads heavy on tinted fallbacks.
- `AvatarGroup` and `AvatarGroupCount` ring in `--background`. On a card in dark mode that is the wrong color, so call sites add `ring-card` by hand.
- `AvatarBadge` defaults to a Quiet Indigo fill, which the Quiet Indigo Rule reserves for the viewer's own markers. It isn't used anywhere in the product; presence is drawn by hand.
- The product sets 24px fallbacks at 10px and 20px ones at 9px, under the 11px floor in The Thirteen-Fourteen Rule.
- The fallback has no weight; every call site adds `font-semibold`.
- `AvatarGroupCount` is exported but missing from the registry's export list.

API `Avatar` (extends Base UI `Avatar.Root` (`<span>`)):
- `size?: "sm" | "default" | "lg"` = "default". 24, 32 or 40px. Written to `data-size`.
- `render?: ReactElement | (props, state) => ReactElement`. Render the root as another element.
- `className?: string`. Merged last. Use it for one-off sizes such as `size-12` in profile settings.

API `AvatarImage` (extends Base UI `Avatar.Image` (`<img>`)):
- `src: string`. The photo URL.
- `alt: string`. The person's name, or `""` when the name is visible beside it.
- `onLoadingStatusChange?: (status: "idle" | "loading" | "loaded" | "error") => void`. Called as the image loads or fails.
- `keepMounted?: boolean` = false. Keeps the `<img>` mounted and loads in place, for `loading="lazy"` or `next/image`.

API `AvatarFallback` (extends Base UI `Avatar.Fallback` (`<span>`)):
- `delay?: number` = 0. Milliseconds to wait before showing the fallback, to avoid a flash while a fast photo loads.
- `children?: React.ReactNode`. Two initials, or a 16px icon.
- `className?: string`. Merged last, so tag tint classes replace Well Gray and Slate Meta.

API `AvatarBadge` (extends <span>):
- `children?: React.ReactNode`. Optional icon, drawn at 8px at default and `lg`, hidden at `sm`.
- `className?: string`. Override the fill for presence, such as `bg-success` for Available.

API `AvatarGroup` (extends <div>):
- `className?: string`. Tighten the overlap with `-space-x-1.5`; on cards use `*:data-[slot=avatar]:ring-card`.

API `AvatarGroupCount` (extends <div>):
- `children?: React.ReactNode`. The overflow count, such as `+3`, or a 16px icon.
- `className?: string`. Merged last.

### Identicon

- Level: Atom
- Category: Identity
- Status: Stable
- Import: `@oration/canon/components/identicon`
- Exports: `Identicon`, `IdenticonGroup`, `identityHue`, `identityColors`, `IDENTITY_HUES`
- Docs: /design/components/identicon

Identicon paints a small generative mark from a string, so a record without a photo or logo still has a face you can find again: a customer, a cohort, a report's author, an agent template. The same username always draws the same mark. In the suite that mark is Bayer 2x2 in the oklch-mono palette: a circle for a person, a rounded square for a group or a piece of software. It is the base of Agent avatar. The mistake to avoid is seeding it with a display name: rename the record and it becomes a stranger.

When to use:
- Beside the name of a person-like record that has no photo: a caller, a report's author. Use `shape="rounded"`.
- Beside a cohort or other group. Use `shape="square"`.
- As IdenticonGroup when several of those records share a row and a count past four.
- `identityColors(seed)` when initials or a monogram need an identity tint. That tint is separate from the mark's palette.

When not to use:
- For a teammate with a name and maybe a photo. People get initials in a circle. Use /design/components/avatar instead.
- For an AI agent. Use the agent mark, which keeps the Bayer tile and adds the live and draft rings. Use /design/components/agent-avatar instead.
- For a company, supplier or provider shown by its letters. Use /design/components/monogram-tile instead.
- As an icon for a nav item, section or feature. A generative mark reads as an identity. Use /design/foundations/iconography instead.

Rules:
- The One Pattern Rule: Records in the suite use `type="Bayer 2x2"` and `colorScheme="oklch-mono"`. A customer, a cohort and an agent share that drawing. Other generators and schemes exist on the component; mixing them in one product makes two records look like two design systems.
- The Shape Rule: Circles are people (`shape="rounded"`). Rounded squares are groups and software (`shape="square"`, 8px corners). Agent avatar overrides that corner to 10px at 32px so an agent never passes for a teammate.
- The Option Hue Rule: The mark does not use the categorical tag hues. Those stay on select-option values, identity tints for initials and monograms, and the four app marks. `identityColors` is that tint. It is not the identicon's paint.

Anatomy:
- Tile: A canvas sized by `size` in pixels. `rounded` clips it to a circle. `square` clips it with `rounded-md` (8px). `bg-muted` shows through until the bitmap is painted.
- Palette: Two colors from `colorScheme`, derived from the username. `oklch-mono` is one hue at two lightnesses. The suite does not theme these with tag tokens.
- Pattern: The generator named by `type`. Bayer 2x2 is a full-bleed dither. Every pixel is filled; there is no empty ground with a floating glyph.

States:
- Decorative: Without `aria-label`, the canvas is `aria-hidden="true"`. This is the normal case, beside a visible name.
- Labelled: With `aria-label`, the canvas is `role="img"` with that name, for a mark shown without its record.
- Empty, then painted: The server sends an empty muted tile. The bitmap is drawn on the client after mount. Light and dark do not restyle it; the colors are computed, not tokens.

Behavior:
- The username is hashed and fed to the generator, so the drawing is a pure function of the string, the type and the color scheme.
- `shape="rounded"` is `rounded-full`. `shape="square"` is `rounded-md`. A `style` border radius, as Agent avatar sets, overrides the square corner.
- The canvas is painted at `size` by `size` pixels with `imageRendering: pixelated`, which is the point of a dither and the reason smooth generators look stepped.
- It has no motion and no interaction. Wrap it with the name in a link to make the row clickable.
- IdenticonGroup overlaps marks by 8px with a 2px ring in the surface color, shows four, then a `+n` count. Each mark and the count have a tooltip with the record names.

Do and don't:
- Do: Seed with the record's stable ID, so the mark survives a rename.
- Don't: Seed with the display name. Northwind Freight and Northwind Freight LLC draw two different marks for the same supplier.
- Do: Put the mark beside the record's name, in rows, headers and pickers.
- Don't: Use identicons as icons for nav items or sections. They look like identities.
- Do: Use Bayer 2x2 and oklch-mono for every record in the suite.
- Don't: Give cohorts one generator and customers another. The shape already says which is which.

Content:
- An identicon carries no text. The name beside it does the work: Suppliers with overdue W-9s, Halcyon Logistics.
- When it stands alone, `aria-label` is the record's name as people know it, not its ID: Net 30 suppliers, not coh_4471.

Accessibility:
- Decorative by default (`aria-hidden`). Screen readers get the record from the visible name.
- Set `aria-label` only when no name is visible; it becomes `role="img"`.
- Color is never the only way to tell records apart. The name is always written.
- The mark does not move, so there is nothing to reduce for motion preferences.
- Group tooltips name the hidden records. The count is still not enough on its own: keep a written name or an accessible name on the row.

Known gaps (follow the system, not the gap):
- The bitmap is drawn in an effect, so the first server paint is an empty muted tile. The old SVG mark rendered on the server.
- `oklch-mono` picks a hue from the whole wheel, so a mark can land near Quiet Indigo. Identity tints for initials still exclude indigo; the mark does not.
- `identityColors` no longer agrees with the mark. A customer shown as a Bayer tile in one app and as tinted initials in another will not share a color.
- `size` is a number in pixels, while Avatar uses `sm | default | lg`. Call sites use 16, 18, 20, 24, 28, 36, 40 and 48.
- Smooth generators (Glass Orb and its neighbours) are painted with `imageRendering: pixelated`, so they step. Bayer is the one that wants that.
- Group tooltips open on hover. The trigger is not a button, so keyboard users don't get the hidden names from the tooltip.

API `Identicon` (extends <canvas>):
- `username: string`. A stable ID. Same username, same mark. Replaces the old `seed` prop.
- `type?: IdenticonType` = "Bayer 2x2". Which generator draws the tile. The suite uses Bayer 2x2. The full list is the exported `identiconTypes` array.
- `shape?: "rounded" | "square"` = "rounded". `rounded` is a circle, for a person. `square` is `rounded-md`, for a group or software.
- `size?: number` = 32. Width and height in pixels.
- `colorScheme?: ColorScheme` = "oklch-mono". How the two colors are picked from the username. The suite uses oklch-mono. The full list is the exported `colorSchemes` array.
- `aria-label?: string`. Makes the mark `role="img"` with this name. Leave it out beside a visible name.
- `className?: string`. Merged last, so it can override the shape.
- `style?: React.CSSProperties`. Merged after the size. Agent avatar sets `borderRadius` here.

API `IdenticonGroup`:
- `items: { id: string; label: string }[]`. `id` seeds the mark. `label` is the tooltip.
- `limit?: number` = 4. How many marks to show before the count.
- `type?: IdenticonType` = "Bayer 2x2". Passed through to each mark.
- `shape?: "rounded" | "square"` = "square". Passed through to each mark.
- `size?: number` = 24. Passed through to each mark.
- `emptyLabel?: React.ReactNode`. Rendered in muted text when `items` is empty.
- `stopPropagation?: boolean` = false. Stops click and keydown from reaching a row or card behind the group.
- `className?: string`. On the row.

API `identityHue`:

API `identityColors`:

API `IDENTITY_HUES`:

### Agent avatar

- Level: Atom
- Category: Identity
- Status: Stable
- Import: `@oration/canon/components/agent-avatar`
- Exports: `AgentAvatar`
- Docs: /design/components/agent-avatar

Agent avatar is an AI agent's face: its Bayer Identicon, seeded by the agent's ID, in a rounded tile rather than a circle, so an agent never passes for a teammate. It appears wherever an agent does work in the Agents Platform: lists, call pills, transcripts, run history and the agent's own header. Two states add a ring: a breathing indigo ring while the agent is on a call, and a dashed ring while it is a draft. The ring is color and motion, so the words for the state still belong beside it.

When to use:
- Beside an agent's name in lists, tables, pickers and transcripts: Payment status line, W-9 collection.
- With `state="live"` while the agent is on a call, in the live calls list, the call pill and the agent header.
- With `state="draft"` for agents that have never been published.
- With `labelled` when the mark stands alone, such as a stack of agents on a campaign, so screen readers get the name and state.

When not to use:
- For a person on the support team or a supplier contact. Use /design/components/avatar instead.
- For a customer, cohort or report with no agent behind it. Use /design/components/identicon instead.
- To show that a voice session is listening, thinking or speaking. Use /design/components/voice-orb instead.
- As the only signal that an agent is live in a dense list. Add the words. Use /design/components/status-label instead.

Rules:
- The Quiet Indigo Rule: The live ring is indigo because indigo is spent on live state that carries a label. It is the only color the avatar adds. The mark itself stays in its Bayer palette.
- The Label-Beside-Color Rule: The ring alone doesn't say On a call. The component speaks the state to screen readers; sighted people need a status label, a count (2 on calls now) or a waveform beside it.

Anatomy:
- Tile: A Bayer identicon seeded by `agent.id`, with a corner of 10px at 32px that scales with size (never under 4px). It is a rounded square, never a circle.
- Live ring: A static Quiet Indigo border around the tile, 1.5px (2px from 40px), set off by a 2px gap (1.5px under 28px). Only when `state="live"`.
- Breathing ring: A copy of the live ring that grows to 1.16x and fades from 50% to nothing, then rests 0.4s. Skipped under reduced motion.
- Draft ring: A dashed 1.5px ring in Graphite Ink at 40%, in the same place, when `state="draft"`.

States:
- Idle: The tile alone. Published agents not on a call.
- Live: The indigo ring, breathing every 2.2s. Spoken as On a call.
- Live, reduced motion: The static indigo ring only. `useReducedMotion` removes the breathing copy.
- Draft: The dashed ring. Spoken as Draft.

Behavior:
- `data-state` on the root carries `idle`, `live` or `draft` for styling from outside.
- The rings are absolutely positioned outside the tile, so the avatar's box stays `size` by `size` and rows don't shift when a call starts. Leave about 4px around it.
- The breathing ring animates `opacity` and `transform` only, 1.8s on the house curve `cubic-bezier(0.23, 1, 0.32, 1)`, repeating after a 0.4s rest.
- Without `labelled`, the state is an `sr-only` word (On a call, Draft) inside the avatar and the tile is hidden, so the visible name beside it names the agent.
- With `labelled`, the root is `role="img"` with an `aria-label` such as Payment status line, on a call, and the `sr-only` word is dropped.
- The avatar isn't interactive. Wrap it and the name in one link or button to open the agent.

Do and don't:
- Do: Say the live state in words beside the ring: a status label, a call count or a waveform.
- Don't: Rely on the ring alone in a list. In grayscale, or with motion off, it is a thin outline that says nothing.
- Do: Draw agents with the agent mark, so they read as software at a glance.
- Don't: Draw an agent as initials in a circle. It reads as a teammate, and people will expect it to answer a message.

Content:
- Agent names are what the agent does, in sentence case: Payment status line, W-9 collection, Vendor onboarding.
- The spoken states are fixed: On a call for live and Draft for draft. Visible labels use the same words.
- Counts beside a live agent are specific: 2 on calls now, not Active.

Accessibility:
- Beside a visible name, leave `labelled` off. The name is read from the text and the state from the `sr-only` word.
- Alone, set `labelled` so the mark is `role="img"` with the agent's name and state.
- The breathing ring stops under `prefers-reduced-motion`; the static ring stays so the state is still drawn.
- The indigo ring is 1.5 to 2px against the plane with a gap, which holds up at every size from 16px. It isn't the only cue: the state is always spoken.

Known gaps (follow the system, not the gap):
- A second `AgentAvatar` lives in `apps/web/src/components/records/avatars.tsx`: a sparkle icon on a tag tint, used through `ActorAvatar` across the CRM. Agents look different in the CRM and in the Agents Platform.
- Without `labelled`, the `sr-only` state word is inside the avatar, so it is read before the name: On a call Payment status line.
- The breathing loop (1.8s plus 0.4s) runs outside the spring tokens and the 320ms ceiling in the motion grammar. It is ambient, like the status label's pulse, but it isn't a Canon token.
- Rows in the Home live calls list write the caller's name but not the agent's, and don't set `labelled`, so the agent is identified by its mark alone and screen readers hear only On a call.

API `AgentAvatar`:
- `agent: { id: string; name: string }`. `id` seeds the mark; `name` is used for the label when `labelled` is set.
- `size?: number` = 32. Pixels. The corner is `size * 10 / 32`; ring width and gap step up at 28 and 40px.
- `state?: "idle" | "live" | "draft"` = "idle". Adds the live or draft ring and its spoken word.
- `labelled?: boolean` = false. Makes the avatar `role="img"` named for the agent and state, for use without a visible name.
- `className?: string`. On the root span.

### Logo

- Level: Atom
- Category: Identity
- Status: Beta
- Import: `@oration/canon/components/logos`
- Exports: `Logo`, `logos`, `LOGO_NAMES`
- Docs: /design/components/logo

Logo draws a brand mark or its wordmark from the original SVG, at a fixed optical size. Multicolor marks such as Microsoft and Google keep their own inks in both themes. A one-ink mark such as GitHub is painted with `currentColor`, so it turns with the text. Recolor a mark only when the surface cannot hold the brand colors.

When to use:
- Beside a provider action, such as Continue with Google, at 16px.
- In a row of products a customer already uses, marks at 16px or wordmarks at 16px tall.
- For Oration's own mark and wordmark once those files are added the same way.

When not to use:
- For a company that has no logo file yet. A letter tile is the stand-in, and it is never a fake brand mark. Use /design/components/monogram-tile instead.
- For a person, where a photo or initials belong. Use /design/components/avatar instead.
- For an agent. Agents use the Bayer mark in a rounded tile, not a company logo. Use /design/components/agent-avatar instead.

Rules:
- Original ink, unless the surface refuses it: A multicolor mark stays in brand color on white, on a card, and on a dark well. Switch to mono, light, or dark only for a one-ink lockup, or when the brand colors fail on that surface.

Anatomy:
- Mark: The symbol, square, 16px by default. Microsoft's four squares, Google's G, GitHub's octocat.
- Wordmark: The name as a drawing, 16px tall and as wide as the file. Google and GitHub have one. Microsoft, on SVGL, does not.
- Tone: Brand keeps the file's fills. Mono, light, and dark repaint every shape: currentColor, graphite `#1b1f24`, or white.

States:
- Brand: The default. Multicolor fills stay. A one-ink file uses currentColor and follows the surrounding text, including inside `.dark`.
- Mono: Every shape takes currentColor. Use it when a multicolor mark has to sit in one ink, matching a label.
- Light: Graphite ink, for a light background, including when the page around it is dark.
- Dark: White ink, for a dark background that does not change the text color.

Behavior:
- The drawing is the SVG you saved. Paths are not redrawn. `bun run add-logo` in `packages/canon` copies a file, or downloads a title from SVGL, into `src/components/logos/svg/` and regenerates `assets.ts`.
- A light file and a dark file of the same one-ink mark collapse into one drawing in currentColor. The dark original stays next to it as `*.dark.svg`.
- Two multicolor drawings that actually differ are both kept, and the dark one shows under `.dark`.
- Pass `decorative` when the name is already in the adjacent text, so the mark is hidden from assistive tech. Otherwise the SVG is `role="img"` with the brand name.
- A wordmark's class list includes `size-` so a button's `[&_svg:not([class*='size-'])]:size-4` does not squash it. Override the height with `className="h-5"` or `h-6`.

Do and don't:
- Do: Use the brand tone for Microsoft and Google on both light and dark surfaces.
- Don't: Repaint a multicolor mark white or black just because the page is dark. The four colors are the mark.
- Do: Let GitHub follow the text color, and pass decorative when the button already says GitHub.
- Don't: Leave a black octocat on a dark well, or announce the name twice to a screen reader.

Content:
- Don't set a title that restates a visible label. `Continue with Google` next to the mark is enough: pass `decorative`.
- When the mark is the only name, leave the default title, which is the brand.

Accessibility:
- With the default, the SVG has `role="img"` and `aria-label` set to the brand, or to `title` when you pass one.
- `decorative` sets `aria-hidden` and removes the label. Use it when adjacent text names the brand.
- The mark is not a control. The button or link around it takes the click.
- Tone light and tone dark are forced inks, so they stay readable when they sit on the opposite surface.

Known gaps (follow the system, not the gap):
- Microsoft has a mark only. SVGL does not ship a Microsoft wordmark.
- The Google symbol in the catalog is the standard four-color G. SVGL's Google symbol is a filtered reconstruction that blurs at 16px, so it is not the file we render. The Google wordmark is the SVGL original.

API `Logo` (extends <svg>):
- `name: LogoName`. Catalog key: `microsoft`, `google`, or `github`. `LOGO_NAMES` lists them.
- `variant?: "mark" | "wordmark"` = "mark". The symbol, or the name drawn as a wordmark.
- `tone?: "brand" | "mono" | "light" | "dark"` = "brand". Brand keeps original fills. Mono uses currentColor. Light is graphite. Dark is white.
- `title?: string`. Accessible name. Defaults to the brand title in the catalog.
- `decorative?: boolean` = false. Hides the mark from assistive tech.
- `className?: string`. Size override. Marks default to `size-4` (16px). Wordmarks default to `h-4`. Example: `className="size-6"`.

### Monogram tile

- Level: Atom
- Category: Identity
- Status: Beta
- Import: `@oration/canon/components/monogram-tile`
- Exports: `MonogramTile`
- Docs: /design/components/monogram-tile

Monogram tile is a company's initials in a rounded square on a pale tag tint: suppliers, customers' companies, integrations, SSO and AI providers, teams and workspaces. It is Oration's stand-in for a logo, and it stays neutral on purpose: provider names such as Deepgram or Twilio appear as letter tiles, never as their brand marks. The square shape is the point. Circles are people, tiles are organizations, so keep the two apart.

When to use:
- Beside a company or supplier name in rows, cells, cards and record headers: Northwind Freight, Halcyon Logistics.
- For integrations and AI or telephony providers in settings and pickers, in `gray` so no provider looks endorsed.
- For teams and a workspace without an uploaded logo, in the record's own tag color.
- At `xs` inline in running text, such as an approval that names the supplier.

When not to use:
- For a person, even one who represents a company. Use /design/components/avatar instead.
- For an AI agent. Use /design/components/agent-avatar instead.
- For records with no meaningful letters, such as cohorts or anonymous callers. Use /design/components/identicon instead.
- For a category or value of a record, such as a supplier's tier. Use /design/components/tag instead.

Rules:
- The Option Hue Rule: Tag hues belong to select-option values and to identity tints on avatars and monogram tiles. The tile's color identifies the company; it never encodes status, risk or a category.
- No brand logos: Providers and partners are shown as neutral letter tiles, never with their logos or brand colors. It keeps screens calm and avoids implying endorsements Oration hasn't made.

Anatomy:
- Tile: A square from 16 to 48px with corners that step with size: 4, 5, 8, 10 and 12px.
- Tint: The tag fill for `color` (`--tag-{color}`), with an inset 1px outline of black at 5% (white at 10% in dark) so pale tiles keep their edge.
- Initials: Semibold, tight tracking, in the tag's deep ink. Two letters from `md` up, one at `xs` and `sm`.

States:
- Static: A monogram has no interactive states. Hover and focus belong to the row or card that holds it.
- One letter: At `xs` and `sm`, or when the name is one word: Halcyon is H.
- Neutral: `color="gray"` for providers and integrations, so no brand stands out.

Behavior:
- Initials come from the first letter of the first two words. A standalone `&` is skipped, so Baker & Lowe Supply is BL.
- Characters other than A to Z, spaces and `&` are stripped before the initials are taken, so digits and punctuation never show.
- The tile is always `aria-hidden`; the name beside it is what people and screen readers read.
- It renders a `<span>`, so it sits inline with text at `xs` and aligns with `items-center` in rows.

Do and don't:
- Do: Show providers as gray letter tiles with the provider's name beside them.
- Don't: Recreate a provider's logo or brand color. It looks like an endorsement and breaks the calm of the page.
- Do: Use a square tile for a company and a circle for a person.
- Don't: Put a company's initials in a circle. It reads as a teammate named NF.

Content:
- Pass the name people know, not the legal entity: Northwind Freight, not Northwind Freight Holdings, LLC.
- When a name starts with a digit or symbol, the tile skips it: 3PL Direct draws PD. Check that the letters still make sense.
- Keep the name visible beside the tile. The letters alone don't identify a company.

Accessibility:
- Always `aria-hidden`. There is no `title` prop, so never use a tile without the company's name next to it.
- The tag fill and deep ink pairs are the ones tags use for 12px text. At `xs`, `sm` and `md` the letters are 8 to 10px, so treat them as a shape, not as text anyone must read.
- No motion and no focus.

Known gaps (follow the system, not the gap):
- Initials at `xs`, `sm` and `md` are 8, 9 and 10px, under the 11px floor in The Thirteen-Fourteen Rule.
- The 4px and 5px corners at `xs` and `sm` are outside the 6, 8, 10 and 12px radius ramp.
- Initials strip every character outside A to Z, so accented first letters vanish: Émile Roux becomes MR and Ørsted becomes R.
- There is no `title` or label prop, so the tile can't be used on its own accessibly.
- `color` is always passed by hand from the record. There is no seed option, while Avatar and the contact center derive tints from `identityColors(seed)`, and `indigo` is allowed here but excluded from `IDENTITY_HUES`.
- Most of the product imports it through `apps/web/src/components/records/avatars.tsx`, which re-exports it and wraps it as `CompanyLogo`, and duplicates its tint and size maps for its own avatars. The adoption count on this page undercounts real use.

### Progress

- Level: Atom
- Category: Feedback
- Status: Beta
- Import: `@oration/canon/components/progress`
- Exports: `Progress`, `ProgressTrack`, `ProgressIndicator`, `ProgressLabel`, `ProgressValue`
- Docs: /design/components/progress

Progress is a 4px Ink 65 bar on a Well Gray track that shows how much of a task with a known size is done: an import, an export, a payment run going out, a test suite running. It is built on Base UI Progress, so it is announced as a progress bar with its value, and its label and value are wired up for you. It measures work in motion; for a level against a limit, such as credits or seats, use Meter. It has no indeterminate animation, so when the size of the work is unknown, reach for a spinner instead of a bar that sits empty.

When to use:
- For a task whose total is known and that finishes in front of the person: Importing 1,208 suppliers, Sending 212 payments.
- With a label and a value above the bar, in a dialog, sheet or settings section while the work runs.
- In a table cell or card, with an `aria-label`, for runs that are still going: a payment run's sent count, a campaign's dialed count.

When not to use:
- For a quantity measured against a limit or target, such as credits used or occupancy. Use /design/components/meter instead.
- For work of unknown length. The bar has no indeterminate animation. Use /design/components/spinner instead.
- For an AI model thinking or generating. Use /design/components/ai-loader instead.
- For steps a person moves through, such as an onboarding flow. Use /design/components/stepper instead.
- For content that is loading into a layout. Use /design/components/skeleton instead.

Rules:
- The Ink Fill Rule: Magnitudes are drawn in ink steps on a Well Gray track, and progress is Ink 65. The fill is never indigo, and it doesn't turn green on completion: finishing isn't a verdict, the words say it.
- The Label-Beside-Color Rule: A bar alone doesn't say what is progressing or how far. Pair it with a label (Importing 1,208 suppliers) and a value (42% or 89 of 212).

Anatomy:
- Label: `ProgressLabel`, 14px medium, linked to the bar with `aria-labelledby`. Says what is running.
- Value: `ProgressValue`, pushed right with `ml-auto`, 14px Slate Meta in tabular figures. A formatted percent by default.
- Track: A 4px round Well Gray track at full width, wrapping onto its own line under the label and value.
- Indicator: Ink 65 (`bg-foreground/65`), its width set by Base UI as a percentage and eased over 300ms.

States:
- Empty: `value={0}`. The track alone, with the value at 0%.
- Progressing: `data-progressing` on every part. The fill grows over 300ms on the house ease-out each time the value changes.
- Complete: `data-complete` once `value` reaches `max`. The fill stays Ink 65; change the label to say it finished.
- Indeterminate: `value={null}` sets `data-indeterminate` and drops `aria-valuenow`, but nothing moves: the indicator collapses and the track sits empty.

Behavior:
- `Progress` renders its children first, then its own track and indicator, in a wrapping flex row. Put `ProgressLabel` and `ProgressValue` inside it; the track drops to the next line at full width.
- `value` runs from `min` (0) to `max` (100). Base UI clamps it and writes `aria-valuenow`, `aria-valuemin` and `aria-valuemax`.
- `ProgressValue` shows the value through `Intl.NumberFormat`: a percent by default, or whatever `format` and `locale` say. Pass a function as its child to write your own text, such as 89 of 212 invoices.
- `getAriaValueText` sets what screen readers hear for the value, so the spoken and visible text can match.
- The width transition is 300ms on `--ease-out` (`cubic-bezier(0.23, 1, 0.32, 1)`). Updates faster than that read as one smooth fill.
- State attributes (`data-progressing`, `data-complete`, `data-indeterminate`) are on the root, track, indicator, label and value, for styling from outside.

Do and don't:
- Do: Draw the fill in Ink 65, the same ink as every other magnitude.
- Don't: Fill it indigo or green. Indigo means selected or live, and green says something passed.
- Do: Say what is running and how far along it is, above the bar.
- Don't: Show a bare bar. Nobody knows what it measures or whether 60% is good news.

Content:
- The label names the work in progress with a count: Importing 1,208 suppliers, Sending 212 payments.
- When it finishes, the label says so in the past tense: Import finished, 212 payments sent.
- Prefer counts to percents when the unit matters: 89 of 212 invoices tells more than 42%.
- Don't promise time you can't measure. Leave out About 2 minutes left unless the estimate is real.

Accessibility:
- Base UI renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext`, and links `ProgressLabel` with `aria-labelledby`.
- Without a visible label, give the root an `aria-label`: Friday freight run, payments sent.
- Screen readers don't announce every change of a progress bar. Announce the start and the finish in a `role="status"` region or a toast.
- The width transition is short and only moves the fill; it isn't disabled under reduced motion.

Known gaps (follow the system, not the gap):
- Indeterminate draws nothing. With `value={null}` the indicator has no width and the track sits empty, with no animation.
- `Progress` always appends its own track, so `ProgressTrack` and `ProgressIndicator` can't be used to rearrange the parts inside it without rendering two tracks.
- Label and value default to 14px, while DESIGN.md sets dense UI at 13px. The one product call site overrides both with `text-13`, which `cn` from the `cn` package keeps alongside `text-sm`, so the rendered size depends on stylesheet order.
- It is used only in the import and export settings. The evaluation live run panel and the knowledge document meta draw their own `role="progressbar"` bars by hand.

API `Progress` (extends Base UI `Progress.Root` (`<div>`)):
- `value: number | null`. The current value. `null` is indeterminate.
- `min?: number` = 0. The value at an empty bar.
- `max?: number` = 100. The value at a full bar. Use the real total, such as 212.
- `format?: Intl.NumberFormatOptions`. How `ProgressValue` and the default value text format the value.
- `locale?: Intl.LocalesArgument`. Locale for formatting. Defaults to the runtime locale.
- `getAriaValueText?: (formattedValue: string, value: number | null) => string`. Sets the spoken value.
- `children?: React.ReactNode`. `ProgressLabel` and `ProgressValue`.
- `className?: string`. On the root, merged after `flex flex-wrap gap-3`.

API `ProgressLabel` (extends Base UI `Progress.Label` (`<span>`)):
- `className?: string`. Merged after `text-sm font-medium`. Use `text-[13px]` in dense layouts.

API `ProgressValue` (extends Base UI `Progress.Value` (`<span>`)):
- `children?: (formattedValue: string | null, value: number | null) => React.ReactNode`. Write your own value text. Defaults to the formatted value.
- `className?: string`. Merged after `ml-auto text-sm text-muted-foreground tabular-nums`.

API `ProgressTrack` (extends Base UI `Progress.Track` (`<div>`)):
- `className?: string`. Merged last.

API `ProgressIndicator` (extends Base UI `Progress.Indicator` (`<div>`)):
- `className?: string`. Merged last.

### Meter

- Level: Atom
- Category: Data display
- Status: Stable
- Import: `@oration/canon/components/meter`
- Exports: `Meter`, `MeterSegment`
- Docs: /design/components/meter

Meter is a round Well Gray track with an ink fill that shows a quantity against a limit: credits used this period, seats taken, a payment run's paid and scheduled totals, a forecast against its target. Pass `value` for one Ink 65 fill, or `segments` for a stack of ink steps, and `target` for a marker. It measures a level, not work in motion; for a task that finishes, use Progress. The mistake people make is coloring it: the fill stays ink unless the value is itself a verdict, and the words and figures beside it say what it means.

When to use:
- For a used-of-total figure with a real limit: 18,420 of 25,000 credits used, 18 of 25 seats.
- With `segments` to break one total into two or three parts, such as a payment run's paid, scheduled and awaiting approval amounts, with a legend underneath.
- With `target` to show a figure against a goal: straight-through processing against 80%, a quarter's forecast against its number.
- In table cells and rails at `sm` beside a tabular value, for per-row shares such as an approver's queue.
- With a semantic `tone` only when the value is a verdict, such as password strength or a failing score.

When not to use:
- For a task that runs and finishes, such as an import or a payment run going out. Use /design/components/progress instead.
- For a trend over time. A meter is one moment. Use /design/components/mini-chart instead.
- For a single percentage that reads better as a ring on a dashboard tile. Use /design/components/radial-chart instead.
- For status history over periods, such as a sync's uptime by day. Use /design/components/health-bar instead.
- For comparing more than three parts or many categories. A stack past three segments is a chart. Use /design/components/chart instead.

Rules:
- The Ink Fill Rule: Magnitudes are drawn in ink steps (80, 65, 45, 25, 15) on a Well Gray track. A single fill is Ink 65; a three-part stack is Ink 80, 45 and 15. A fill turns semantic only when the value is itself a verdict, such as a strong password in Ledger Green. It is never indigo.
- The Label-Beside-Color Rule: The bar is the picture; the figure is the fact. Put the value in words beside it (18 of 25 seats), and give every segment a legend entry with its tabular value.
- The Tabular Figures Rule: The value, the limit and every legend figure are set in tabular figures, so they line up across rows and don't jitter as they change.

Anatomy:
- Track: The root: a full-width Well Gray bar with round ends, 4, 6 or 10px tall. Carries `role="meter"` and the ARIA values.
- Fill: With `value`, one round Ink 65 fill (or the tone color) clipped to the track, its width a percentage of `max`.
- Segments: With `segments`, flat fills laid end to end in order. Each takes its color from its own `className`; set ink steps.
- Target marker: A 2px Graphite Ink bar with a 2px card-colored ring, 4px past the track top and bottom, at `target`.
- Value and legend: Not part of the component. The figure above it in Body Dense tabular, and for stacks an 8px square swatch, a label and a tabular value per segment.

States:
- Empty: `value={0}`. The track alone. Say None used beside it rather than hiding the meter.
- Partial: The fill covers `value / max` of the track.
- Full: At or over `max` the fill is clamped to the whole track. `aria-valuenow` still reports the real total, so say Over by 1,200 in words.
- Against a target: The marker sits at `target` whether the fill has passed it or not. Label the target in 11px Footnote under it.
- Verdict: `tone` of `success`, `warning` or `danger` swaps the single fill to Ledger Green, Amber or Signal Red. Segments ignore tone when they set their own class.
- Changing: Width changes animate over 500ms on the house ease-out, the one fill allowed past 320ms.

Behavior:
- `max` is required. Every width is `value / max`, clamped between 0% and 100%.
- With `segments`, each segment's width is its own `value / max`, laid left to right in array order. `aria-valuenow` is their sum.
- `value` is ignored when `segments` is passed.
- A segment without a `className` falls back to the tone color, so an unstyled stack reads as one bar. Give each segment an ink step.
- The target is `aria-hidden`; say what it is in text nearby.
- The track is `overflow-visible` so the target marker can extend past it; the fills sit in an inner clipping layer with round ends.
- Width transitions are 500ms on `--ease-out` (`cubic-bezier(0.23, 1, 0.32, 1)`), so a changing value glides rather than jumps.
- Rest props spread onto the root after the ARIA attributes, so `aria-valuetext` or `id` pass straight through.

Do and don't:
- Do: Fill with ink steps: Ink 65 for one value, Ink 80, 45 and 15 for a stack.
- Don't: Fill with indigo or categorical hues. Indigo is for selection and the primary action, and hues turn a quantity into categories.
- Do: Put the figure in words beside the bar: 18 of 25 seats, 7 left.
- Don't: Show a bare bar. Nobody can read 72% off a track, and the limit is invisible.
- Do: Use a tone only when the value is a verdict, such as password strength.
- Don't: Color a plain quantity by how full it is. Seats used aren't good or bad, and green for a nearly full plan reads as a pass.

Content:
- Lead with the used figure and the limit in tabular figures: 18,420 of 25,000 credits used.
- Add the remainder and the reset when there is one, in Slate Meta: 6,580 left. Resets Oct 14.
- The `label` prop is what screen readers hear. Write the full sentence: 18 of 25 seats used, not Seats.
- Legend entries are the segment's name and its value, in the same order as the stack: Paid $842,300.
- Label a target by what it is and its figure: Target 80%, Q3 number $2.4M.

Accessibility:
- The root is `role="meter"` with `aria-label`, `aria-valuemin={0}`, `aria-valuemax` and `aria-valuenow`. Support for the ARIA 1.2 meter role varies; some screen readers announce it as a progress bar or read only the name, so repeat the figure in visible text.
- Pass `aria-valuetext` for units: 18,420 of 25,000 credits. Without it the number is read bare.
- The target marker is `aria-hidden`; state the target in text.
- Segments are not announced individually. The legend carries each part in text.
- Ink steps invert with the theme, so the stack keeps its contrast in dark mode. Don't rely on the lightest step alone to carry a meaning.
- The width transition only moves the fill and isn't turned off under reduced motion.

Known gaps (follow the system, not the gap):
- Usage settings stack credits in `bg-chart-1`, `bg-chart-2` and `bg-chart-3` (graphite, teal and amber) with round legend dots. DESIGN.md asks for ink steps and 8px square swatches. The forecast on Home follows the rule.
- Contact center ships its own `Meter` in `contact-center/ui.tsx` that takes a 0 to 1 value and no `max`; its roster, queue, disposition and wrap-up views use that one instead.
- Segments that add up past `max` aren't scaled down: each is clamped on its own and the overflow is clipped, so the last segments disappear without a sign.
- The target's ring is `ring-card`. On a tint well or the rail it draws a white halo instead of matching the surface.
- Segments are keyed by `label`, so two segments with the same label collide.

API `Meter` (extends `<div>` (all props except `children`)):
- `max: number`. The limit. Widths are a share of it.
- `label: string`. The accessible name, set as `aria-label`.
- `value?: number` = 0. A single fill. Ignored when `segments` is set.
- `segments?: MeterSegment[]`. A stacked fill, left to right. Their sum is the value.
- `target?: number`. Draws a marker at this value.
- `size?: "sm" | "default" | "lg"` = "default". Track height: 4, 6 or 10px.
- `tone?: "success" | "warning" | "danger" | "neutral"` = "neutral". Fill color. `neutral` is Ink 65. The others are for verdicts only.
- `className?: string`. On the track, merged last. Use it for width and margin.

API `MeterSegment`:
- `value: number`. Its size, in the same units as `max`.
- `label: string`. Its name. Also the React key, so keep it unique.
- `className?: string`. Its fill, such as `bg-ink-80`. Falls back to the tone color.

### Animated number

- Level: Atom
- Category: Data display
- Status: Stable
- Import: `@oration/canon/components/animated-number`
- Exports: `AnimatedNumber`
- Docs: /design/components/animated-number

Animated number is a tabular figure that turns its digits to a new value when the value changes, built on `@sfinterface/numbers`. Each digit is a strip behind a fixed window, and only the columns whose digit moved turn, in the direction the number went. It is for numbers that move because of something the person just did: a tab count after a filter, a credit budget while a slider drags, a payment run total as invoices are added. It inherits face, size, weight and color from its surroundings, so it drops into a stat, a tab or a sentence. The mistake is using it for decoration: it only animates on change, and a figure that never changes should be plain text.

When to use:
- For a count or total that updates in place after an action: tab counts after a bulk change, About 1,240 suppliers as filters toggle.
- Beside a slider or stepper, so the figure keeps up with the thumb: a monthly credit budget, a payment threshold.
- For live counters that tick while the person watches: credits left, calls in queue, invoices processed today.
- With `format` for currency, percents and compact notation, so the formatting stays right as it turns.

When not to use:
- For numbers that are read once and never change on screen, such as table cells or a record's created date. Use plain text with `tabular-nums`.
- For a headline figure with a label, a delta and a trend. Use /design/components/stat instead.
- For a level against a limit, where the picture matters more than the digits. Use /design/components/meter instead.
- For text that streams in, such as a model's reply. Use /design/components/streaming-text instead.
- For a short label that changes, such as Pause to Resume. Use /design/components/text-swap instead.

Rules:
- The Tabular Figures Rule: Every number that changes or gets compared is set in tabular figures. Animated number sets `tabular-nums` for you, so digits keep their width while they turn and columns stay aligned.
- Motion grammar: Movement explains a change; it never decorates. Numbers animate only when their value changes in front of the person, never on load, and reduced motion swaps them instantly.
- The Roll Rule: Figures use the default `roll` transition, the only one that turns through the digits in between and so shows how far the number moved. `tick`, `blur`, `flip` and `scale` exist in the library but aren't part of the house grammar.

Anatomy:
- Prefix: Optional node before the digits, such as `+` on a delta. It sits in the same inline box, so it stays against the digits as columns come and go.
- Digit column: A strip of digits behind a window one cell tall. Only columns whose digit changed turn, each by its own distance, on one clock.
- Symbols: Currency signs, group separators, decimal points and percent signs from `format`. They don't turn; they enter and leave as the width changes.
- Suffix: Optional node after the digits. Keep units in a muted span beside it when they shouldn't be read as part of the figure.

States:
- First render: The formatted value is in the server markup and drawn statically. Nothing animates on mount.
- Increasing: Changed columns turn forward over 450ms on the house drawer curve, `cubic-bezier(0.32, 0.72, 0, 1)`. Counting up out of 9 goes forward to 0, not back through eight digits.
- Decreasing: Columns turn the other way, so direction reads without an arrow.
- Fast turns: A column that travels far defocuses slightly while it moves, as deep as it travels, and the window's soft edge reaches further mid-turn.
- Entering and leaving columns: A digit or separator that appears or disappears (999 to 1,000) comes and goes over 240ms.
- Reduced motion: With `prefers-reduced-motion: reduce`, columns don't turn, blur or fade. The new value replaces the old one instantly.

Behavior:
- Renders one inline `<span>` of plain DOM, no shadow root. Style it through `className` and the parent: face, size, weight, color and tracking are inherited.
- The stylesheet is imported once at the top of canon's `globals.css`, ahead of Tailwind, so its `arc` layer sits below every utility.
- `locale` defaults to `en-US`, so grouping is `1,184,250`. Pass another locale, such as `"en-IN"` or `"ar-EG"`, to get its grouping and digits.
- `format` takes any `Intl.NumberFormat` options: `{ style: "currency", currency: "USD" }`, `{ style: "percent" }`, `{ notation: "compact" }`, `{ maximumFractionDigits: 1 }`.
- Turns run 450ms on the library's default curve, which is the house drawer curve. Pass `duration` only with a reason.
- `trend` is `"auto"` by default, so direction comes from the change. Force `"up"` or `"down"` when a value wraps, such as a countdown that resets.
- Every other prop, including `id`, `title` and `aria-*`, is spread onto the root span, and `ref` reaches it.

Do and don't:
- Do: Animate a figure that changes because of the person's action, such as the counts on view tabs after a bulk update.
- Don't: Swap every figure in a table or card for an animated number. Values that never change add thirty cells per digit and nothing else.
- Do: Use `format` for money and percents, so decimals, signs and grouping stay correct as the value turns.
- Don't: Build the display by hand with `prefix="$"`. Cents lose their trailing zero and negatives come out as $-1,200.

Content:
- Keep units outside the number in a muted span when they don't change: 2,500 credits, not a suffix read with it.
- Use `prefix` for a sign on a delta (+12) and `suffix` for a unit that belongs to the figure (42% from `format` is better than a `%` suffix).
- Say when a count is an estimate in the words around it: About 1,240 suppliers match.
- Round to what people act on. `{ notation: "compact" }` for large totals in tight spaces ($1.2M), full figures where amounts are reconciled.

Accessibility:
- The digit strips are `aria-hidden`, and one formatted string sits behind them with the prefix and suffix, so it is read as one value rather than digit by digit.
- Pass `label` when the figure needs words a screen reader should hear instead, such as 1,204 invoices captured.
- Changes aren't announced. When a new value matters to someone who can't see it, put it in a polite live region or say it in a toast.
- Under reduced motion the new value appears at once; there is no turn, blur or fade.
- Tabular figures keep the width steady, so surrounding text doesn't jump while digits turn.

Known gaps (follow the system, not the gap):
- The turn runs 450ms. DESIGN.md caps state changes at 320ms; the roll is listed as a sanctioned long run.
- `@sfinterface/numbers` is pre-1.0 and pinned to an exact version, because its props and motion still change between releases.

API `AnimatedNumber` (extends `NumbersProps` from `@sfinterface/numbers`, so every span attribute reaches the root.):
- `value: number`. The number to show. Changing it starts the turn.
- `format?: Intl.NumberFormatOptions`. How the number is formatted, such as currency or percent.
- `locale?: string | string[]` = "en-US". Passed to `Intl.NumberFormat`.
- `prefix?: ReactNode`. Before the digits, read with the value.
- `suffix?: ReactNode`. After the digits, read with the value.
- `trend?: "auto" | "up" | "down"` = "auto". Which way the columns turn.
- `duration?: number` = 450. Milliseconds for one turn.
- `label?: string`. What a screen reader hears instead of the formatted value.
- `className?: string`. Merged after `tabular-nums`. Use it for weight and color.

### Icon swap

- Level: Atom
- Category: Content
- Status: Stable
- Import: `@oration/canon/components/icon-swap`
- Exports: `IconSwap`
- Docs: /design/components/icon-swap

Icon swap cross-fades between the icons of one control as its state changes: copy to check, play to pause, an empty star to a filled one, a spinner to a check. Both icons share one grid cell, so the swap never shifts the button or the text beside it. It animates only when `swapKey` changes, so the mistake is changing the icon without changing the key, which snaps it. It is purely visual: the control around it still has to say its state in words.

When to use:
- For a confirmation that replaces the action's icon for a moment: Copy to a check after copying an invoice number.
- For a toggle whose icon shows its state: favorite, play and pause, show and hide a password.
- For a short task that ends in a result in the same spot: a spinner while a domain is checked, then a check.
- For a checklist item that flips from an empty circle to a check as a requirement is met.

When not to use:
- For a ready-made copy action with its tooltip and timing. Use /design/components/copy-button instead.
- For an icon button with a pressed state and tooltip built in. Use /design/components/icon-action instead.
- For a button that shows progress while it saves. The label stays and a spinner sits on top. Use /design/components/pending-button instead.
- For a status that needs words, such as a supplier's sync state. Use /design/components/status-label instead.
- For two states of one line icon: a menu to a close, a plus to a minus, a chevron flipping. The strokes move instead of cross-fading. Use /design/components/icon-morph instead.
- For the label beside the icon. Swap it with Text swap, keyed on the same state. Use /design/components/text-swap instead.
- For decorative motion on hover or load. Icons change only when state does.

Rules:
- Motion grammar: Movement explains a change. The swap runs on a 0.3s spring with no bounce, only on a state change, never on mount, and only animates opacity, scale and blur.
- The Label-Beside-Color Rule: An icon alone doesn't carry state. The control says it in words: `aria-pressed`, an `aria-label` that changes, a tooltip, or a label beside it.

Anatomy:
- Cell: An `inline-grid` span that centers its children and stacks them in one grid area, so the outgoing and incoming icons overlap exactly.
- Outgoing icon: Fades out, shrinks to 0.25 and blurs by 4px, popped out of layout so it doesn't push anything.
- Incoming icon: Fades in from 0.25 scale and 4px blur to full size and sharp.

States:
- Rest: One icon, no motion. The first render never animates.
- Swapping: When `swapKey` changes, the old icon exits and the new one enters at the same time on a 0.3s spring with no bounce.
- Same key: If the children change but `swapKey` doesn't, the icon is replaced with no animation.
- Reduced motion: Under the app's `MotionConfig reducedMotion="user"`, the scale is dropped and the icons fade.

Behavior:
- `swapKey` is turned into a string and used as the React key of the animated span. Change it whenever the icon should change, and pass the icon for the current state as `children`.
- `AnimatePresence` runs with `initial={false}`, so nothing animates on mount, and `mode="popLayout"`, so the exiting icon leaves the layout at once.
- Enter and exit are opacity 0 to 1, scale 0.25 to 1 and blur 4px to 0, on a spring with `duration: 0.3` and `bounce: 0`.
- Rapid toggles interrupt cleanly: the latest key wins and the previous icon exits from wherever it was.
- It adds no semantics and no size. The icon's own `size-*` class decides the cell, and the parent button decides the hit area.
- It is used inside Copy button, Password input and the AI message copy action, so those swap the same way.

Do and don't:
- Do: Key the swap on the state that picks the icon, so the change is animated.
- Don't: Swap the icon with a plain conditional. It snaps, and the change is easy to miss.
- Do: Expose the state on the control: `aria-pressed` on a toggle, a label that changes from Copy to Copied.
- Don't: Let the icon be the only sign of the state. Screen readers hear nothing, and a filled star alone is easy to misread.

Content:
- The control's label names the action for the current state: Play recording and Pause recording, not Toggle.
- For a toggle, keep one label and set `aria-pressed`: Favorite, pressed or not.
- Confirmations are past tense and short: Copied, Added, Saved. Keep them in the tooltip or a live region, not a toast, for a one-click action.

Accessibility:
- Icon swap renders two `<span>`s with no role. Mark the icons `aria-hidden="true"` and name the control around it.
- Toggles use `aria-pressed`. Actions whose meaning flips (play and pause) change their `aria-label`.
- Transient confirmations like Copied are announced with a polite live region, or through a tooltip that updates.
- Under reduced motion the swap is a short fade; the scale is removed by the app's Motion config.
- The hit area belongs to the button, not the icon: at least 24px, 32px on touch.

Known gaps (follow the system, not the gap):
- It relies on the app-wide `MotionConfig reducedMotion="user"` for reduced motion, which removes the scale but keeps the blur. DESIGN.md asks for blur to be zeroed too, and outside that provider the scale runs regardless.
- The inner span is fixed at `inline-flex` with no way to pass classes or attributes to it.

API `IconSwap` (extends Nothing. Only the props below are used.):
- `swapKey: string | number | boolean`. Changing it animates to the new children. Usually the state itself.
- `children: React.ReactNode`. The icon for the current state.
- `className?: string`. On the outer cell, merged after `inline-grid place-items-center`.

### Icon morph

- Level: Atom
- Category: Content
- Status: Beta
- Import: `@oration/canon/components/icon-morph`
- Exports: `IconMorph`
- Docs: /design/components/icon-morph

Icon morph turns one line icon into a related one by moving its strokes: a menu folds into a close, a plus turns into a close or flattens into a minus, a chevron flips, an arrow turns around. Every glyph is built from the same three strokes on Lucide's 24 grid, so any glyph morphs into any other and it sits beside Lucide icons unnoticed. Use it when both icons are the same object in two states. When they are different objects, such as copy and check or play and pause, use Icon swap.

When to use:
- For a disclosure whose icon shows open or closed: a menu to a close, a chevron down to up.
- For an add control that becomes its own undo or close: a plus to a close, a plus to a check.
- For a sort or direction toggle: an arrow up to an arrow down.
- For an expand and collapse pair: a plus to a minus.

When not to use:
- For two different objects: copy to check, play to pause, a spinner to a check, a bell to a muted bell. Use /design/components/icon-swap instead.
- For a glyph that isn't in the set. Don't draw strokes by hand in an app; add the glyph to Icon morph or use Icon swap. Use /design/components/icon-swap instead.
- For a chevron that only rotates inside an accordion or collapsible trigger. Those rotate with a transform already. Use /design/components/collapsible instead.

Rules:
- The Swap-In-Place Rule: A label or icon that changes while people watch changes in place: icons through Icon swap or Icon morph, short labels through Text swap, numbers through Animated number. It never snaps with a plain conditional.
- The Three Springs Rule: Strokes move on `spring.moderate`, critically damped so the shape lands exactly with no overshoot.

Anatomy:
- Canvas: A Lucide-compatible `svg`: 24 viewBox, `currentColor` stroke, 2px, round caps and joins, `aria-hidden="true"`.
- Carrying strokes: Slots one and three draw the shape. A single-stroke glyph such as a chevron or check draws it in both, so a second stroke folds into the first instead of vanishing.
- Middle stroke: Slot two is the menu's middle bar. On every other glyph it collapses to the center and fades.

States:
- Rest: The glyph for `icon`. The first render never animates.
- Morphing: When `icon` changes, each stroke's points travel to the new glyph on `spring.moderate`, and the middle stroke fades in or out.
- Reduced motion: Reads `useReducedMotion`. The new glyph draws at once.

Behavior:
- Glyphs: `menu`, `close`, `plus`, `minus`, `check`, `chevron-up`, `chevron-down`, `chevron-left`, `chevron-right`, `arrow-up`, `arrow-down`, `arrow-left`, `arrow-right`.
- Pass the glyph for the current state: `icon={open ? "close" : "menu"}`. There is no key to manage; the strokes are fixed for the life of the icon.
- Every glyph is three strokes of three points, so every path has the same shape and Motion interpolates `d` directly.
- It takes every `svg` prop, so `className="size-3.5"` and `data-icon="inline-start"` work as they do on a Lucide icon inside Button.

Do and don't:
- Do: Morph between two states of one object: plus to close on a filter toggle.
- Don't: Snap a plus to a close with a plain conditional. The control appears to be replaced rather than to change.
- Do: Swap between two different objects with Icon swap: copy to check.
- Don't: Force unrelated meanings into the morph set, like an arrow and a minus for play and pause.

Content:
- The control says its state in words: `aria-expanded` on a disclosure, a label that changes from Add to list to Added.

Accessibility:
- The svg is `aria-hidden="true"`. Name the control around it.
- Disclosures set `aria-expanded`; toggles set `aria-pressed`; actions whose meaning changes change their `aria-label`.
- Under reduced motion the glyph changes at once.

Known gaps (follow the system, not the gap):
- The set is line glyphs only. Filled icons (play, pause, a filled star) and multi-part icons can't morph and go through Icon swap.

### Text swap

- Level: Atom
- Category: Content
- Status: Beta
- Import: `@oration/canon/components/text-swap`
- Exports: `TextSwap`
- Docs: /design/components/text-swap

Text swap changes a short label in place. Letters the old and new label share glide to their new spots, new letters sharpen in, removed letters blur away, and the width follows on a spring, so the button or row around it never jumps. Reach for it whenever a label changes while people are looking at it: Follow to Unfollow, Check DNS to Checking, Pause to Resume. The mistake is using it for text that never changes on screen (a dialog title, a plural, an empty state) or for a sentence that can wrap.

When to use:
- For a button whose label flips with its state: Pause and Resume, Follow and Unfollow, Show and Hide.
- For a pending label that replaces the action while it runs: Send test to Sending, Test run to Running.
- For a short status that changes live: a status label going from On call to On hold, Active to Paused.
- For a confirmation that replaces the action in the same spot: Add to Added, Verify to Verified.

When not to use:
- For a number that changes. Counts, amounts and credits roll in tabular figures. Use /design/components/animated-number instead.
- For the icon beside the label. Swap it with Icon swap, keyed on the same state. Use /design/components/icon-swap instead.
- For a label that is being worked out, such as Summarizing… in a shimmer. The shimmer paints through the text, and moving letters break it. Use /design/patterns/live-states instead.
- For text decided once when a view opens: Edit view or New view, an empty state, a plural such as 1 agent or 3 agents, or a tooltip. It never changes on screen, so there is nothing to animate.
- For a sentence or anything that can wrap. Text swap stays on one line.

Rules:
- The Swap-In-Place Rule: A label or icon that changes while people watch changes in place: icons through Icon swap or Icon morph, short labels through Text swap, numbers through Animated number. It never snaps with a plain conditional.
- The Three Springs Rule: Letters and the width move on `spring.moderate`, which is critically damped, so nothing overshoots the layout. Leaving letters use `exit.moderate`, one tier quicker.

Anatomy:
- Root: The `as` element (a `span` by default), `whitespace-nowrap`, carrying `className` and `id`.
- Screen reader text: An `sr-only` copy of the plain label, so assistive technology reads Unfollow, never letters.
- Frame: An `aria-hidden` inline block with an explicit width that springs to the new label's width.
- Track and letters: One inline span per character. Letters are matched by character and occurrence, so the second i in one label pairs with the second i in the next.

States:
- Rest: The label as plain text. The first render never animates.
- Swapping: Shared letters glide, new letters rise 0.14em from 80% scale and a 2px blur, removed letters lift 0.1em and blur away, and the frame springs to the new width.
- Rapid change: A new label mid-swap starts from wherever the letters are. The latest label wins.
- Reduced motion: Reads `useReducedMotion`. The label and width change at once, with no blur, scale or travel.

Behavior:
- Pass the label for the current state as a single string: a ternary of string literals or a template literal. JSX children aren't allowed.
- Only the letters that are new stagger, in reading order, 20ms apart and capped at eight letters, after a 60ms handoff that lets leaving letters start to clear.
- Leaving letters pop out of layout (`AnimatePresence mode="popLayout"`), so the new label measures its true width at once.
- A `ResizeObserver` follows width changes that aren't a new label (fonts loading, a responsive size) without animating.
- It inherits font, size, weight and color, so it works inside Button, Pending button, Status label, headings and table cells unchanged.
- Pair it with Icon swap when the same control also changes its icon, keyed on the same state.

Do and don't:
- Do: Wrap the ternary that picks the label, so the change reads as one control changing state.
- Don't: Swap the label with a plain conditional. The button snaps to a new width and the change is easy to miss.
- Do: Keep it to short labels that change on screen, and leave decided-once text as plain text.
- Don't: Wrap a sentence, a dialog title or a plural. It can't wrap and there's nothing to animate.

Content:
- Pending labels are the verb in the present participle with no ellipsis when a spinner travels with them: Checking, Sending, Publishing.
- Confirmations are past tense and short: Added, Verified, Published.
- Toggles name the action the button takes next: Pause while running, Resume while paused.
- Labels that share letters morph best (Publish, Publishing, Published). Labels with none still cross-fade cleanly.

Accessibility:
- The visual letters are `aria-hidden="true"`; an `sr-only` copy carries the label, so a button's accessible name is the whole word.
- Text swap adds no live region. If the change must be announced (a result, not an action label), put the message in a polite `role="status"` region too.
- Toggles still set `aria-pressed` where the label doesn't change, and change their label where the action does.
- Under reduced motion the label changes at once.

Known gaps (follow the system, not the gap):
- Splitting the label into letters drops kerning pairs and ligatures between them. At 12 to 14px Geist this is invisible; at display sizes check it.
- It can't sit inside `text-shimmer`: the gradient is clipped to text, and moving letters drop out of it. In-progress shimmer labels stay plain text.

API `TextSwap` (extends Nothing. Only the props below are used.):
- `children: string`. The label for the current state.
- `as?: "span" | "div" | "p" | "strong" | "h1" | "h2" | "h3"` = "span". The root element.
- `className?: string`. On the root, merged after `whitespace-nowrap`.
- `id?: string`. On the root.

### Marker

- Level: Atom
- Category: Content
- Status: Experimental
- Import: `@oration/canon/components/marker`
- Exports: `Marker`, `MarkerIcon`, `MarkerContent`
- Docs: /design/components/marker

Marker is a quiet line of Slate Meta text that annotates what's around it: a sync note under a table, a day divider in an activity feed, a small heading over a group. It comes in three variants: plain with an optional icon, `separator` with a hairline on each side, and `border` with a hairline underneath. It is meta, not a message, so the mistake is using it for anything the person must act on; that is an alert or inline field help.

When to use:
- For a note under or beside content: Synced from NetSuite 4 minutes ago, Only admins can change approval rules.
- With `separator` for a label between hairlines in a feed or list: Today, Yesterday, or.
- With `border` for a small group label over a short list: Earlier this week, Northwind Freight invoices.
- With a `MarkerIcon` when a 16px icon helps the note scan: a lock for permissions, a clock for timing.

When not to use:
- For a warning or error the person has to act on. Use /design/components/alert instead.
- For help and errors tied to a form field. Use /design/components/field instead.
- For a plain rule with no text. Use /design/components/separator instead.
- For a section title with an action on the right. Use /design/components/section-header instead.
- For a timestamp and author line on a record. Use /design/components/meta instead.

Rules:
- Meta is Slate: Marker text is Slate Meta, the color of timestamps, counts and helper text. It sits below the content it annotates in the hierarchy and never competes with a heading.
- Hairlines, not boxes: The `separator` and `border` variants draw 1px hairlines in `--border`. Don't wrap a marker in a card or well to make it stand out; if it needs to stand out, it isn't a marker.

Anatomy:
- Container: A full-width flex row, 14px Slate Meta, with an 8px gap and a 16px minimum height. Renders a `<div>` unless `render` swaps it.
- Icon: `MarkerIcon`, an `aria-hidden` 16px box. Icons inside it without a `size-*` class are sized to 16px.
- Content: `MarkerContent`, the text. It wraps long words and styles direct child links with an underline.
- Rules: With `separator`, a hairline before and after the content that fills the space. With `border`, one hairline underneath with 8px of padding above it.

States:
- Rest: Static text. Marker has no interactive states of its own.
- Link hover: A link inside the content is underlined and turns Graphite Ink on hover.
- Wrapping: Long content wraps inside `MarkerContent`. In the separator variant the content doesn't shrink, so keep it short.

Behavior:
- `Marker` is built with Base UI `useRender`, so `render={<p />}` or `render={<li />}` changes the element while keeping the classes. Props are merged with `mergeProps`.
- The `separator` variant draws its rules with `::before` and `::after`, each `flex-1`, so the content centers between them. `MarkerContent` becomes `flex-none` and centered.
- The `border` variant adds `border-b` and 8px of bottom padding; put it directly above the list it labels.
- Items are vertically centered. With content that wraps to two lines, the icon centers on the block rather than the first line.
- The root exposes `data-variant` through its render state, and `MarkerContent` reads it with `group-data-[variant=separator]/marker`.

Do and don't:
- Do: Keep a marker to one short line of meta: when something synced, who can change it, which day a group is.
- Don't: Put a warning or a call to action in a marker. Slate text at 14px reads as a footnote, and people skip it.
- Do: Use the separator variant for day dividers in a feed, with one word or a date.
- Don't: Put a sentence between the rules. The rules shrink to nothing and the divider reads as a paragraph.

Content:
- Write meta as a fragment in sentence case, no trailing period for one clause: Synced from NetSuite 4 minutes ago.
- Relative days in feed dividers: Today, Yesterday, then dates: Thursday, Sep 24.
- Say who and when rather than what happened generally: Edited by Priya Raman at 9:42 AM.
- Permission notes name the role: Only admins can change approval rules.

Accessibility:
- Marker renders a plain `<div>` with no role. For a group label, render it as a heading (`render={<h3 />}`) so screen reader users can jump between groups.
- The separator rules are pseudo-elements and aren't announced; only the text is read.
- `MarkerIcon` is `aria-hidden`. The text has to carry the meaning on its own.
- Slate Meta on white passes 4.5:1 at 14px; don't dim it further with opacity.
- Links inside the content are underlined so they don't rely on color.

Known gaps (follow the system, not the gap):
- Nothing in `apps/web` imports Marker yet. Feed dividers, sync notes and group labels are written by hand where they appear.
- Passing `text-13` through `className` is read as a color by `cn` from the `cn` package, which drops `text-muted-foreground` and leaves the text at 14px in Graphite Ink. Use `text-[13px]`.
- The default is 14px, while DESIGN.md sets dense meta at 13px and Caption at 12px.
- Items are centered, so on a wrapped two-line note the icon floats to the middle instead of sitting on the first line.

API `Marker` (extends `<div>` via Base UI `useRender`):
- `variant?: "default" | "separator" | "border"` = "default". Plain, between two hairlines, or over one hairline.
- `render?: ReactElement | (props, state) => ReactElement`. Render as another element, such as `<h3 />` or `<li />`.
- `className?: string`. Merged into the variant classes. Use `text-[13px]`, not `text-13`, to change the size.

API `MarkerIcon` (extends `<span>`):
- `className?: string`. Merged last.

API `MarkerContent` (extends `<span>`):
- `className?: string`. Merged last.

### Well

- Level: Atom
- Category: Layout
- Status: Beta
- Import: `@oration/canon/components/well`
- Exports: `Well`
- Docs: /design/components/well

Well is a tint well: a sub-region inside a card, filled with Well Gray at 70%, with 10px corners and 12px of padding. It groups a preview, a few figures or a set of dependent fields without drawing a second card. The mistake it exists to prevent is the nested card, a bordered or shadowed box inside another, which stacks edges and flattens the hierarchy. A well has no border, no shadow and no interaction of its own.

When to use:
- For a live preview under a setting: sample phrases an agent would stop for, a remittance email as the supplier will see it.
- For a few figures inside a sheet or record panel: open, overdue and paid this month.
- For dependent fields that appear when a setting is on, such as the approver and threshold under Require a second approval.
- For a quoted excerpt inside a card: a transcript line, a supplier's email, a note from the last call.

When not to use:
- For a surface on the page plane. A well only exists inside a card. Use /design/components/card instead.
- For a message that tells the person something went wrong or needs attention. Use /design/components/alert instead.
- For code or JSON, which has its own mono surface and copy action. Use /design/components/code-block instead.
- For a selectable option. A well isn't interactive. Use /design/components/choice-card instead.
- For a row in a list with an icon, title and action. Use /design/components/item instead.

Rules:
- The Tint Well Rule: Inside a card, a sub-region is a Well Gray tint at 70% with a 10px radius, never a second bordered or shadowed card.
- One level deep: A well sits directly in a card. Don't put a well inside a well; split the content with a hairline or spacing instead.

Anatomy:
- Card: The surface the well sits in: `rounded-xl bg-card shadow-border` with 16px padding. Not part of the component.
- Well: A `<div>` with `bg-muted/70` and 10px corners. No border, no shadow.
- Padding: 12px by default. Use 16px (`p-4`) for fields, `px-3 py-2.5` for a single line.
- Content: Whatever the region holds, in the card's type: 13px for dense content, Slate Meta for secondary lines.

States:
- Rest: The only state. The well is a static region with no hover, focus or pressed styles.
- Dark theme: Well Gray swaps with the theme, so the 70% tint stays a step off the card in both.
- Revealed: When a well holds dependent fields, show it only while the controlling setting is on. It appears in place, no animation needed.

Behavior:
- `Well` is a styled `<div>`. Every prop spreads onto it, and `className` is merged after `rounded-[10px] bg-muted/70 p-3`, so padding and layout can be overridden.
- It sets no text color or size. Content inherits from the card.
- Controls inside a well keep their own surfaces: inputs stay white with their hairline, so they stand out against the tint.
- It works on any card width. In a grid of figures, give each well `min-w-0` so long values truncate instead of stretching the grid.

Do and don't:
- Do: Split the inside of a card with a 70% tint well at a 10px radius.
- Don't: Put a bordered or shadowed card inside a card. Two edges stack, and the inner box reads as a separate object.
- Do: Keep wells one level deep, directly inside the card.
- Don't: Nest a well inside a well. The tints add up to a darker gray that reads as disabled.

Content:
- Label a preview so it's clear it is one: Preview, As Northwind Freight will see it.
- Figures in a well follow the stat pattern: a 12px Slate label, a tabular value, an optional detail line.
- Quoted text keeps its source nearby: who said it and when, in Slate Meta under the quote.

Accessibility:
- The well is a `<div>` with no role; it groups visually only. If the region needs a name for screen readers, use a `<section>` with `aria-labelledby` inside it, or put a heading in it.
- The tint is decoration. Don't rely on it alone to show that fields are dependent; the setting that reveals them says so.
- Slate Meta and Graphite Ink both keep their contrast on the 70% tint in both themes.
- Revealed fields appear after the setting that controls them in reading order, so focus moves into them naturally.

Known gaps (follow the system, not the gap):
- Only the agent configuration screens import `Well`. About 140 files in `apps/web` write the `bg-muted/70` recipe by hand, with a mix of corners and padding.
- Two local components are also called `Well`: a figure well in `contact-center/charts.tsx` (label, value, detail) and a 12px text well in the procedure editor nodes. They look close to this one but don't share it.
- Corners are written as `rounded-[10px]` rather than `rounded-lg`, so they won't follow a change to `--radius`.

API `Well` (extends `<div>`):
- `className?: string`. Merged after `rounded-[10px] bg-muted/70 p-3`. Use it for padding and layout.
- `children?: React.ReactNode`. The region's content.

### Illustration

- Level: Atom
- Category: Content
- Status: Beta
- Import: `@oration/canon/components/illustration`
- Exports: `Illustration`, `ILLUSTRATION_NAMES`
- Docs: /design/components/illustration

Illustration draws one of 23 spot drawings. Each is one subject, drawn large and flat with room round it: Card White shapes outlined at Ink 65 over a copy a few units lower at Ink 45 that shows as their edge, a 1px stroke, a faded reflection under whatever stands on the floor, and one Ink 80 accent. Each drawing acts out its subject once when it mounts and again on hover: a letter drops into the inbox, the gears turn, a check is drawn. They're drawn in `currentColor` and Card White, so they invert with dark mode on their own. Their job is to make an empty, error or education state recognizable at a glance, never to decorate. Most of the time you don't render one directly: pass `illustration` to an empty state or a page intro and it picks the size for you.

When to use:
- Through Empty and Data state's `EmptyState`, above the title of a first-run or no-results state: `customers` for no suppliers yet, `filters` for no matches.
- In a Page intro banner that explains what a new area is for.
- Directly, at `md`, for a full-panel moment such as the onboarding finish (`done`).
- At `sm` inside cards, side panels and table bodies, where the state has less room.

When not to use:
- For a small glyph inside a button, row or menu. Use a 16px Lucide icon. Use /design/foundations/iconography instead.
- For a loading state. Draw the layout that's coming instead. Use /design/components/skeleton instead.
- For the face of a person, company or agent. Use /design/components/avatar instead.
- As decoration on a populated page, a card header or a marketing flourish. Art only appears when there's nothing else to show.
- For an error inside a form or a failed save. Say it next to the field or in a toast. Use /design/patterns/feedback instead.

Rules:
- The Ink Fill Rule: The art is drawn in ink steps on paper and Well Gray, with a single Ink 80 accent. It never takes indigo or a categorical hue, so it sits quietly under the title and can't be mistaken for status.
- One family, one per state: Every drawing shares the flat-shape-and-edge style, the stroke and the palette, and tells one action with its motion, so they read as one set. A state gets one illustration, placed above its title and centered with it.

Anatomy:
- Canvas: An `<svg>` with a 120 by 96 `viewBox` at a 5:4 ratio, rendered 80, 120 or 160px wide.
- Slabs: Flat shapes seen from a little above, filled with Card White (`var(--card)`) and outlined at Ink 65: the tiles, cards, discs and trays in the drawing.
- Edge: The same shape again a few units lower at Ink 45, showing below the top as its thickness. Marks on surfaces sit at Ink 15 and 25.
- Outlines: 1px round-capped strokes with `vector-effect: non-scaling-stroke`, so they stay 1px at every size. Each ink step is `currentColor` mixed into Card White, so an edge lying over another doesn't darken.
- Accent: One Ink 80 mark, such as the check or the unread dot, that the drawing is about. It comes on as the action lands.

States:
- Decorative: The default. `aria-hidden` is set and the art is skipped by screen readers.
- Named: `title` sets `role="img"` and `aria-label`, for the rare drawing that carries meaning the text around it doesn't.
- Playing: On mount, and each time the pointer comes onto it, the drawing acts out its subject over about a second and a half, then rests in the pose it was drawn in.
- Reduced motion: Every animation is off and the drawing stands in its rest pose, which is its final pose. Nothing is missing.
- Dark theme: Ink follows `currentColor` and paper and wells follow `--card` and `--muted`, so the drawing inverts with no extra class.

Behavior:
- `name` picks the drawing from a fixed map. `ILLUSTRATION_NAMES` lists all 23, in the map's order.
- `size` sets the rendered width to 80, 120 or 160px and the height to 80% of that. Override both with classes such as `h-auto w-16` only when a composed component needs it.
- The root has `text-foreground`, `shrink-0` and `select-none`. `className` is merged after them.
- Motion is CSS keyframes in `globals.css`, one `motion` per mark (`drop`, `slide`, `hop`, `rise`, `grow`, `spin`, `ripple`, `press`, `pulse`, `bob`, `lift`, `pop`, `shake`, `draw`, `light`). No library and no frame loop: the root is a small client canvas that replays its animations on `pointerenter` with the Web Animations API.
- Shapes are path strings from the kit in `illustrations/primitives.tsx` (`rrect`, `ellipse`, `rhombus`, `hexagon`, `wedge`, `cube`, `gear`), worked out once when the drawings' module loads. No camera; rendering is plain SVG.
- `focusable="false"` keeps the SVG out of the tab order in every browser.
- `EmptyState` renders `md` art at its `md` size and `sm` art at `sm`. `ErrorState` always uses `error` at `sm`. `PageIntro` uses `sm` at 72px and hides it below 640px.

Do and don't:
- Do: Size the art to its container: `sm` in a card or side panel, `md` in a page-level empty state.
- Don't: Drop a `lg` drawing into a small panel. It crowds the title and pushes the action below the fold.
- Do: Leave the art in ink. It inverts with the theme and stays quiet under the title.
- Don't: Tint it with `text-primary` or a status color. Indigo reads as selected, and the drawing starts competing with the one filled button.
- Do: Keep it decorative and let the title say what the state is.
- Don't: Give it a `title` that repeats the heading. Screen readers hear No suppliers yet twice.

Content:
- Pick the drawing for the place, not the mood: `customers` for suppliers and contacts, `filters` for no matches, `search` for no results, `reports` for an empty report, `done` for a finished flow.
- The title under it says what the place is for or why it's empty: No suppliers yet, No invoices match these filters.
- A `title` on the art, when you need one, describes the picture, not the state: A checklist with every item done.

Accessibility:
- Decorative by default: `aria-hidden="true"` and no role, so the state's text carries everything.
- With `title`, the SVG becomes `role="img"` with that `aria-label`.
- `focusable="false"` stops legacy browsers from tabbing into the SVG.
- Outline contrast comes from ink steps of `currentColor`, which follow the theme. Don't lower it with opacity.
- Under `prefers-reduced-motion: reduce` every animation is off and the drawing rests in its final pose.

Known gaps (follow the system, not the gap):
- `ErrorState` shrinks the art to 64px with `h-auto w-16` at its small size, and `PageIntro` to 72px with `w-18`. Neither is on the 80, 120, 160 ramp.
- Only `className` is forwarded, so an `id`, `aria-describedby` or `data-*` attribute can't be set on the SVG.

API `ILLUSTRATION_NAMES`:

### Variable chip

- Level: Atom
- Category: Editors
- Status: Beta
- Import: `@oration/canon/components/variable-chip`
- Exports: `VariableChip`
- Docs: /design/components/variable-chip

Variable chip is a `{{name}}` token set in Geist Mono, for template variables in prompts, procedures, macros and message templates. Its fill says what kind of variable it is: gray for a custom variable, teal for a system variable filled in at call time, and a warning tint with an icon for one that isn't defined yet and will come out blank. The braces are drawn faintly and hidden from screen readers, so the name is what gets read. The mistake is showing an undefined variable as if it were fine; the warning state exists so a blank never reaches a supplier.

When to use:
- Inline in a template preview, where a variable will be replaced: Hi {{supplier_name}}, we paid {{invoice_number}}.
- In a palette of insertable variables beside an editor, with `onClick` to insert and a `description` that says where the value comes from.
- In a variables list or sheet, at `sm`, next to each variable's name and description.
- With `state="undefined"` to list variables a template uses that nobody has defined: Won't be filled in: {{po_number}}.

When not to use:
- For editing a prompt with variables as atomic nodes. Use the editor, which renders chips for you. Use /design/components/prompt-editor instead.
- For a value such as a stage, tier or payment term. Use /design/components/tag instead.
- For a keyboard shortcut. Use /design/components/kbd instead.
- For a block of code, JSON or a full template. Use /design/components/code-block instead.
- For a list of key and value pairs a person edits. Use /design/components/key-value-editor instead.

Rules:
- Mono for machine strings: Geist Mono appears only where a machine wrote the string. A variable name is one, so the chip is mono; the sentence around it stays in Geist Sans.
- The Label-Beside-Color Rule: State never relies on color. Undefined variables add a warning icon, an inset warning ring, screen reader text and a tooltip; system variables add screen reader text and a tooltip.

Anatomy:
- Container: A 20px (or 18px at `sm`) pill with 8px corners, baseline-aligned so it sits in running text. A `<span>`, or a `<button>` with `onClick`.
- Warning icon: Undefined only: a 12px triangle, `aria-hidden`.
- Braces: `{{` and `}}` at 55% opacity and `aria-hidden`, so the name reads first.
- Name: The variable name in Geist Mono, 12px (11px at `sm`), truncated if the chip is narrower.
- Tooltip: For system and undefined variables, or whenever `description` is set: what the variable is, or why it's blank.

States:
- Defined: `state="defined"`, the default. Tag Gray fill, gray text. No tooltip unless `description` is set.
- System: Tag Teal fill and text, with a tooltip: System variable, filled in at call time.
- Undefined: A 15% warning tint, a 1px inset warning ring at 45%, a triangle icon and a tooltip saying it stays blank until defined.
- Hover: Clickable chips only: brightness drops to 97% (rises to 110% in dark) over 150ms, with a pointer cursor.
- Focus visible: Clickable chips only: a 2px Focus Indigo ring at 60%.
- Selected: `selected` draws the same 2px ring, for a chip selected inside an editor.

Behavior:
- Without `onClick` the chip is a `<span>`; with it, a `type="button"` `<button>` that calls `onClick` with the mouse event.
- A defined chip with no `description` renders bare. Every other chip is wrapped in a Tooltip, with `description` taking the place of the default hint.
- The tooltip opens on hover and on keyboard focus. On a non-clickable span it has no focus stop, so keyboard users get the state from the screen reader text only.
- The chip never wraps (`whitespace-nowrap`) and truncates its name inside `max-w-full`, so a long name in a narrow cell ends in an ellipsis.
- `align-baseline` keeps it on the text baseline in paragraphs. Use `sm` in 12 and 13px text and the default in 14px text.

Do and don't:
- Do: Mark variables that aren't defined as undefined, so the warning shows before the template is sent.
- Don't: Render every variable as defined. A gray chip promises a value, and the supplier gets Hi , instead.
- Do: Use the variable's machine name, lowercase with underscores, exactly as the template stores it.
- Don't: Write a label in the chip. Spaces and capitals suggest it can be typed any way, and it won't match.

Content:
- Names are lowercase snake case nouns: supplier_name, invoice_number, payment_date.
- A `description` says where the value comes from: The supplier's legal name from their W-9.
- In an insert palette, end the description with the action: Invoice number. Click to insert.
- Introduce a list of undefined chips with what will happen: Won't be filled in:.

Accessibility:
- The braces are `aria-hidden`, so a screen reader reads supplier_name rather than left brace left brace.
- System and undefined chips add screen reader text: (system variable) and (undefined variable).
- Clickable chips are real buttons with Enter and Space. Their name is the variable name, so give the palette a visible label such as Insert a variable.
- Tooltips on non-clickable chips can't be reached by keyboard. Don't put information in `description` that isn't also on the page.
- The warning icon is `aria-hidden`; the screen reader text carries the state.
- At 18px, `sm` chips are below the 24px hit target. Use the default size when chips are the main way to insert.
- Tab: Moves to a clickable chip and opens its tooltip.
- Enter: Activates a clickable chip.
- Space: Activates a clickable chip.
- Esc: Closes the tooltip.

Known gaps (follow the system, not the gap):
- System variables are Tag Teal, a categorical hue. The Option Hue Rule keeps those hues for select-option values and identity tints, not for a kind of thing.
- Focus and selected draw a 2px ring at 60% with no border change. DESIGN.md gives controls a 3px ring at 40 to 50% plus an indigo border.
- Hover is a `brightness` filter rather than a token step, so the hover color isn't in the palette.
- No rest props are forwarded, so a clickable chip can't take an `aria-label` such as Insert invoice_number.

API `VariableChip` (extends Nothing. Renders a `<span>` or `<button>`; only the props below are used.):
- `name: string`. The variable name, without braces.
- `state?: "defined" | "undefined" | "system"` = "defined". Custom, not defined yet, or filled in by the system.
- `description?: React.ReactNode`. Overrides the tooltip text. Also adds a tooltip to defined chips.
- `onClick?: (event: React.MouseEvent<HTMLElement>) => void`. Makes the chip a button, for insert palettes.
- `selected?: boolean` = false. Shows the 2px ring, for a chip selected in an editor.
- `size?: "sm" | "default"` = "default". 18px with 11px text, or 20px with 12px text.
- `className?: string`. Merged last onto the chip.

### AI loader

- Level: Atom
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/ai-loader`
- Exports: `AILoader`, `PixelGrid`, `useElapsed`, `formatElapsed`
- Docs: /design/components/ai-loader

AI loader is the house wait state for work a model is doing: a small pixel grid that ripples, a shimmering label that names the work and the seconds elapsed. It fills the gap between a request and its first output, then gets replaced in place by the result. The common mistake is using it for ordinary data loading. When the shape of the result is known (a list, a table, a card), load it with a skeleton; the AI loader is for work whose output doesn't exist yet.

When to use:
- While a model searches, reads or drafts and nothing has streamed yet: Searching documents…, Reading the call…
- In the slot where the answer will appear, so the result replaces it without a layout jump.
- When the wait can run past a couple of seconds and the elapsed count reassures people that it is still working.
- As a `PixelGrid` alone inside a compact affordance whose text already says what is happening, such as a pending field action or a Rewriting… bar.
- With `useElapsed` and `formatElapsed` when a custom row needs the same ticking seconds, such as a running campaign.

When not to use:
- To load records, rows or cards whose shape you already know. Use /design/components/skeleton instead.
- For a generic busy glyph inside a button or a non-AI request. Use /design/components/spinner instead.
- When the work has visible steps a person may want to read. Use /design/components/thinking instead.
- For a plan whose rows tick through queued, running and done. Use /design/components/task-list instead.
- For work with a known amount done, such as an import at 40%. Use /design/components/progress instead.
- For the state of a live voice call. Use /design/components/voice-orb instead.

Rules:
- The Quiet Indigo Rule: The grid is drawn in ink by default. Indigo is for the primary action, selection, focus and labelled live state, so an indigo pixel grid reads as decoration. Keep `tone` at `ink` or `muted`.
- Shimmer only while working: The shimmering label is the one gradient-clipped text Canon allows, and only on an in-progress label. When the work finishes, the loader leaves and the result takes its place. Never leave a shimmer on finished text.

Anatomy:
- Pixel grid: A 3×3, 4×4 or 5×5 grid of square cells with 1px corners. Opacity ripples diagonally across it on a 1.2s cycle.
- Label: The live status, in medium weight with the `text-shimmer` sweep. It names the work: a verb in -ing form, the object and an ellipsis.
- Elapsed: Whole seconds in Slate Meta tabular figures, 12s then 1m 14s. Hidden from screen readers so it doesn't announce every tick.

States:
- Working: The grid ripples, the label shimmers and the counter ticks once a second from `startedAt` or from mount.
- Label change: Pass a new `label` as the work moves on. The status region announces the new text once.
- No counter: `showElapsed={false}` hides the seconds and stops the interval. Use it for waits that are always short.
- Past a minute: `formatElapsed` switches to minutes and seconds: 1m 14s.
- Resting grid: `PixelGrid active={false}` holds a fixed checker of four opacities, so it still reads as pixels rather than a block.
- Reduced motion: The grid holds its resting pattern and the label shimmer stops. The label and counter still update.

Behavior:
- The grid animates each cell's opacity with the Web Animations API (0.16 to 1 and back, 1.2s, on the house ease-in-out). It keeps running smoothly while the main thread is busy rendering a stream.
- Each cell starts 90ms after its diagonal neighbour, with a negative delay so the ripple is already in motion on the first frame.
- `useElapsed(startedAt, running)` reads whole seconds since `startedAt` (epoch ms), or since mount when it is left out, and ticks with a one-second interval while `running` is true.
- Pass `startedAt` when the loader might remount, for example when a skeleton swaps for another state, so the counter doesn't restart at 0s.
- Replace the loader with the result in the same place. The loader has no exit animation of its own.
- Under reduced motion the ripple doesn't start and `.text-shimmer` stops through the global reduced-motion rule. Nothing else changes.

Do and don't:
- Do: Name the work in the label, so the wait explains itself: Checking payment PMT-58213…
- Don't: Use a generic label such as Loading… or Please wait. It says nothing a spinner doesn't.
- Do: Load a known shape, such as the supplier list, with a skeleton that matches it.
- Don't: Put the AI loader where a list or table is loading. It promises model work that isn't happening.
- Do: Show one loader in the slot where the result will appear.
- Don't: Stack a spinner, a pixel grid and a Please wait line. Three indicators for one wait is noise.

Content:
- Write the label as a verb in -ing form plus its object, ending in a single ellipsis character: Searching documents…, Reading the call…, Drafting a reply…
- Be specific when you can: Checking payment PMT-58213… beats Thinking… (the default).
- Keep it to one short line. It truncates nowhere, so a long label wraps and pushes content down.
- Don't put the time in the label. The counter already shows it.
- Change the label as the work moves forward, no more often than every second or so. Past tense belongs to the result, not the loader.

Accessibility:
- The loader is a `role="status"` region, so its label is announced politely and again whenever it changes.
- The elapsed counter is `aria-hidden`, so screen readers aren't interrupted every second.
- `PixelGrid` is always `aria-hidden`. When you use it alone, the text beside it or the control's `aria-label` has to say what is happening, as the pending AI field action does with Generating a draft.
- Under reduced motion the grid is static and the shimmer stops. The label carries the state on its own, which is why it must always be present.
- When the result arrives, move focus only if the person asked for it. Otherwise let the result render in place.

Known gaps (follow the system, not the gap):
- Only one product screen uses `AILoader`: the knowledge base question panel. Other AI waits hand-roll the look with a `text-shimmer` span (Checking which skill fits… in the skill test panel, Summarizing… in the ticket composer), a spinning refresh icon (Analyzing… in analysis settings) or a `Spinner` (Starting a chat with… in the web call). Use `AILoader` for these.
- `tone="primary"` draws indigo pixels. Nothing uses it, and under the Quiet Indigo Rule it is decoration.
- `formatElapsed` has no hour unit: at 3,600 seconds it reads 60m 0s.
- The loader has no exit transition, so the swap to the result is instant. That is fine for text, but a result much taller than the loader will push content down in one step.

API `AILoader` (extends Nothing. Only the props below are read.):
- `label?: string` = "Thinking…". The live status. Name the work.
- `startedAt?: number`. Epoch ms the work began. Defaults to when the loader mounted.
- `size?: "sm" | "md" | "lg"` = "md". Grid of 3, 4 or 5 cells a side, with 12, 13 or 14px text. `sm` suits panels and rows.
- `tone?: "ink" | "muted" | "primary"` = "ink". Grid color. Keep `ink`; `primary` spends indigo on decoration.
- `showElapsed?: boolean` = true. Shows the seconds counter and runs its interval.
- `className?: string`. Merged onto the row.

API `PixelGrid` (extends Nothing):
- `size?: "sm" | "md" | "lg"` = "md". 11, 16.5 or 28px square.
- `tone?: "ink" | "muted" | "primary"` = "ink". Cell color.
- `active?: boolean` = true. Runs the ripple. False holds the resting pattern.
- `className?: string`. Merged onto the grid.

API `useElapsed`:
- `startedAt?: number | undefined`. First argument. Epoch ms; defaults to when the calling component mounted.
- `running?: boolean` = true. Second argument. False reads the value once and stops ticking.
- `returns?: number`. Elapsed whole seconds.

API `formatElapsed`:
- `seconds: number`. Seconds to format.
- `returns?: string`. The formatted duration.

### Voice orb

- Level: Atom
- Category: Voice
- Status: Beta
- Import: `@oration/canon/components/voice/orb`
- Exports: `VoiceOrb`
- Docs: /design/components/voice-orb

Voice orb is the live voice agent's signature visual: a soft sphere of cool light whose motion follows the call. It breathes while connecting, leans in with the caller's voice while listening, turns a slow sheen while thinking and swells with the agent's voice while speaking. It is the one animated gradient in Canon, allowed because it shows audio level and call state, not because it is pretty. The thing people get wrong is letting it carry the state alone: it always sits beside a text status such as Nora is speaking or You're muted.

When to use:
- At the center of a live call surface: the web call panel, a test call or a call preview.
- In the embeddable widget before a call starts, idle, beside a Start call button.
- Small (about 40px) in the header of a live call card, next to the agent's name and a Live status label.
- Once per surface, for the call that is happening now.

When not to use:
- To identify an agent in lists, rows, menus and headers. Use /design/components/agent-avatar instead.
- For audio level in a compact bar, a minimized call pill or a supervisor monitor. Use /design/components/waveform instead.
- For a recording that plays back and seeks. Use /design/components/waveform instead.
- For a call's state in a table cell or a queue row. Use /design/components/status-label instead.
- For AI work that isn't a voice call. Use /design/components/ai-loader instead.
- As decoration in empty states, marketing panels or page headers. Use /design/components/illustration instead.

Rules:
- The one animated gradient: The orb is the only place Canon allows a soft animated gradient, because it visualizes audio level and call state. Don't reuse its palette, its blur or its motion for chrome, backgrounds or loaders.
- The Label-Beside-Color Rule: The orb never carries state alone. A text status that changes with it (Connecting to Nora, Listening, Nora is thinking) sits right below or beside it, so the state reads without motion and in grayscale.

Anatomy:
- Halo: A radial glow 18% larger than the sphere. Its opacity and scale follow the state: faint while listening, widest while the agent speaks.
- Body: The sphere: a radial gradient lit from the upper left. Pale and cool in light, graphite in dark.
- Light: Three blurred blobs of indigo, blue and lilac that drift inside the sphere. They spread apart as the voice gets louder and draw together while listening.
- Sheen: A conic highlight that fades in and turns only while thinking, so thinking reads differently from speaking.
- Highlight: A fixed specular spot in the upper left that gives the sphere its volume.
- Shade and rim: An inset shadow at the bottom and a 1px rim that keeps the edge visible on white and on dark surfaces.
- Reduced-motion ring: Only under reduced motion: a 1.5px ring that steps outward with the level in thirds. Not drawn in the anatomy above.

States:
- Idle: Holds still with the light dimmed to 45%. The animation loop stops once the sphere settles.
- Connecting: Breathes on a 2.6s cycle between 97% and 101% scale, with the halo pulsing and the light at 80%.
- Listening: Scales up to 5% with the caller's level while the light draws together, like leaning in.
- Thinking: A steady, slightly faster drift with the conic sheen turning. Level is ignored.
- Speaking: Swells up to 10% with the agent's level, the light spreads and the halo grows up to 22%.
- Muted: Not a state of its own: pass `listening` with a near-silent `level` such as 0.02 and change the text to You're muted.
- Offscreen: The loop pauses when the orb scrolls out of view and resumes when it returns.
- Reduced motion: No loop runs. The light holds its resting position and a ring steps with the level: a third out while connecting, listening or thinking, two thirds while speaking, none when idle.

Behavior:
- One `requestAnimationFrame` loop writes transforms and opacity straight to the DOM, so the orb never re-renders React while it moves.
- Leave `level` out while listening or speaking to get a built-in speech envelope: syllable bursts inside phrases, with pauses between. Pass `level` (0 to 1) when you have real audio.
- Level is smoothed with a fast attack and a slow release, so peaks land at once and the sphere relaxes over about 200ms.
- Changing `state` keeps the current scale and energy and eases toward the new state's targets, so there is no jump between states.
- The light's opacity changes over 700ms when entering idle or connecting. The brief exempts the orb from the three springs.
- Each orb picks a random phase on mount, so two orbs on one screen never move in lockstep.
- The halo, blur and drift radius scale with `size`, so the orb looks the same at 40px as at 112px.
- Light and dark palettes come from private CSS variables on the orb, switched by the `.dark` class. In dark the light blends with `mix-blend-screen`.

Do and don't:
- Do: Pair the orb with a text status that changes with it, and the call clock below.
- Don't: Show the orb alone and expect people to read listening from speaking by motion.
- Do: Use agent avatars to identify agents in a list, with a status label for who is on a call.
- Don't: Put an orb in every row. It is the live call visual, not an identity mark, and a column of animated gradients is noise.
- Do: Keep Start call, Mute and End call as real buttons beside the orb.
- Don't: Make the orb itself the button. It has no focus style, no name for the action and no pressed state.

Content:
- Name the agent's persona in the status: Connecting to Nora, Nora is speaking, Nora is thinking.
- Use the caller's point of view for their side: Listening, You're muted.
- For phone tests, say what the line is doing: Calling +1 312 555 0142, Ringing your phone, Answered, connecting the agent.
- Put the call clock under the status in tabular figures (0:42). Before audio is live, say Setting up audio instead.
- Set the orb's own `label` to the persona and the status together: Nora, listening.

Accessibility:
- The orb is `role="img"` with an `aria-label`, Voice agent listening by default. Pass `label` with the persona and state, such as Nora, listening.
- Because it is an image, label changes aren't announced. Put the visible status text in an `aria-live="polite"` region so state changes are spoken.
- The orb is not interactive and takes no focus. Call controls are separate buttons with names and tooltips.
- Under reduced motion nothing moves; a ring steps with the level so the call still looks alive.
- The light is decorative and has no contrast requirement. The status text beside it carries the meaning and must meet text contrast.

Known gaps (follow the system, not the gap):
- No product surface passes a real audio `level`. Every orb runs the simulated speech envelope; the live call view only passes 0.02 while muted.
- `size` is a free number. The product uses 40, 64, 88 and 112px, and the default of 96 matches none of them.
- The orb's colors are hard-coded OKLCH values in private variables, not theme tokens. That is deliberate, but a change to the indigo token won't reach the orb.
- While animating, `level` only affects listening and speaking. Under reduced motion the ring reads `level` in every state except idle, so a thinking orb with a `level` passed looks louder with motion off than on.

API `VoiceOrb` (extends Nothing. Only the props below are read.):
- `state: "idle" | "connecting" | "listening" | "thinking" | "speaking"`. The call state the motion follows.
- `level?: number`. 0 to 1. The caller's level while listening, the agent's while speaking. Leave it out for a simulated voice. Ignored in other states except by the reduced-motion ring.
- `size?: number` = 96. Diameter in px. The product uses 40, 64, 88 and 112.
- `label?: string` = "Voice agent {state}". Accessible name. Include the persona and the state.
- `className?: string`. Merged onto the root.

### Waveform

- Level: Atom
- Category: Voice
- Status: Stable
- Import: `@oration/canon/components/voice/waveform`
- Exports: `Waveform`, `StaticWaveform`, `simulateVoiceLevel`, `formatClock`
- Docs: /design/components/waveform

Waveform draws audio in two ways. `Waveform` is a row of live level bars for a call in progress: the minimized call pill, the contact center call bar, a supervisor's monitor. `StaticWaveform` draws a recording from precomputed peaks and, given `onSeek`, becomes a slider you drag, click or step with the keyboard. Both are ink, never indigo. The common mistake is letting the live bars stand in for the call's status: they show that sound is happening, while a status label says whether the call is live, on hold or muted.

When to use:
- Beside a live call's status and clock, to show that someone is speaking: On call 3:42 and the bars.
- Inside compact call chrome where the orb doesn't fit: the minimized call pill, a queue row being monitored.
- For a call recording or voicemail with a play button, the position, the duration and a speed menu.
- Read-only (no `onSeek`) for a recording preview in a list, where the row opens the full player.
- With `simulateVoiceLevel` to drive demos and previews that have no audio.

When not to use:
- For the centerpiece of a live call with the agent's state. Use /design/components/voice-orb instead.
- For latency or any other value over time. Use /design/components/latency-timeline instead.
- For a trend in a table cell or a stat. Use /design/components/mini-chart instead.
- For a plain progress bar of a known task. Use /design/components/progress instead.
- To pick a voice and play a sample of it. Use /design/components/voice-picker instead.

Rules:
- The Ink Fill Rule: Bars and peaks are Graphite Ink at fixed alphas: 65% for live bars, 80% for the played part of a recording, 20% for the rest. They are magnitudes, so they are never indigo.
- The Label-Beside-Color Rule: Live bars show that audio is flowing, not what state the call is in. Put a status label beside them (On call, On hold, Muted) and let the bars fall flat when nobody is speaking.
- The Tabular Figures Rule: Position and duration beside a recording, and the call clock beside live bars, are set in tabular figures so they don't jitter as they count.

Anatomy:
- Live bars: `Waveform`: round-ended bars, 2px wide with 2px gaps by default, tallest in the middle. Each bar scales vertically with the smoothed level.
- Played peaks: `StaticWaveform` peaks before the playhead, in Ink 80.
- Unplayed peaks: Peaks after the playhead in Ink 20. Every peak is at least 8% of the height, so silence still shows.
- Hover line: A 1px Ink 50 line under the pointer on a seekable waveform, showing where a click will land. Not shown on touch.
- Focus ring: A 3px Focus Indigo ring at 40% on keyboard focus, with 6px corners.

States:
- Live, active: Bars follow `level`, or a simulated voice when `level` is left out. Peaks land fast and fall slowly.
- Live, inactive: `active={false}` lets the bars fall to 12% height, then stops the animation loop. Use it for muted, on hold and silence.
- Live, reduced motion: No loop runs. The bars hold their envelope shape at a height that steps with `level` in quarters, or flat when inactive.
- Recording, not started: Every peak in Ink 20.
- Recording, playing: Peaks before `progress` turn Ink 80. The caller advances `progress`; the waveform doesn't play audio.
- Recording, hover: The hover line follows the pointer on seekable waveforms.
- Recording, dragging: The waveform captures the pointer, so a drag keeps seeking even when it leaves the bars.
- Recording, focus visible: The 3px ring. Arrow keys step 5 seconds from here.
- Read-only: Without `onSeek` it is `role="img"`, not focusable, with no hover line.

Behavior:
- `Waveform` runs one `requestAnimationFrame` loop that writes `scaleY` to each bar directly. It stops once the bars settle after `active` turns false and restarts when it turns true again.
- Smoothing is frame-rate independent: 40% of the way to a louder target per 60fps frame, 10% toward a quieter one.
- Each bar gets its own flutter on top of a centered envelope, so the row reads as speech rather than an equalizer.
- `StaticWaveform` is controlled: pass `progress` (0 to 1) and update it in `onSeek`. It never changes position on its own.
- Pointer down seeks at once and captures the pointer; moving while held keeps seeking. Hover (not touch) shows the line.
- Keyboard steps are 5 seconds when `duration` is given, otherwise 5%. Page Up and Page Down step twice as far.
- `simulateVoiceLevel(t, seed)` returns a speech-like envelope for a time in seconds; different seeds decorrelate two speakers. `formatClock(seconds)` gives m:ss.

Do and don't:
- Do: Pair live bars with a status label and the clock, and flatten them when the line is muted or on hold.
- Don't: Show bouncing bars as the only sign of a call. They look the same on hold as on a call.
- Do: Keep bars and peaks in ink, with the played part darker.
- Don't: Paint the waveform indigo. It is a magnitude, and indigo is for the one action and selection.
- Do: Give a seekable waveform a play button, position and duration beside it.
- Don't: Ship a seekable waveform with no time readout. People can't tell where they are or how long is left.

Content:
- Name the slider for what it scrubs: Recording position, Voicemail position. The default is Playback position.
- Give a live waveform a `label` only when it stands alone, such as Call audio in a supervisor's monitor. Beside a status label it stays decorative.
- Write positions and durations as m:ss in tabular figures: 2:14 of 7:05.
- Label the play button with its object: Play recording, Pause recording.

Accessibility:
- A seekable `StaticWaveform` is `role="slider"` with `aria-valuenow` in percent and `aria-valuetext` in time, such as 2:14 of 7:05, when `duration` is given.
- Without `onSeek` it is `role="img"` named by `label`.
- `Waveform` is `aria-hidden` unless you pass `label`, which makes it `role="img"`. Beside a visible status it should stay hidden.
- Live bars don't animate under reduced motion; they hold a stepped shape. The status label carries the state either way.
- Hit area: the waveform is full width and at least 32px tall by default; keep it at 32px or more on touch.
- Play and pause are separate buttons with names. The waveform never starts playback itself.
- Tab: Focuses a seekable waveform.
- →: Forward 5 seconds, or 5% without a duration. ↑ does the same.
- ←: Back 5 seconds, or 5%. ↓ does the same.
- Page Up: Forward 10 seconds, or 10%.
- Page Down: Back 10 seconds, or 10%.
- Home: Jumps to the start.
- End: Jumps to the end.

Known gaps (follow the system, not the gap):
- No product surface passes a real `level`: every live waveform runs on the simulated voice, and `simulateVoiceLevel` isn't imported anywhere in the app.
- `formatClock` takes seconds and has no hour unit (an hour reads 60:00). The history recording player and the contact center each use their own clock formatter, one taking milliseconds, one handling hours.
- `tone="primary"` paints the bars indigo. Nothing uses it, and it breaks the Ink Fill Rule.
- `StaticWaveform` has no disabled or processing state. The history player hand-rolls a Well Gray box for The recording is still processing.
- `smoothLevel` is exported but missing from the registry's export list.

API `Waveform` (extends Nothing. Only the props below are read.):
- `level?: number`. 0 to 1. Leave it out while `active` for a simulated voice.
- `bars?: number` = 24. Number of bars.
- `active?: boolean` = true. False lets the bars fall flat and stops the loop.
- `tone?: "ink" | "muted" | "primary" | "current"` = "ink". Bar color. `muted` for the other speaker; `current` inherits.
- `height?: number` = 24. Height in px.
- `barWidth?: number` = 2. Bar width in px.
- `gap?: number` = 2. Gap between bars in px.
- `label?: string`. Makes it `role="img"` with this name. Otherwise decorative.
- `className?: string`. Merged onto the row.

API `StaticWaveform` (extends Nothing):
- `peaks: number[]`. Precomputed peaks, 0 to 1. One bar each, sharing the width.
- `progress?: number` = 0. Playhead from 0 to 1. Peaks before it are drawn darker.
- `onSeek?: (progress: number) => void`. Makes it a slider. Called with 0 to 1 on click, drag and keys.
- `duration?: number`. Seconds. Sets the spoken position and the 5-second key step.
- `height?: number` = 32. Height in px.
- `label?: string` = "Playback position". Accessible name of the slider or image.
- `className?: string`. Merged onto the root.

API `simulateVoiceLevel`:
- `t: number`. Time in seconds.
- `seed?: number` = 0. Decorrelates two speakers.
- `returns?: number`. Level from 0 to 1.

API `smoothLevel`:
- `current: number`. The current level.
- `target: number`. The level to move toward.
- `dt: number`. Seconds since the last frame.
- `returns?: number`. The next level.

API `formatClock`:
- `seconds: number`. Seconds, rounded.
- `returns?: string`. For example 7:05.

### Latency sparkline

- Level: Atom
- Category: Voice
- Status: Experimental
- Import: `@oration/canon/components/voice/latency-sparkline`
- Exports: `LatencySparkline`
- Docs: /design/components/latency-sparkline

Latency sparkline draws end-to-end latency per turn as one ink line with a faint area under it, in exactly the pixels you give it. It is the line layer inside Latency timeline's sparkline view, and it can stand alone in a tight space such as a table cell, where a chart with axes won't fit. It has no axes, thresholds, readout or accessible name of its own, which is the thing people get wrong: put the value and a status label beside it, and name the cell.

When to use:
- In a table cell beside a latency figure, to show whether the last turns were steady or spiky: 720 ms and the line.
- In a dense agent or call list where every row shares one scale, so heights compare across rows.
- Inside a custom latency panel that draws its own thresholds and readout, as Latency timeline does.

When not to use:
- For per-turn latency with target and budget lines, a hover readout and keyboard inspection. Use /design/components/latency-timeline instead.
- For any other trend in a cell or a stat, such as containment or call volume. Use /design/components/mini-chart instead.
- For a single latency value with a verdict. Use /design/components/status-label instead.
- For a chart with axes, a legend and several series. Use /design/components/chart instead.

Rules:
- The Ink Fill Rule: The line is Graphite Ink at 70% over a 6% ink area. Latency is a magnitude, so it is never indigo and never colored by threshold.
- The Label-Beside-Color Rule: The sparkline carries no verdict. Put the figure and a status label (On target, Slow, Over budget) beside it so the cell reads without the line.
- The Tabular Figures Rule: The latency figure beside the line is in tabular figures, aligned right in its column.

Anatomy:
- Area: The region under the line in ink at 6%, down to the bottom edge.
- Line: A 1.5px ink line at 70% with round joins and caps, one point per turn spread across the full width.
- Last point: A 2.5px dot on the newest turn. It scales in on `spring.moderate` each time a new turn arrives.
- Active guide: A dashed vertical line in ink at 25% at the inspected turn.
- Active point: A 3.5px ring on the inspected turn, filled with the background. It replaces the last point while a turn is active.

States:
- Rest: Line, area and the last point.
- New turn: The line redraws with the new point and the last dot scales in from 0. Keyed by the last turn's `id`.
- Active: Pass `active` (an index into `turns`) to draw the guide and ring on that turn instead of the last dot.
- One turn: A single point, centered. There is no line to draw yet.
- Over the scale: Values above `scaleMax` clamp to the top 4px of the box, so a spike never leaves it.
- Empty: With no turns it draws nothing. The parent shows the empty message (Latency shows up after the first turn.).

Behavior:
- It renders an `absolute inset-0` SVG, so the parent must be `relative` and sized to the same `width` and `height` you pass.
- Width and height are pixels, not a viewBox, so strokes and dots stay round at any size. Measure the cell (Latency timeline uses a ResizeObserver) or give it a fixed size.
- Points are spread evenly across the width. y is `height − min(1, e2eMs / scaleMax) × (height − 4)`, so 0 ms sits on the bottom edge.
- Pass the same `scaleMax` to every row in a column. Latency timeline uses the larger of the budget threshold × 1.15 and the slowest turn.
- The SVG has `pointer-events: none`; inspection is the parent's job. Map the pointer's x to an index and pass it as `active`.
- Only the last point animates. Everything else redraws instantly.

Do and don't:
- Do: Share one `scaleMax` across every row, so a slow agent's line sits visibly higher.
- Don't: Scale each row to its own maximum. Every line fills its box and a 1,400 ms agent looks the same as a 700 ms one.
- Do: Put the latency figure and a status label beside the line, and name the cell.
- Don't: Put the line alone in a cell. Nobody can tell whether it is good, and screen readers get nothing.

Content:
- Name the cell with what the line covers and its range: Latency over the last 12 turns, 640 to 910 ms.
- Write figures as 720 ms, with a space before the unit, as `formatMs` from Latency timeline does.
- Use the same verdict words as Latency timeline: On target up to 800 ms, Slow up to 1,200 ms, Over budget above.

Accessibility:
- The SVG is `aria-hidden`. Wrap it in an element with `role="img"` and an `aria-label` that states the range, or rely on the visible figure beside it.
- If you make it inspectable, give it a keyboard path and announce the readout. The example lays a transparent range input over the line with `aria-valuetext`; Latency timeline uses a focusable group, arrow keys and a polite live region.
- The line is 70% ink on white and on dark, which reads as a graphic. The figure beside it carries the value at text contrast.
- The last-point entrance uses a transform, which the app's `MotionConfig reducedMotion="user"` removes under reduced motion.

Known gaps (follow the system, not the gap):
- Nothing in the app uses it on its own. Its only importer is Latency timeline; the product's latency table cells show a figure and a status dot, and trend cells use Mini chart.
- It doesn't measure itself: the caller passes pixel `width` and `height` and must provide a `relative` box of the same size.
- It has no `label` or `ariaLabel` prop and is always `aria-hidden`, so every caller has to name it.
- Target and budget lines belong to Latency timeline. A standalone sparkline has no thresholds, so it needs a status label to carry the verdict.
- The registry describes it as a table-cell component, but it is really the line layer of Latency timeline. Until it gains sizing and a label, Mini chart is the safer choice for cells.

API `LatencySparkline` (extends Nothing):
- `turns: LatencyTurn[]`. Turns in order. Only `id` and `e2eMs` are read.
- `width: number`. Width in px. Match the parent box.
- `height: number`. Height in px. Match the parent box.
- `scaleMax: number`. The ms value at the top of the box. Share it across rows.
- `active: number | null`. Index of the inspected turn, or `null` to show the last point.

API `LatencyTurn`:
- `id: string`. Stable id; keys the last-point entrance.
- `index: number`. 1-based turn number.
- `e2eMs: number`. End-to-end latency, the value drawn.
- `ttfbMs: number`. Time to first byte.
- `sttMs: number`. Speech to text.
- `llmMs?: number`. LLM time.
- `ttsMs?: number`. Text to speech.
- `speaker?: "agent" | "user"`. Whose turn it was.

## Molecules

### Hairline illustration

- Level: Molecule
- Category: Content
- Status: Experimental
- Import: `@oration/canon/components/hairline`
- Exports: `Hairline`, `HAIRLINE_NAMES`, `HAIRLINE_STUDIES`, `HAIRLINE_MODULES`, `HairlineRiffle`, `HairlineTerrain`, `HairlineExploded`, `HairlinePhosphor`, `HairlineSlow`, `HairlineTurntable`, `HairlineCustomers`, `HairlineCampaigns`, `HairlineConnect`, `HairlineCalls`, `HairlineConversations`, `HairlinePhone`, `HairlineSchedule`, `HairlineWidget`, `HairlineTickets`, `HairlineInbox`, `HairlineAgents`, `HairlineFlows`, `HairlineKnowledge`, `HairlineProcedures`, `HairlineScorecards`, `HairlineSkills`, `HairlineTools`, `HairlineVoice`, `HairlineStage`
- Docs: /design/components/hairline

Hairline illustrations are interactive figures that explain an idea by letting someone handle it. Six are studies of motion: a tray of folder-tab pages that riffle, a field that rises under the pointer, an app window taken apart into its screen sections, a dot matrix you can paint, a belt whose clock slows down, and a turntable you can flick. Eighteen more are concept figures, one for each idea in the suite, grouped by the app it lives in: customers, campaigns and integrations in CRM; calls, conversations, phone numbers, business hours and the widget in Contact Center; tickets and the inbox in Ticketing; and agents, flows, knowledge, procedures, scorecards, skills, tools and voice in the Agents Platform. They share one grammar: one projection, one 1px stroke, rounded solids with a single dim crease inside a brighter outline, no words inside the drawing, and one stroke that turns bright when something is active. They're for education and explanation, never for empty states, and every one of them rests in a pose that was drawn on purpose.

When to use:
- On a page that explains how something works, where handling the idea teaches it faster than a paragraph: Exploded beside a note on how a screen is layered, Slow beside one on throughput.
- In a feature announcement or a Page intro-sized moment that has room for a 320px-wide stage and one sentence of context.
- In the design docs and the handbook, to show a motion or interaction principle someone can feel.
- A concept figure beside the introduction to the area it names: `knowledge` above a first look at knowledge sources, `flows` in the tour of the flow builder, `tickets` in a Ticketing announcement.
- Through `Hairline` with a `name` when you want a figure with its default settings, or through the named component when you need its prop.

When not to use:
- For an empty, error or first-run state. Those get a static spot drawing that sits quietly under the title. Use /design/components/illustration instead.
- For loading. Draw the layout that's coming. Use /design/components/skeleton instead.
- To show data. The heights, layers and crates here are made up; a reader will try to read them as numbers. Use /design/components/chart instead.
- As decoration on a dense working screen, a table or a card that has content. A figure that moves under the pointer competes with every control near it.
- Below about 280px wide. The corners of chrome start to collide and the solids lose their crease.

Rules:
- The One Bright Edge Rule: At rest every silhouette is Ink 45 and every crease Ink 25. When something is active, exactly one outline turns Ink 80. Nothing fills, nothing glows, and nothing takes a hue, so the change reads at once.
- The Drawn Rest Rule: When the pointer leaves, every figure goes back to a pose that was composed: pages leaning in their tray, a low field with one rise on its lower-left side, screen sections a little apart, a turntable on a quarter turn. A flat or empty rest is a broken thumbnail.
- The Fixed Target Rule: What the pointer is over is decided by fixed bands, by casting it onto the ground, or by where a solid stood before it lifted, never by the moving drawing. A page or crate that lifts can't slide out from under the pointer and drop its own hover.
- The No Words Rule: Nothing inside the drawing is text. Names, rates and angles go to the readout in the corner, outside the figure, where they can be read and announced.

Anatomy:
- Stage: A 5:4 frame with 12px corners on its own ground, `--hl-ground`, and a 400 by 320 SVG inside it. It fills its container's width.
- Silhouette: Each solid's outline, its projected hull with every corner rounded, at Ink 45. Faces fill with the ground, so a solid hides what is behind it without looking filled.
- Crease: One dim line inside the silhouette at Ink 25: the edge where the solid's cap folds into its sides. It meets the outline halfway round a rounded corner.
- Bright edge: The one outline that turns Ink 80 when its solid is active: the pulled page, the picked layer, the crate under the pointer.
- Readout: Bottom right, 12px medium tabular figures in Graphite Ink: the name, rate or angle the figure is showing.
- Hint: Bottom left, 12px Slate Meta: how to use the figure, such as Hover or use ← →. Linked to the stage with `aria-describedby`.

States:
- Rest: The drawn pose. The readout says Rest, or is empty for Exploded, which only names a picked layer.
- Active: The pointer is over it or the arrow keys moved it. One outline turns Ink 80 over about 100ms and the readout names what is active.
- Focus visible: Keyboard focus draws Canon's 3px ring at 50% around the stage. Slow treats focus like hover and slows its clock.
- Settling: Springs run until they land. The figure keeps its place in the shared frame loop only while something in it still moves.
- Offscreen: Not painted and not ticking. An `IntersectionObserver` takes the figure out of the frame loop until it scrolls back into view.
- Reduced motion: Springs land at once and nothing plays on its own: Phosphor holds a still frame (Loop paused), Slow's belt stops (Paused) and Turntable seats without coasting. Pointer and keys still work.
- Dark theme: Ink is `currentColor` and the ground mixes `--muted` with `--card`, so the figure inverts with no extra class.

Behavior:
- Every figure on a page shares one `requestAnimationFrame` loop. It starts on input and stops as soon as every visible figure has settled; Phosphor's loop and Slow's belt keep it running only while they're on screen.
- Each figure paints into a pool of `<path>` elements and writes an attribute only when it changed, so 160 pillars cost what they draw.
- Pointer positions are mapped to the 400 by 320 stage, so the figures behave the same at every width.
- Riffle. Folder-tab pages with ruled lines stand in a tray with a handle slot. Fixed vertical bands pick the page. The picked page stands up and lifts, pages in front lean forward, pages behind lean back, and each one starts `stagger` ms after its neighbour, counted outwards from the pointer. Leaving runs the same ripple back to rest. Hit bands in the top-right corner draws the bands.
- Terrain. The pointer is cast onto the ground. Each pillar's target height falls off from that point over `radius` cells, and each pillar chases it on its own spring; pillars outside the reach sink to the floor. The nearest pillar takes the bright edge. When the pointer leaves, every pillar springs back to the rest pose: low, with one rise on the lower-left side.
- Exploded. Four screen sections, each with its own footprint: the plane with its lip, a sidebar, the content area with its window dots, and a popover with a field. Across the stage sets the gap, from 2 units to `maxGap`; the stage height is split into four bands to pick a layer. Each corner's guide drops to the highest layer under it, or to the plane.
- Phosphor. The tile floats over a base slab, tied to it by dashed corner guides, and the slab's reflection fades out below it. A 3:2 beam traces the matrix until the pointer lands on the tile. Then the pointer paints, filling the dots between samples so fast strokes don't skip. Lit dots fade over `afterglow` ms, and the loop returns 0.9 seconds after the pointer leaves the tile.
- Slow. The belt has two ends. A crate grows in at the near end and shrinks away at the far end, so nothing slides in from off the stage. Hover springs the clock to `slowTo`; leaving springs it back to 1, and the belt never stops. The crate under the pointer lifts 5 units on a `lift` spring and takes the bright edge; its lid's nine dots are its code, and its number goes to the readout. A crate drifts out from under a still pointer, and drops back as it goes.
- Turntable. Dragging turns it under the hand. On release it coasts, friction decays its speed with a time constant of `coast` ms, and below 50° a second a spring seats it on the nearest quarter turn, carrying the speed it had. Moving up and down tilts the camera between 14° and 50°. The painter's order is worked out again on every frame.
- Every figure draws a reflection under whatever stands on the floor (a tray, a plinth, a pad, a cabinet): its near walls mirrored at Ink 15, fading out over their own height. `reflection={false}` turns it off; the camera stays where it is, so the figure doesn't jump.
- The concept figures each answer the pointer in their own way: a press, a drag, a scrub, a hover. The table under Concept figures lists every one, with its keys and its one prop.
- Props are read every frame, so moving a slider changes the figure mid-gesture. Changing the number of Riffle's `items` remounts it, and so does changing `reflection`.

Do and don't:
- Do: Give the figure a job: one sentence beside it that says what handling it shows.
- Don't: Use it as an empty state. It pulls the eye from the title and the one action, and it moves when nothing has happened.
- Do: Leave it in ink, with one bright edge at a time.
- Don't: Tint it with `text-primary` or a status color. Indigo reads as selected, and every line in the figure starts competing with the page's one filled button.
- Do: Give it room: at least 320px wide, with nothing interactive pressed against it.
- Don't: Squeeze it into a card or a thumbnail. The caption, hint and readout collide, and the 1px creases turn to noise.

Content:
- Readouts are sentence case and short: Rest, Cards, 0.20×, crate 0240, Turn 45°, tilt 30°. Rates and angles use tabular figures.
- Riffle `items` and Exploded `layers` are names someone would recognise, two words at most: Northwind Freight, Popover.
- A caption names the figure, not the action: Riffle, Fig 3. The hint carries the action.
- Write `label` as a description of the picture followed by how to use it, in two short sentences.

Accessibility:
- Every figure except Phosphor is `role="group"`, focusable, and named by its description. Phosphor is `role="img"`: its loop carries the picture and painting has no keyboard equivalent.
- Each concept figure has a keyboard path to what the pointer does: arrows to pick or move, Enter to open or toggle, and digits on Phone. The concept table lists them.
- The hint is linked with `aria-describedby`, so a screen reader hears how to use the figure after its name.
- Riffle's Hit bands toggle is a real `<button>` with `aria-pressed`, reachable with Tab after the figure itself.
- Riffle, Terrain and Exploded announce their readout politely (`aria-live="polite"`) as it changes. Slow and Turntable change theirs every frame, so their readout is hidden from screen readers and the description carries the meaning.
- The drawing itself is `aria-hidden`. Nothing inside it is text.
- Under `prefers-reduced-motion: reduce`, springs land at once and nothing loops on its own. Direct manipulation (dragging the turntable, painting the tile) still follows the hand.
- Contrast comes from the ink steps of `currentColor`. Don't fade the figure with opacity; the creases are already the faintest line Canon draws.
- Tab: Focuses the figure. Slow slows its clock while focused.
- ← + →: Riffle pulls the previous or next page. Terrain moves the rise along a row. Exploded closes or opens the gap. Turntable turns a quarter.
- ↑ + ↓: Terrain moves the rise along a column. Exploded picks the layer above or below. Turntable tilts the view.
- Home + End: Riffle pulls the first or last page.
- Esc: Returns the figure to rest.

Known gaps (follow the system, not the gap):
- Experimental, and not used anywhere in apps/web yet. Adoption is zero on purpose until a page needs one.
- Tickets and Skills need a press or a drag, and Phone a press, so they do less on touch than on a pointer: a tap presses, but there is no hover to preview.
- Riffle, Exploded and Slow answer hover. On touch they only respond while a finger moves across them, and a vertical swipe scrolls the page instead.
- Phosphor has no keyboard equivalent for painting.
- The ground is an opaque mix of Well Gray and Card White, so a stage placed on the sidebar rail or a tinted well doesn't take on that surface.

API `Hairline`:
- `name: HairlineName`. Which figure to draw: a study (`riffle`, `terrain`, `exploded`, `phosphor`, `slow`, `turntable`) or a concept (`customers`, `campaigns`, `connect`, `calls`, `conversations`, `phone`, `schedule`, `widget`, `tickets`, `inbox`, `agents`, `flows`, `knowledge`, `procedures`, `scorecards`, `skills`, `tools`, `voice`).
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineRiffle`:
- `items?: string[]` = RIFFLE_ITEMS. One page per item, front to back. The readout names the pulled page. Three to ten read well.
- `stagger?: number` = 40. Milliseconds between one page moving and the next, counted outwards from the pointer. 0 moves them together.
- `showHitBands?: boolean`. Controls whether the fixed bands that pick the page are drawn, dashed, with the active band at Ink 45. Leave it out and the corner toggle owns it.
- `defaultShowHitBands?: boolean` = false. Whether the bands start drawn, when `showHitBands` is left out.
- `onShowHitBandsChange?: (show: boolean) => void`. Called with the next value when the corner toggle is pressed.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineTerrain`:
- `radius?: number` = 3. How far the rise reaches from the pointer, in cells. 1.5 to 5 read well.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineExploded`:
- `layers?: string[]` = ["Plane", "Sidebar", "Cards", "Popover"]. Names for the four layers, bottom to top: the plane, the sidebar, the content area and the popover. Only the first four are read; a missing name falls back to the default.
- `maxGap?: number` = 28. The widest the gap opens, in world units, clamped to 3 to 40. The camera leaves room for 40, so the figure never zooms.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlinePhosphor`:
- `afterglow?: number` = 520. Milliseconds a lit dot takes to fade out.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineSlow`:
- `slowTo?: number` = 0.2. The clock rate while hovered or focused, as a fraction of full speed.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineTurntable`:
- `coast?: number` = 650. The friction's time constant in milliseconds: how long a flick keeps turning before the spring seats it.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineCustomers`:
- `names?: string[]` = CUSTOMER_NAMES. Names for the six people, read by the readout.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineCampaigns`:
- `interval?: number` = 1400. Milliseconds between waves while the campaign runs.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineConnect`:
- `to?: string` = "NetSuite". The app being connected, named by the readout.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineCalls`:
- `duration?: number` = 220. The recording's length in seconds, for the readout.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineConversations`:
- `contact?: string` = "Northwind Freight". Who the agent is talking to, named by the readout.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlinePhone`:
- `initial?: string` = "415555". Digits already dialled when the figure appears, so the display isn't empty. Changing it remounts the figure.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineSchedule`:
- `hours?: readonly [number, number]` = [9, 17]. Opening and closing hour, 0 to 24. A close before the open runs past midnight. The pegs spring to new heights when it changes.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineWidget`:
- `defaultOpen?: boolean` = false. Rests with the widget open, which suits a thumbnail.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineTickets`:
- `lanes?: string[]` = ["Open", "Pending", "Resolved"]. Names for the three lanes, left to right.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineInbox`:
- `from?: string` = "Halcyon". Who the message is from, named by the readout once the letter is out.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineAgents`:
- `uses?: string[]` = ["Knowledge", "Tools", "Voice"]. Names for the three things on the ring: the document, the tool and the voice.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineFlows`:
- `steps?: string[]` = FLOW_STEPS. Names for the five steps: the trigger, its two branches, and what each branch leads to.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineKnowledge`:
- `sources?: { name: string; articles: number }[]` = KNOWLEDGE_SOURCES. The six sources, one per drawer, top left to bottom right, with their article counts.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineProcedures`:
- `steps?: string[]` = PROCEDURE_STEPS. Names for the five steps, bottom to top.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineScorecards`:
- `bands?: string[]` = ["Needs work", "Fair", "Good", "Excellent"]. Names for the four score bands, outermost ring first.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineSkills`:
- `names?: string[]` = SKILL_NAMES. Names for the nine skills, top left to bottom right.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineTools`:
- `rpm?: number` = 40. The driving gear's speed at full drive, in turns a minute.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineVoice`:
- `gain?: number` = 1. How loud it hears, 0 to 1.5. The pointer's distance scales it.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

API `HairlineStage` (extends Nothing. Only the props below reach the stage.):
- `name: string`. Set as `data-name` on the stage.
- `factory: HairlineFactory<P>`. Builds the figure's controller. Keep it stable: a new function remounts the figure.
- `params: P`. The figure's settings, read through `ctx.params.current` on every frame.
- `description: string`. The accessible name, unless `label` replaces it.
- `hintText: string`. What the hint corner says.
- `initialReadout: string`. The readout before the first frame, so the server render matches.
- `keyboard?: boolean` = false. Makes the stage focusable as `role="group"` and passes keys to the controller.
- `live?: boolean` = false. Announces the readout politely. Only for readouts that change in steps.
- `cursor?: "default" | "grab" | "crosshair"` = "default". The pointer over the stage.
- `action?: { label: string; pressed: boolean; onToggle: () => void }`. A toggle button in the top-right corner, for a view of the figure's working such as Riffle's hit bands. It carries `aria-pressed`.
- `label?: string`. Replaces the figure's own accessible description. Describe the picture and how to use it.
- `caption?: React.ReactNode`. A short caption in the top-left corner, such as Riffle or a figure number. Hidden from screen readers.
- `hint?: boolean` = true. Shows how to use the figure in the bottom-left corner. Turn it off in tight grids, where it would run into the readout.
- `reflection?: boolean` = true. Draws a faded reflection under whatever stands on the floor: a tray, a plinth, a pad. Turn it off when the figure sits on a busy surface or in a tight grid.
- `className?: string`. Merged onto the stage. The stage fills its container's width at 5:4, so size it with the container.

### Field

- Level: Molecule
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/field`
- Exports: `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldSet`, `FieldLegend`, `FieldContent`, `FieldTitle`, `FieldSeparator`
- Docs: /design/components/field

Field is the form row: it ties a label, a control, a description and an error into one `role="group"` so every form in Oration stacks the same way and the whole row reads as invalid together. It is the most imported form part in the suite, in dialogs, sign-in and settings. Field lays things out; it does not wire them. You still set `htmlFor` on the label, and `aria-invalid` and `aria-describedby` on the control, pointing at the ids of the description and the error.

When to use:
- For every labelled control in a form or dialog: Legal name, Remit-to email, Tax ID.
- With `orientation="horizontal"` for switches and checkboxes that sit beside their label and description.
- With `FieldSet` and `FieldLegend` to name a group of radios, checkboxes or choice cards, such as Payment method.
- With `FieldError` under the control for the validation message, rendered always so it appears in place.
- With `FieldSeparator` to split two ways into the same form, such as single sign-on and email.

When not to use:
- For a settings page row with the label on the left and the control on the right. Use /design/components/settings-section instead.
- For a labelled slider with a readout and a reset button. It brings its own label. Use /design/components/slider-field instead.
- For a standalone control with no description or error, such as a toolbar search. Use /design/components/search-field instead.
- For a few large radio options with descriptions, where the ready-made cards carry the selected ring. Use /design/components/choice-card instead.
- For a dialog that exists only to collect a few fields and submit. Use /design/components/form-dialog instead.

Rules:
- Every field has a label: Every control has a label, visible or screen-reader only. A placeholder shows the expected format and is never the only name, because it disappears as soon as someone types.
- Errors say how to fix it: An error is an instruction next to the field that failed: Enter a 9-digit EIN, like 12-3456789. It never blames and never says only Invalid.

Anatomy:
- Field: A `role="group"` column with 8px gaps. `data-invalid` turns its text Signal Red; `data-disabled` dims the label.
- Label: `FieldLabel`, a `Label` at 14px weight 500, linked to the control with `htmlFor`.
- Control: Any input: `Input`, `Textarea`, `Select`, `InputGroup`, `TagInput`. It draws its own focus and invalid rings.
- Description: `FieldDescription`, 14px Slate Meta. Format hints and consequences, shown before the mistake.
- Error: `FieldError`, 14px Signal Red with `role="alert"`. Renders nothing while it has no content.

States:
- Rest: Label in Graphite Ink, description in Slate Meta, the control at rest.
- Focus visible: Drawn by the control: an indigo border and a 3px ring at 50%. Field itself draws nothing.
- Invalid: `data-invalid` on Field turns the label Signal Red. `aria-invalid` on the control gives it a red border and a 3px red ring at 20%. `FieldError` shows the message.
- Disabled: `data-disabled` on Field dims the label and title to 50%; the control's own `disabled` dims it and blocks input.
- Choice card hover: When a `FieldLabel` wraps a Field, it becomes a bordered card that fills Well Gray at 50% on hover.
- Choice card checked: The card takes a 5% indigo fill and a 30% indigo border once the control inside is checked, and a 3px ring when it has keyboard focus.

Behavior:
- `orientation` is `vertical` (label above control, the default), `horizontal` (control beside its label, for switches and checkboxes) or `responsive`.
- `responsive` stacks until the surrounding `FieldGroup` is at least 28rem wide, then lays out like `horizontal`. It reads a container query, so it only works inside a `FieldGroup`.
- In a horizontal field, wrap the label and description in `FieldContent` so they stack beside the control; the row then aligns to the top.
- `FieldGroup` stacks fields 20px apart and nested groups 16px apart. Most dialogs pass `className="gap-4"`.
- `FieldSet` renders a native `<fieldset>`, so `disabled` on it disables every control inside. It tightens to 12px when it holds a checkbox or radio group.
- `FieldLegend` has two sizes: `variant="legend"` (16px, the default) for form sections and `variant="label"` (14px) when the group reads like one field.
- `FieldError` takes `children` or an `errors` array (for example from a form library). Duplicate messages are dropped; one message renders as text and several as a bulleted list.
- `FieldDescription` tightens its top margin when it sits right under a legend or before the last element, so hint and error don't drift apart.

Do and don't:
- Do: Keep a visible label above the control and put the format in the description or the placeholder.
- Don't: Use the placeholder as the only label. It disappears as soon as someone types, and the field is left with no name on screen.
- Do: Say exactly how to fix it, under the field that failed, and mark the control `aria-invalid`.
- Don't: Show a generic message such as Invalid input, or collect errors in a banner away from the fields.
- Do: Put switches and checkboxes in a horizontal field, with the label and its consequence beside the control.
- Don't: Stack a switch under its label like a text input. The row reads as two things and the label loses its hit area.

Content:
- Labels are nouns in sentence case with no colon: Remit-to email, not Remit-To Email:.
- Mark the exception, not the rule. If most fields are required, mark the optional ones with (optional) in Slate Meta.
- Descriptions state the format or the consequence in one sentence: Payments to this supplier are held until a W-9 is on file.
- Errors start with a verb and give the fix: Enter an email address, like ap@northwindfreight.com.
- Placeholders are examples of real values, such as `12-3456789` or Northwind Freight LLC, never instructions.
- Legends name the choice, not the action: Payment method, not Choose how to pay.

Accessibility:
- Link each label with `htmlFor` and the control's `id`. Generate ids with `React.useId()` in reusable forms.
- Mark the failing control `aria-invalid="true"` and point `aria-describedby` at the description and error ids. `data-invalid` on Field is styling only.
- FieldError carries `role="alert"`, so its message is announced as soon as it renders. Validate on submit or on blur, not on every keystroke.
- On submit, move focus to the first invalid control.
- Keep the submit button enabled; show errors after a submit attempt so screen reader users learn why nothing happened.
- Use `FieldSet` and `FieldLegend` for radio and checkbox groups so the group name is announced with each option.
- Inputs render at 16px below 768px so mobile browsers don't zoom on focus.
- Tab: Moves to the next control. Labels and descriptions are not stops.
- Space: Toggles a checkbox or switch in a horizontal field, or selects a choice card.
- ↑ + ↓: Moves between radios inside a `FieldSet`.

Known gaps (follow the system, not the gap):
- Field doesn't generate or connect ids. Every call site sets `htmlFor`, `aria-invalid` and `aria-describedby` by hand, and the sign-in forms carry their own `describedBy` helper to do it.
- FieldDescription and FieldError are 14px, while DESIGN.md sets helper text as 12px Caption; product call sites override them to `text-13` or `text-xs`.
- `className="text-13"` on FieldDescription or FieldError doesn't do what it says. The `cn` inside packages/canon reads `text-13` as a color, so it removes Slate Meta (or Signal Red) and leaves the 14px size: the nine product descriptions that pass it render at 14px in Graphite Ink. Use `text-[13px]`, as the examples here do.
- FieldGroup's default 20px gap sits between the named 16px and 24px steps; most product dialogs override it to `gap-4`.
- `data-invalid` recolors the label red as well as the control. DESIGN.md only specifies the red border and ring on the control.
- The choice-card recipe (a FieldLabel wrapping a Field) draws a CSS border and a 5% indigo fill when checked. DESIGN.md gives selected choice cards a 1.5 to 2px indigo ring; Choice card is the component that follows it.
- FieldSeparator paints its text on `bg-background`, so on a card in dark theme, or in a well, the label sits on a visible patch.
- FieldError always uses `role="alert"`. The accessibility bar reserves alerts for urgent errors not tied to a control; field errors are already linked through `aria-describedby`.
- 27 product files hand-roll `<fieldset>` and a styled `<legend>` (for example the shift and public key dialogs in settings) instead of using FieldSet and FieldLegend, which only 5 files import.

API `Field` (extends <div>):
- `orientation?: "vertical" | "horizontal" | "responsive"` = "vertical". Label above the control, beside it, or stacked until the parent FieldGroup is 28rem wide.
- `data-invalid?: boolean`. Turns the field's text Signal Red. Styling only.
- `data-disabled?: boolean`. Dims the label and title to 50%.

API `FieldLabel` (extends Label (<label>)):
- `htmlFor?: string`. The id of the control it names.

API `FieldDescription` (extends <p>):
- `id?: string`. Point the control's `aria-describedby` at it.

API `FieldError` (extends <div>):
- `errors?: Array<{ message?: string } | undefined>`. Messages to show when there are no children. Duplicates are dropped; several render as a list.
- `children?: ReactNode`. The message. Wins over `errors`.

API `FieldGroup` (extends <div>):

API `FieldSet` (extends <fieldset>):
- `disabled?: boolean`. Disables every control inside.

API `FieldLegend` (extends <legend>):
- `variant?: "legend" | "label"` = "legend". 16px for form sections, 14px when it reads like a field label.

API `FieldContent` (extends <div>):

API `FieldTitle` (extends <div>):

API `FieldSeparator` (extends <div>):
- `children?: ReactNode`. Text centered on the rule.

### Input group

- Level: Molecule
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/input-group`
- Exports: `InputGroup`, `InputGroupAddon`, `InputGroupInput`, `InputGroupText`, `InputGroupButton`, `InputGroupTextarea`
- Docs: /design/components/input-group

Input group puts an input or textarea and its addons in one 32px box: a leading icon, a text prefix such as `$` or `portal.cedarline.io/`, a unit such as `%` or days, or an inline button such as copy, clear or show password. The box focuses and turns invalid as one control. The mistake people make is dropping a plain `Input` inside it: only `InputGroupInput` and `InputGroupTextarea` strip the inner border and carry the `data-slot` the group's focus ring listens for.

When to use:
- For a value with a fixed prefix or suffix: a portal address after `portal.cedarline.io/`, an amount after `$`, a discount before `%`.
- For a leading icon that says what the field holds, such as a mail or search glyph.
- For one or two small inline actions that act on the field's value: copy, clear, paste, show password, verify.
- For a textarea with a header or toolbar row inside the same box, using `block-start` and `block-end` addons.
- As the base of composed fields: Password input and Key-value editor are built on it.

When not to use:
- For a plain text field with nothing attached. Use /design/components/input instead.
- For a password with a show and hide toggle. It is already built. Use /design/components/password-input instead.
- For a read-only key, ID or URL that people copy. Use /design/components/copy-row instead.
- For a toolbar search box with a leading glyph. Use /design/components/search-field instead.
- For a unit that people choose, such as seconds or minutes. Use /design/components/duration-picker instead.

Rules:
- The Machine Mono Rule: Prefixes and values that a machine will parse, such as URLs, slugs and IDs, are set in Geist Mono. Currency symbols, units and words stay in Geist Sans.
- Addons describe, buttons act: Text and icon addons are part of the value's label and never take focus. An inline button is a real control: it has a name, a tooltip when it is icon-only, and it acts only on this field.

Anatomy:
- Group: A `role="group"` box, 32px tall with 10px corners and a 1px Field Stroke. It grows to fit a textarea or block addons.
- Leading addon: `InputGroupAddon align="inline-start"` holding `InputGroupText` or a 16px icon in Slate Meta. Clicking it focuses the input.
- Control: `InputGroupInput` or `InputGroupTextarea`: the input with its own border, ring and fill removed. Its padding tightens to 6px beside an addon.
- Trailing addon: `align="inline-end"` for units, keyboard hints and `InputGroupButton`s, pulled 5px toward the edge when it holds a button.
- Focus ring: Drawn on the group, not the input: an indigo border and a 3px ring at 50% while the control has focus.

States:
- Rest: 1px Field Stroke, transparent fill (Field Stroke at 30% in dark).
- Focus visible: When the control is focused, the group takes an indigo border and a 3px Focus Indigo ring at 50%. Inside a combobox popup the ring is suppressed.
- Invalid: Any control inside with `aria-invalid` turns the group's border red with a 3px red ring at 20% (40% in dark).
- Disabled: A disabled control inside dims the whole group to 50% on a Field Stroke tint. Set `data-disabled` on the group to dim the addons too.
- Read-only: A `readOnly` input looks like rest and still focuses; pair it with a copy button.

Behavior:
- Addons use CSS `order`, so `inline-start` always draws first and `inline-end` last. Keep the DOM order the same as the visual order so Tab moves left to right.
- Clicking an addon anywhere except on a button focuses the group's input.
- `InputGroupButton` defaults to `type="button"`, `variant="ghost"` and `size="xs"` (24px). `icon-xs` is a 24px square for icon actions.
- `block-start` and `block-end` addons turn the group into a column: a header or toolbar row that spans the full width above or below the control.
- With a textarea the group's height is automatic, and the textarea grows with its content.
- Pass height changes through the group's `className`, such as `h-9` on auth screens.

Do and don't:
- Do: Put the fixed part of a value in an addon so people type only the part that changes.
- Don't: Pre-fill the fixed part into the input, where it can be deleted and has to be validated again.
- Do: Name icon-only inline buttons and give them a tooltip, such as Clear amount.
- Don't: Leave a bare X with no name. Screen reader users hear only button.
- Do: Use one or two inline actions that act on this value.
- Don't: Crowd the field with actions that belong in the form footer, such as Save or Cancel.

Content:
- Prefixes are exact: `https://`, `portal.cedarline.io/`, `$`. Don't add a trailing space or a colon.
- Units are words or standard symbols: days, %, USD. Match the unit the value is stored in.
- Inline button labels are one verb: Verify, Paste, Send test.
- Keep the label outside the group, in a Field above it. The prefix is not a label.

Accessibility:
- The group has `role="group"`; name the control itself with a `<label htmlFor>` or `aria-label`.
- Text addons are not read as part of the input's name. When the prefix matters, repeat it in the label or description: Portal address, after portal.cedarline.io/.
- Icon-only `InputGroupButton`s need an `aria-label` and a tooltip with the same words.
- The 24px inline buttons meet the 24px minimum target. On touch-first screens raise the group to `h-9` and use `icon-sm`.
- Toggle buttons such as show password expose their state with `aria-pressed`.
- Tab: Moves to the control, then to each inline button in DOM order. Addon text is skipped.
- Enter: Activates a focused inline button.

Known gaps (follow the system, not the gap):
- `InputGroupButton size="sm"` adds no classes, so it renders at Button's default 32px, and `icon-sm` is a 32px square. Both are as tall as the 32px group and overflow its 1px border. Use `xs` or `icon-xs` unless the group is `h-9`.
- Inline buttons use `--radius` minus 3px (7px) and keys minus 5px (5px); neither is on the 6, 8, 10 and 12px ramp.
- Clicking an addon focuses the group's first `input`, so with `InputGroupTextarea` a click on a block addon doesn't focus the textarea.
- Settings keeps its own password field (`apps/web/src/components/settings/account-security/password-input.tsx`) built from these parts instead of using Password input.

API `InputGroup` (extends <div>):
- `data-disabled?: boolean`. Dims the addons along with a disabled control.
- `className?: string`. Merged last. Use it for width and height, such as `h-9` or `sm:w-72`.

API `InputGroupAddon` (extends <div>):
- `align?: "inline-start" | "inline-end" | "block-start" | "block-end"` = "inline-start". Before or after the control on the same line, or as a full-width row above or below it.

API `InputGroupInput` (extends Input (<input>)):

API `InputGroupTextarea` (extends Textarea (<textarea>)):

API `InputGroupText` (extends <span>):

### Search field

- Level: Molecule
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/search-field`
- Exports: `SearchField`
- Docs: /design/components/search-field

Search field is the compact filter box at the start of a list toolbar: a 14px search glyph, a 28px input and a required accessible `label`. It filters as people type, with a controlled `value` and an `onChange` that hands you the string; there is no submit. It is deliberately bare. A clear button or a shortcut hint goes in `children`, absolutely positioned, and you widen the input's padding yourself through `inputClassName`, which replaces the default classes rather than adding to them.

When to use:
- To filter the rows of a list, table or grid in place: agents, conversations, suppliers, cohorts.
- At the start of a toolbar row, before filters and view options, at `w-full sm:w-64`.
- At the top of a panel or popover list, such as chat history, at 32px.
- With a clear button once there is a query, and Escape to clear.

When not to use:
- To search the whole workspace or jump to a page. That is the command palette. Use /design/components/command instead.
- To pick one value from a long list for a form field. Use /design/components/combobox instead.
- For a form field that happens to have a search icon, with a visible label and an error. Use /design/components/input-group instead.
- For structured filters such as status or tier. Use /design/components/filter-chip instead.

Rules:
- The Thirteen-Fourteen Rule: Toolbar search is dense UI: 13px text in a 28px control, beside 28px toolbar buttons. Below 768px it grows to 32px and 16px so phones don't zoom.
- Filtered to nothing says why: When a query hides every row, the empty state names the query and offers Clear search, not a bare No results.

Anatomy:
- Wrapper: A `relative` div that takes `className`, usually a width such as `w-full sm:w-64`.
- Glyph: A 14px lucide search icon in Slate Meta, 10px from the left edge, hidden from assistive tech.
- Input: An `Input` at 28px with 32px of left padding for the glyph. It is meant to be 13px; see the gaps. `label` becomes its `aria-label`.
- Trailing slot: `children`, positioned by you: a clear button or a key hint. Add right padding to the input so text doesn't run under it.

States:
- Rest: Field Stroke border, Slate Meta placeholder.
- Focus visible: The input's indigo border and 3px ring at 50%.
- Filled: The query in Graphite Ink. Show a clear button in the trailing slot.
- No results: Owned by the list below: name the query and offer to clear it.
- Disabled: Not supported by props today; there is no `disabled` pass-through.

Behavior:
- Controlled only: pass `value` and `onChange(value: string)`. Filter on every change; debounce only when the filter is expensive.
- `onKeyDown` reaches the input, so Escape can clear the query or ArrowDown can move into a result list.
- `type` reaches the input. `type="search"` adds the browser's own clear control in Chromium and Safari; don't pair it with your own clear button.
- `inputClassName` and `iconClassName` replace the defaults. Copy the recipe and change one part: for a clear button, `h-7 pr-8 pl-8 max-md:h-8 md:text-[13px]`.
- Below 768px the input is 32px at 16px text, so iOS doesn't zoom on focus.
- There is no `ref` or `id`. To focus it from a shortcut, find the input inside a wrapper ref.

Do and don't:
- Do: Give it a `label` that names what is searched, such as Search suppliers, and a placeholder that hints at what matches.
- Don't: Rely on the placeholder alone, or label every field Search, so a screen reader can't tell two apart.
- Do: When the query hides everything, say which query and offer Clear search.
- Don't: Show a bare No results with no way back.

Content:
- Labels are Search plus the thing: Search suppliers, Search the transcript.
- Placeholders list what matches, in sentence case with no ellipsis: Search name, phone or vendor ID.
- No-result copy quotes the query: No suppliers match “zenith”.
- Name the clear button for what it clears: Clear search.

Accessibility:
- `label` is required and becomes the input's `aria-label`. There is no visible label, so make it specific.
- The glyph is `aria-hidden`; the name comes from `label` alone.
- Announce result counts in a polite live region (`role="status"`) near the list, such as 12 suppliers.
- A clear button needs an `aria-label` and a tooltip, and should return focus to the input.
- Don't autofocus a toolbar search on page load; it hides the page heading from screen reader users.
- Tab: Moves focus to the input.
- Esc: Clears the query when you wire it through `onKeyDown`, as the transcript search does.
- /: A common page shortcut to focus search. Show it as a key hint in the trailing slot.

Known gaps (follow the system, not the gap):
- There is no built-in clear button or shortcut hint. The registry describes both; today they are `children` you position yourself.
- The default input renders at 14px from 768px up, not the 13px it asks for. The `cn` inside packages/canon reads `text-13` as a color, so Input's `md:text-sm` survives the merge and wins. Pass `md:text-[13px]` in `inputClassName`, as the examples on this page do; the hero shows the default.
- `inputClassName` and `iconClassName` replace the default classes instead of merging with them, so a call site that only wants `pr-8` loses the height, padding and 13px size.
- No `id`, `ref`, `name`, `disabled` or `autoFocus` pass-through. The breadcrumb switcher ships its own search field (`apps/web/src/components/shell/breadcrumb-switcher/search-field.tsx`) and the AI governance kit wraps this one to force `type="search"`.

API `SearchField`:
- `value: string`. The query.
- `onChange: (value: string) => void`. Called with the new query on every keystroke.
- `label: string`. The input's accessible name.
- `placeholder: string`. What people can search by.
- `onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>`. Key handler on the input, for Escape to clear or arrows into results.
- `type?: React.HTMLInputTypeAttribute`. The input type. `"search"` adds the browser clear control.
- `className?: string`. On the wrapper, usually a width.
- `inputClassName?: string` = "h-7 pl-8 text-13 max-md:h-8 max-md:text-base". Replaces the input's classes.
- `iconClassName?: string` = "pointer-events-none absolute top-1/2 left-2.5 size-3.5 -translate-y-1/2 text-muted-foreground". Replaces the glyph's classes.
- `children?: ReactNode`. Rendered after the input inside the relative wrapper: a clear button or a key hint.

### Password input

- Level: Molecule
- Category: Inputs
- Status: Beta
- Import: `@oration/canon/components/password-input`
- Exports: `PasswordInput`
- Docs: /design/components/password-input

Password input is a password field with a trailing eye button that shows and hides what was typed. It is built on Input group and sized for the sign-in and sign-up screens, where fields are 36px. The eye is a toggle: it keeps the name Show password and reports its state with `aria-pressed`. It is for secrets a person types and remembers, not for API keys and tokens that people copy; those belong in a copy row or a key-value editor with secrets.

When to use:
- For the password on sign-in, with `autoComplete="current-password"`.
- For a new password on sign-up or reset, with `autoComplete="new-password"` and the rules shown up front.
- For re-entering a password to confirm a sensitive change, such as transferring workspace ownership.

When not to use:
- For an API key, signing secret or token that people copy rather than type. Use /design/components/copy-row instead.
- For header values or environment variables that may be secret. Use /design/components/key-value-editor instead.
- For a one-time code from email or SMS. Use /design/components/input-otp instead.
- For a masked field with more than one inline action. Use /design/components/input-group instead.

Rules:
- Never block paste: People paste passwords from password managers. Don't prevent paste, don't disable autofill, and set the right `autoComplete` so managers offer to fill and save.
- Rules before mistakes: Show the requirements for a new password before people type, and tick them off as they are met, instead of rejecting the password after submit.

Anatomy:
- Group: An Input group at 36px (`h-9`). `className` lands here, not on the input.
- Input: `type="password"` until revealed. Spell check and auto-capitalization are off.
- Visibility toggle: A 24px ghost icon button with `aria-pressed`, named Show password. The eye and eye-off icons cross-fade in place.
- Tooltip: Show password or Hide password, after the 400ms tooltip delay.

States:
- Masked: The default. The eye icon is shown.
- Revealed: Plain text. The toggle is pressed and shows the eye-off icon. It stays revealed until pressed again.
- Focus visible: The group's indigo border and 3px ring at 50%. The toggle has its own ring.
- Invalid: `aria-invalid` on the input gives the group a red border and a 3px red ring at 20%.
- Disabled: `disabled` dims the group to 50%, for example while an account is locked after too many attempts. The toggle stays clickable.

Behavior:
- Every prop except `type` and `className` goes to the inner input: `id`, `name`, `value`, `onChange`, `autoComplete`, `aria-*`, `ref`.
- `className` goes to the Input group wrapper, so use it for height and width, such as `h-8` in a settings dialog.
- Visibility is internal state. It starts masked on mount and there is no prop to control it or mask again after submit.
- The toggle is a `type="button"`, so it never submits the form, and it doesn't move focus from the button.
- The icons cross-fade on a 300ms spring with a slight blur. Under reduced motion only the fade runs.

Do and don't:
- Do: Show the rules for a new password under the field and tick them off as they are met.
- Don't: Reveal the rules only in an error after submit, so people guess and fail first.
- Do: Use it for passwords people type. Use a copy row for keys people copy.
- Don't: Put an API signing secret in a password field, where it can be edited and can't be copied in one click.

Content:
- The label is Password, or New password and Confirm new password when both appear.
- State requirements as positives: At least 12 characters, One number or symbol.
- Errors give the fix: Enter your password. or Use at least 12 characters. Don't say whether the email or the password was wrong after a failed sign-in; say That email and password don't match.
- Pair the field with a Forgot password? link at the label's right edge on sign-in.

Accessibility:
- Label the input with a `<label htmlFor>`; the toggle's name doesn't name the field.
- Set `autoComplete` to `current-password` or `new-password`, and `name="password"`, so managers fill and save correctly.
- The toggle keeps one name, Show password, and reports pressed and not pressed. That is the correct toggle pattern; its tooltip switches wording.
- Link rules and errors with `aria-describedby` so they are read with the field.
- The toggle is 24px, the minimum target; auth screens are touch-friendly because the field around it is 36px.
- Tab: Moves from the input to the visibility toggle.
- Space: Shows or hides the password when the toggle has focus.
- Enter: Submits the form from the input.

Known gaps (follow the system, not the gap):
- It is 36px by default, taller than the 32px control height. That matches the auth screens; in settings and dialogs pass `className="h-8"`.
- The tooltip says Hide password while revealed but the accessible name stays Show password, so sighted and screen reader users get different words.
- Only the auth screens import it. Settings has its own copy (`apps/web/src/components/settings/account-security/password-input.tsx`) with no tooltip and a name that changes with state.
- There is no `visible` or `onVisibleChange` prop, so a form can't mask the field again after a failed submit.

API `PasswordInput` (extends <input>, without `type`):
- `className?: string` = "h-9". Applied to the Input group wrapper, not the input.
- `autoComplete?: string`. `"current-password"` to sign in, `"new-password"` to create one.
- `aria-invalid?: boolean`. Turns the group red.
- `disabled?: boolean`. Dims the group and blocks input.

### One-time code

- Level: Molecule
- Category: Inputs
- Status: Beta
- Import: `@oration/canon/components/input-otp`
- Exports: `InputOTP`, `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator`
- Docs: /design/components/input-otp

One-time code draws a verification code as a row of single-character slots over one real input, so paste, SMS autofill through `autocomplete="one-time-code"`, Backspace and the caret all behave like a normal field. Oration uses it for sign-in verification and SMS two-factor setup: six digits, in one run or two groups of three. The mistake people make is setting `aria-invalid` only on `InputOTP`. The real input sits outside the slot groups, so the slots stay gray; pass `aria-invalid` to each `InputOTPSlot` as well.

When to use:
- For a six-digit code sent by email or SMS to verify a sign-in or a new device.
- For confirming a phone number while turning on SMS two-factor.
- For an authenticator app code when enrolling or signing in.
- For short, fixed-length recovery codes, with a pattern that allows letters.

When not to use:
- For a password or passphrase people remember. Use /design/components/password-input instead.
- For a long or variable-length code, such as a bank micro-deposit reference. Use /design/components/input instead.
- For a PIN people set and reuse. Mask it and use a regular field. Use /design/components/password-input instead.
- For showing a code for people to copy, such as a backup code list. Use /design/components/copy-row instead.

Rules:
- Never block paste: Codes arrive in email and SMS and get pasted. One real input underneath makes paste and one-time-code autofill work; don't break it with per-slot inputs.
- The Tabular Figures Rule: Digits in slots are set in tabular figures so every slot holds its character at the same width and the row doesn't shimmer as it fills.

Anatomy:
- Container: `InputOTP`: a flex row that holds the groups and, on top of them, the transparent real input that receives typing and paste.
- Group: `InputOTPGroup` joins its slots into one shape with shared borders and 10px outer corners.
- Slot: `InputOTPSlot index`: a 32px square showing one character from the input's value.
- Active slot: The slot where the next character lands: an indigo border and a 3px ring at 50%, with a 1px blinking caret while empty.
- Separator: `InputOTPSeparator`: a 16px minus sign with `role="separator"` between groups.

States:
- Empty: Every slot shows its Field Stroke border.
- Active: While focused, the slot at the caret takes the indigo border and ring and rises above its neighbors; an empty active slot shows the blinking caret.
- Filled: Slots show their characters in Graphite Ink.
- Invalid: With `aria-invalid` on each slot, borders turn Signal Red and the group takes a 3px red ring at 20%. The active slot keeps a red ring.
- Disabled: `disabled` dims the whole row to 50% and shows a not-allowed cursor.
- Verified: No built-in style. Sign-in tints the slot borders Ledger Green at 60% while it moves on.

Behavior:
- `maxLength` sets how many characters the input takes; render the same number of slots, indexed from 0.
- `onChange(value)` receives the whole string; `onComplete(value)` fires once the last slot fills, including after a paste or autofill. Verify there.
- `pattern` filters what can be typed or pasted: `^\d+$` for digits, `^[a-zA-Z0-9]+$` for recovery codes. Non-matching input is ignored.
- Pasting a code fills every slot at once. `pasteTransformer` can strip spaces or dashes before it lands.
- `inputMode` defaults to `numeric`, so phones show the number pad.
- Groups are only visual. Characters flow across them and the value never contains the separator.
- `containerClassName` styles the row, for example `w-full gap-2` with `flex-1` groups to fill a card.

Do and don't:
- Do: Mark every slot invalid and say what to do next under the row: check the latest email, or resend.
- Don't: Set `aria-invalid` only on the root, so the slots stay gray and the error floats unexplained.
- Do: Verify with `onComplete` as soon as the last digit lands, and offer a way to send a new code.
- Don't: Make people press Verify after the sixth digit when nothing else is left to do.

Content:
- Say where the code went and how long it lasts: We sent a 6-digit code to maya.okafor@cedarline.io. It expires in 10 minutes.
- The label names the code: Verification code or 6-digit code.
- Errors give a next step: That code didn't match. Check the latest email or send a new code.
- Offer Send a new code with a countdown rather than a bare resend link that can be hammered.

Accessibility:
- There is one real input, so screen readers announce a single text field with its whole value. Name it with `aria-label` or a `<label htmlFor>` pointing at its `id`.
- Slots are presentational; don't give them roles or tab stops.
- Set `autoComplete="one-time-code"` so iOS and Android offer the code from SMS.
- Link the instructions and errors with `aria-describedby` on `InputOTP`.
- The caret blinks with opacity only; it doesn't move, so it stays on under reduced motion.
- Default slots are 32px. On touch screens enlarge them with `className` (the sign-in form uses 44 to 48px).
- 0 + – + 9: Types into the active slot and moves to the next.
- Backspace: Deletes the previous character.
- ← + →: Moves the caret between filled slots.
- ⌘ + V: Pastes a whole code into every slot.
- Enter: Submits the surrounding form.

Known gaps (follow the system, not the gap):
- `aria-invalid` on `InputOTP` doesn't reach the slots: the library renders the input beside the groups, not inside them, so the group's `has-aria-invalid` and the slot's `aria-invalid:` styles only apply when each slot gets `aria-invalid`. Sign-in paints its own red classes instead.
- Slots are 32px with 14px text and there's no size prop. Both product call sites override them: SMS setup to 40px at 16px, sign-in to 44 to 48px at 18px.
- There's no success style; sign-in adds `border-success/60` by hand.
- `REGEXP_ONLY_DIGITS` and the other pattern constants from `input-otp` aren't re-exported, so call sites write the pattern strings themselves.
- The separator's icon has no color of its own; call sites pass `text-subtle-foreground`.

API `InputOTP` (extends input-otp `OTPInput` (<input> attributes)):
- `maxLength: number`. Number of characters, and of slots you render.
- `value?: string`. The code, controlled.
- `onChange?: (newValue: string) => unknown`. Called with the whole code on every change.
- `onComplete?: (...args: any[]) => unknown`. Called with the code when the last slot fills.
- `pattern?: string`. A regular expression source that each entry must match, such as `^\d+$`.
- `inputMode?: string` = "numeric". The on-screen keyboard.
- `pasteTransformer?: (pasted: string) => string`. Cleans pasted text before it is applied.
- `containerClassName?: string`. Classes for the row that holds the groups.
- `textAlign?: "left" | "center" | "right"` = "left". Where the hidden caret sits; affects which slot is active on click.
- `pushPasswordManagerStrategy?: "increase-width" | "none"` = "increase-width". Makes room for password manager badges.
- `render?: (props: RenderProps) => ReactNode`. Render slots from state instead of `children`.
- `disabled?: boolean`. Dims the row and blocks input.

API `InputOTPGroup` (extends <div>):

API `InputOTPSlot` (extends <div>):
- `index: number`. Position in the code, from 0.
- `aria-invalid?: boolean`. Paints the slot and its group red. Set it on every slot.

API `InputOTPSeparator` (extends <div>):

### Tag input

- Level: Molecule
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/tag-input`
- Exports: `TagInput`
- Docs: /design/components/tag-input

Tag input turns typed or pasted values into removable chips inside one field: invite emails, allowed domains, opt-out keywords, enum options, header names. Enter, a comma or leaving the field commits the entry; Backspace in an empty field removes the last chip; pasting a list splits it. It is used across settings and agent configuration. The chips are values inside a control, drawn in Well Gray; they are not option tags, so they never take the categorical hues, and an entry that fails `validate` turns into a Signal Red tint instead.

When to use:
- For a short list of free-form values: invite emails, allowed domains, keywords, phrases.
- For machine strings such as enum values, variable names or header names, with `mono`.
- When people often paste a list, from a spreadsheet column or an email thread.
- With `suggestions` when common values exist but anything is allowed, such as supplier tags.
- With `max` when the list has a hard limit, such as five escalation phrases.

When not to use:
- For choosing from a fixed, known set. Use a multi-select with chips. Use /design/components/combobox instead.
- For displaying values on a record. Values are tags, not controls. Use /design/components/tag instead.
- For pairs of names and values, such as headers with their values. Use /design/components/key-value-editor instead.
- For active filters above a list. Use /design/components/filter-chip instead.
- For a single value. Use a plain field. Use /design/components/input instead.

Rules:
- The Option Hue Rule: The ten categorical hues belong to select-option values on records. Chips in a tag input are entries being edited, so they stay Well Gray; only an invalid entry changes, to a red tint.
- The Machine Mono Rule: Set `mono` when the entries are machine strings, such as `vendor_id` or `X-Cedarline-Tenant`. Emails, phrases and names stay in Geist Sans.

Anatomy:
- Field: At least 32px tall with 10px corners and a Field Stroke border. It wraps chips onto new lines and focuses the text input when you click its padding.
- Chip: 24px, 8px corners, Well Gray with 13px Graphite Ink text, or Geist Mono at 12px with `mono`. Invalid chips are a 10% red tint with red text.
- Remove button: A 20px X with a 28px hit area, named Remove plus the value. It returns focus to the text input.
- Text input: The entry being typed, at least 96px wide. The placeholder shows only while there are no chips.
- Counter: With `max`, a 12px tabular count such as 3/5 at the right edge.

States:
- Empty: The placeholder in Slate Meta.
- Focus: The field takes an indigo border and a 3px ring at 50% while the input has focus.
- Invalid chip: An entry that fails `validate` stays in the list as a red-tint chip, announced with (invalid).
- Rejected: With `rejectInvalid`, a failing entry stays in the text input and the field turns red until it is edited.
- Invalid field: `aria-invalid` turns the border red with a 3px red ring at 20%, for errors about the whole list.
- Suggestions open: A popover list under the field, up to eight matches, with a Well Gray highlight that glides between options.
- Full: At `max`, the text input becomes read-only and collapses, suggestions stop, and the counter reads 5/5.
- Disabled: The field dims to 50%, and chips can't be removed.

Behavior:
- Enter commits the entry. So does any character matched by `split` (a comma or a new line by default) while typing or pasting, and leaving the field.
- Each entry runs through `normalize` first (trimming by default), then duplicates are dropped unless `allowDuplicates` is set.
- Pasting text that contains a split character adds every part at once. Parts beyond `max` are dropped.
- Backspace in an empty input removes the last chip. The X on a chip removes that chip and keeps focus in the field.
- With `suggestions`, matches filter by a case-insensitive substring and exclude values already added. Arrow keys move through them and wrap; Enter picks; Escape closes the list without leaving the field.
- Chips added after mount scale in from 0.96 with a fade on the fast spring. Chips that were there on load don't animate. Under reduced motion only the fade runs.
- It is controlled: `value` is the array and `onChange` gets the next array on every add and remove.

Do and don't:
- Do: Validate each entry and keep failing entries visible in red, so people can fix them in place.
- Don't: Accept anything and fail the whole list on save with a message that doesn't say which entry is wrong.
- Do: Keep chips Well Gray. They are values being edited.
- Don't: Color chips with tag hues, which makes an input look like a record's select values.
- Do: Split on the characters people actually paste: commas and new lines, plus spaces for emails and domains.
- Don't: Make people add a pasted list of forty emails one at a time.

Content:
- The label names the list: Invite by email, Allowed websites, Opt-out keywords.
- The placeholder says how to add: Add an email and press Enter. It disappears once there's a chip.
- Say the limit in the description when there is one: Up to 5 phrases. The counter shows how many are left.
- When entries are invalid, the description or error says the format: Use a full domain, like northwindfreight.com.

Accessibility:
- Name the input with `id` and a `<label htmlFor>`, or with `aria-label`.
- With `suggestions`, the input is a combobox: `aria-expanded`, `aria-controls`, `aria-autocomplete="list"` and `aria-activedescendant` point at a listbox named Suggestions.
- Each remove button is named Remove plus the value, so a list of chips reads clearly.
- Invalid chips add a screen-reader-only (invalid) after the value.
- With `max`, a hidden 3 of 5 added is linked to the input through `aria-describedby`.
- Pass `aria-describedby` for your description or error; it is combined with the counter.
- Enter: Adds the typed entry, or the highlighted suggestion.
- ,: Adds the typed entry (any `split` character does).
- Backspace: In an empty input, removes the last chip.
- ↓ + ↑: Moves through suggestions, wrapping at the ends.
- Esc: Closes suggestions and keeps the typed text.
- Tab: Moves through each chip's remove button, then the text input. Leaving the input commits the entry.

Known gaps (follow the system, not the gap):
- Duplicates, and entries past `max`, are dropped without a message; the typed text just disappears.
- Adding or removing a chip isn't announced, and the chips aren't in a list, so screen reader users don't hear how many entries there are unless `max` is set.
- With `mono`, the text input asks for 13px (`md:text-13`) but renders at 14px: the `cn` inside packages/canon reads `text-13` as a color, so `md:text-sm` stays and wins.
- The invalid ring stays at 20% in dark, where Input uses 40%.
- Chips use 8px corners inside a 10px field with 4px of padding; concentric corners would be 6px.

API `TagInput`:
- `value: string[]`. The entries.
- `onChange: (value: string[]) => void`. Called with the next array on every add and remove.
- `id?: string`. The text input's id, for `<label htmlFor>`.
- `placeholder?: string`. Shown while there are no chips.
- `aria-label?: string`. The name when there's no visible label.
- `aria-describedby?: string`. Ids of the description or error.
- `aria-invalid?: boolean`. Marks the whole field invalid.
- `validate?: (tag: string) => boolean`. Return false to flag an entry. Flagged entries stay as red chips.
- `rejectInvalid?: boolean` = false. Keep failing entries in the text input instead of adding them.
- `normalize?: (raw: string) => string` = (raw) => raw.trim(). Runs on every entry before it is added, such as lowercasing emails.
- `split?: RegExp` = /[,\n]+/. Characters that commit an entry while typing or pasting.
- `suggestions?: string[]`. Values offered as you type.
- `max?: number`. The most entries allowed. Shows a counter.
- `allowDuplicates?: boolean` = false. Allow the same value twice.
- `mono?: boolean` = false. Geist Mono chips and input, with spell check off.
- `disabled?: boolean` = false. Dims the field and blocks changes.
- `className?: string`. On the outer wrapper.

### Editable text

- Level: Molecule
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/editable-text`
- Exports: `EditableText`
- Docs: /design/components/editable-text

Editable text shows a value as plain text and turns it into an input when clicked, for renaming in place: a workflow name in the header, a ticket title, a supplier's legal name in its attribute list. Enter or clicking away commits, Escape restores, and there is no Save button. The mistake people make is styling it only through `className`. That styles the resting button; the input that appears on click inherits its type from the parent, so put the font size and weight on the wrapper, or pass them to `inputClassName` too, or the text jumps when editing starts.

When to use:
- To rename the thing a page is about, in its header: a workflow, a ticket, a supplier.
- For short text attributes in a record's attribute list, one value per row.
- For a description that people edit rarely, with `multiline`.
- Where each change saves on its own and confirms with a toast or a quiet saved state.

When not to use:
- In a form with a Save button, where all fields commit together. Use /design/components/field instead.
- For a value with a fixed set of options, such as stage or tier. Use /design/components/select instead.
- For long-form text such as prompts or instructions. Use /design/components/prompt-editor instead.
- For a value people copy more often than they change, such as an ID. Use /design/components/copy-row instead.

Rules:
- Every change is acknowledged: A commit saves right away, so tell people it happened: a toast with Renamed to Northwind Freight LLC, or an Undo when the change is easy to regret.
- The Machine Mono Rule: Machine values such as vendor IDs are set in Geist Mono in both the resting and editing states; pass the class to `className` and `inputClassName`.

Anatomy:
- Display button: A full-width `<button>` with 8px corners and 6px side padding, showing the value truncated to one line (three with `multiline`).
- Placeholder: Shown in Faint Slate when the value is empty: Empty by default.
- Editor: An input, or a three-row textarea with `multiline`, on the White Plane with a 2px indigo ring at 50%. It opens with the text selected.

States:
- Rest: The value as plain text; nothing marks it as editable until hover.
- Hover: A Well Gray fill over 100ms and a text cursor.
- Focus visible: A 3px indigo ring at 40% on the display button.
- Editing: The input replaces the button in place, with a 2px indigo ring at 50% and the text selected.
- Empty: The placeholder in Faint Slate.

Behavior:
- Click, Enter or Space on the display button opens the editor with the whole value selected.
- Enter commits a single-line value. With `multiline`, Enter adds a new line and ⌘Enter commits.
- Escape restores the previous value and closes the editor. Blur commits.
- The committed value is trimmed. `onCommit` only runs when it differs from `value`, and it does run with an empty string, so guard empties in your handler.
- It holds no saved state of its own: update `value` from `onCommit`, and a new `value` from outside replaces the draft while not editing.
- `className` styles the display button; `inputClassName` styles the editor. The editor's font comes from the parent element.

Do and don't:
- Do: Set the heading type on the wrapper so the editor matches the text it replaces.
- Don't: Put `text-lg` only on `className`. Click it: the editor drops to 14px and the header jumps.
- Do: Label it with the attribute's name, such as Legal name, so it is announced as Legal name: Northwind Freight LLC. Edit.
- Don't: Leave the value to name itself. A row of bare values reads as a list of buttons with no meaning.

Content:
- The placeholder invites the first value: Add a description, Add a legal name. Use Empty only in dense attribute lists.
- Confirm renames with the new name: Renamed to Halcyon Logistics.
- If an empty value isn't allowed, restore the old one and say why in a toast: A supplier needs a name.

Accessibility:
- `label` is required. The display button is announced as {label}: {value}. Edit, and the editor uses `label` as its name.
- The display is a real `<button>`, so it is in the tab order and opens with Enter or Space.
- The editor takes focus when it opens and selects its text.
- After Enter or Escape, focus is not returned to the display button; see the gaps below.
- Keep the hit area at least 24px tall; `h-7` or `h-8` in attribute lists.
- Enter: On the display button, opens the editor. In a single-line editor, commits.
- Space: Opens the editor from the display button.
- ⌘ + Enter: Commits a multiline value.
- Esc: Restores the previous value and closes the editor.
- Tab: Leaves the editor, which commits.

Known gaps (follow the system, not the gap):
- Focus isn't returned to the display button after Enter or Escape. The editor unmounts and focus falls to the page, so keyboard users lose their place.
- Multiline commits only on ⌘Enter (`metaKey`). On Windows and Linux, Ctrl+Enter inserts a new line instead.
- Empty values commit. There is no validation, error or pending state for a save that fails.
- `className` doesn't reach the editor. Call sites that set heading type on it, such as the ticket title, change size when editing starts.
- The editing ring is 2px while the suite's field focus ring is 3px, and the hover fill runs 100ms against the 150ms standard.

API `EditableText`:
- `value: string`. The saved value.
- `onCommit: (value: string) => void`. Called with the trimmed value when it changed.
- `label: string`. The attribute's name, used for both the button and the editor.
- `placeholder?: string` = "Empty". Shown when the value is empty.
- `multiline?: boolean` = false. A three-row textarea; ⌘Enter commits and the display clamps to three lines.
- `className?: string`. Classes for the display button.
- `inputClassName?: string`. Classes for the editor.

### Slider field

- Level: Molecule
- Category: Inputs
- Status: Beta
- Import: `@oration/canon/components/slider-field`
- Exports: `SliderField`
- Docs: /design/components/slider-field

Slider field is a labelled slider for tuning one number in settings: a 14px label, a live readout, captions for both ends, an optional hint, and a Reset to … button that appears once the value leaves its default. Agent settings use it for the interruption word threshold, speaking speed, voice stability and ambient volume. The mistake people make is leaving `format` as the raw number. The readout, the end captions, the reset label and the value screen readers hear all come from `format`, so put the unit there: 2 words, 30%, 1.00×.

When to use:
- For a setting on a bounded scale where the relative position matters more than the exact number: speed, stability, volume.
- For a small integer range with meaningful ends, such as an interruption threshold from Stops at any sound to Only full sentences.
- When the setting has a recommended default people should be able to return to.
- Beside a preview that updates as the value moves, so people see what the number means.

When not to use:
- For an exact value people type, such as a timeout in seconds. Use /design/components/duration-picker instead.
- For a range with two thumbs, or a bare slider without the label row. Use /design/components/slider instead.
- To show a measured amount that people can't change. Use /design/components/meter instead.
- For two to five named modes rather than a scale. Use /design/components/segmented-control instead.

Rules:
- The Ink Fill Rule: A slider's indigo fill marks a value someone is setting. When the amount is measured rather than chosen (credits used, talk ratio), draw it in ink steps with a meter instead.
- The Tabular Figures Rule: The readout and the end captions are tabular, so the readout doesn't jitter as the value changes.

Anatomy:
- Label: Base UI `Slider.Label` at 14px weight 500, with an optional `info` tip beside it.
- Reset button: An extra-small ghost button, Reset to plus the formatted default. It appears only while the value differs from `defaultValue`.
- Readout: The formatted value at 13px weight 500 in tabular figures, right-aligned.
- Track: A 4px Well Gray track with an indigo fill, and a 14px white thumb with an indigo edge and a 20px extra hit area around it.
- Captions: 12px Slate Meta labels for each end: `minLabel` and `maxLabel`, or the formatted min and max.
- Hint: An optional 13px sentence under the slider, linked to the thumb.

States:
- Rest: The fill runs from the start to the thumb.
- Hover: A 3px Focus Indigo ring at 50% around the thumb, over 150ms.
- Focus visible: The same 3px ring while the thumb has keyboard focus.
- Dragging: The ring stays while the thumb is pressed.
- Changed: The reset button scales in from 0.96 with a fade on the fast spring, and leaves on the faster exit.
- Disabled: The track and thumb dim to 50% and ignore input. The label and readout stay at full strength.

Behavior:
- Controlled only: `value` and `onChange(value)`. It holds a single number.
- `step` defaults to 1. Round in `onChange` when the step is a fraction, as speed does with `Math.round(next * 100) / 100`, to avoid floating-point tails.
- The thumb aligns to the track's edges at min and max, so it never overhangs the row.
- Clicking anywhere on the track moves the thumb there; dragging follows the pointer.
- The reset button sets `defaultValue` through `onChange` and then disappears.
- Pass an `InfoTip` to `info` for jargon such as stability or interruption threshold.

Do and don't:
- Do: Format the value with its unit and name what each end means: Slower and Faster, Silent and Loud.
- Don't: Show a raw 0.3 with 0 and 1 at the ends, so people have to guess the scale.
- Do: Set `defaultValue` to the recommended setting so people can get back to it in one click.
- Don't: Leave people to remember where the default was after a few experiments.

Content:
- The label names the setting, not the control: Speed, Interruption word threshold.
- End captions describe the effect, in two or three words: Stops at any sound, Only full sentences.
- `format` includes the unit and pluralizes: 1 word, 3 words.
- The hint says when to change it: Slow down slightly for agents that read long reference numbers.

Accessibility:
- The label is a Base UI `Slider.Label`, so the thumb is named by it.
- `format` also sets `aria-valuetext`, so screen readers hear 30% instead of 0.3.
- The visible readout and end captions are `aria-hidden`. If an end's meaning matters, repeat it in `hint`, which is linked with `aria-describedby`.
- The thumb is 14px with an extra 10px on every side, for a 34px target.
- When the value is off, explain why beside it or in the hint rather than only dimming it.
- ← + →: Moves by one `step`. Up and down arrows do the same.
- Shift + →: Moves by 10 units, Base UI's large step.
- Page Up + Page Down: Moves by 10 units.
- Home + End: Jumps to `min` or `max`.

Known gaps (follow the system, not the gap):
- `largeStep` isn't exposed, so Shift+arrow and Page Up or Down move by Base UI's default of 10 units. On a 0 to 1 or 1 to 5 range, one press jumps to the end.
- The reset button unmounts as soon as it is pressed, so keyboard focus falls to the page.
- The end captions are `aria-hidden`; their meaning reaches screen readers only if it is repeated in `hint`.
- The thumb is hard-coded `bg-white`, and disabled dims only the track, not the label and readout.
- The fill is Quiet Indigo. DESIGN.md lists checked controls, selection and focus as indigo's uses but doesn't name sliders.

API `SliderField`:
- `label: ReactNode`. The setting's name.
- `value: number`. The current value.
- `onChange: (value: number) => void`. Called as the thumb moves and when reset is pressed.
- `min: number`. The low end.
- `max: number`. The high end.
- `step?: number` = 1. The increment.
- `defaultValue?: number`. The recommended value. Shows the reset button whenever `value` differs.
- `format?: (value: number) => string` = (v) => String(v). Formats the readout, captions, reset label and `aria-valuetext`.
- `minLabel?: ReactNode`. Caption for the low end. Defaults to `format(min)`.
- `maxLabel?: ReactNode`. Caption for the high end. Defaults to `format(max)`.
- `hint?: ReactNode`. A sentence under the slider, linked to the thumb.
- `info?: ReactNode`. An `InfoTip` beside the label.
- `disabled?: boolean`. Dims the track and blocks input.
- `id?: string`. Base for the hint's id.
- `className?: string`. On the root.

### Duration picker

- Level: Molecule
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/duration-picker`
- Exports: `DurationPicker`, `formatDuration`, `formatDurationShort`
- Docs: /design/components/duration-picker

Duration picker edits one length of time, stored in milliseconds, as a number beside a unit select, with optional preset chips and a plain-language readout such as Hangs up after 1 minute of silence. Oration uses it for silence timeouts, retention windows, shift and break lengths and retry delays. Switching the unit converts the number, so the stored value never changes by accident. The mistake people make is offering every unit: pass only the units that fit the setting, `["s", "min"]` for a silence timeout or `["d"]` for retention, and always store and pass milliseconds.

When to use:
- For timeouts and delays: End call after, Retry after, Remind the approver after.
- For retention and expiry windows in days: Delete recordings after.
- For shift, break and schedule lengths in minutes or hours.
- With presets when a few values cover most cases, such as 30 seconds, 1 minute and 2 minutes.

When not to use:
- For a point in time rather than a length, such as a payment run date. Use /design/components/calendar instead.
- For opening hours across the week. Use /design/components/business-hours-picker instead.
- For a relative scale with no exact value, such as speaking speed. Use /design/components/slider-field instead.
- For a plain count that isn't time, such as maximum reminders. Use /design/components/input instead.

Rules:
- The Tabular Figures Rule: The number is right-aligned in tabular figures, and preset chips and the readout are tabular too, so values line up down a settings page.
- Say it in words: Keep the readout on unless space is tight. Deleted after 90 days is what people check; the number and unit are how they set it.

Anatomy:
- Number: A 96px Input, right-aligned in tabular figures, with a decimal keypad on phones.
- Unit: A 128px Select of the allowed units, spelled out: seconds, minutes, days.
- Readout: 13px Slate Meta text from `formatDuration`, wrapped by `readout`, in a polite live region.
- Presets: 28px chips labelled with `formatDurationShort`. The selected chip is a 6% indigo tint with a 22% inset indigo ring.

States:
- Rest: The value in its best unit, the readout beside it.
- Focus visible: The input or select takes its indigo border and 3px ring.
- Invalid: Out of range or not a number: red border and ring on the input and a message under the row. The stored value doesn't change.
- Preset selected: The chip matching the value is pressed: indigo tint and inset ring.
- Preset hover: Unselected chips move from Well Gray at 70% to full Well Gray and Graphite Ink.
- Preset out of range: Chips outside `min` and `max` dim to 50% and can't be pressed.
- Disabled: Input, select and chips are all disabled.

Behavior:
- `value` is milliseconds and `onChange` receives milliseconds. The initial unit is the largest allowed unit that shows the value as a whole number: 90,000 ms shows as 90 seconds, 120,000 ms as 2 minutes.
- If no allowed unit fits evenly, the smallest one is used with a decimal, such as 1.5 with `["min"]`.
- Valid typing commits on every keystroke. Problems are reported on blur, then update live while the error shows.
- Changing the unit converts the number: 90 seconds becomes 1.5 minutes. The stored value stays the same.
- On blur the number is tidied, so `05` becomes `5`.
- Pressing a preset sets the value, switches to that preset's best unit and clears any error. Presses scale to 0.96 when motion is allowed.
- A new `value` from outside resyncs the number and unit.

Do and don't:
- Do: Offer only the units that make sense for the setting, and presets for the common values.
- Don't: Offer milliseconds to days for a silence timeout, so people can type 0.02 minutes.
- Do: Wrap the readout in the setting's words: Hangs up after 1 minute of silence.
- Don't: Hide the readout and leave people to convert 90 seconds in their heads.

Content:
- The readout is a fragment that states the effect: Deleted after 90 days, Hangs up after 1 minute of silence.
- Errors come built in and give the fix: Enter a number, like 30., Enter at least 5 seconds., Enter 10 minutes or less.
- Pass an `aria-label` that matches the row's label, such as End call after.
- Keep presets to three or four, in ascending order.

Accessibility:
- The number and unit sit in a `role="group"` named by `aria-label`. Without an `id`, the input takes the same name; with an `id`, label it through `<label htmlFor>`.
- The readout is `aria-live="polite"` and linked to the input, so the plain-language value is read on change and on focus.
- Errors are linked to the input with `aria-describedby` and mark it `aria-invalid`.
- Presets are toggle buttons with `aria-pressed` in a group named Presets.
- Out-of-range presets are disabled rather than hidden, so the set stays stable.
- Tab: Moves from the number to the unit select, then through the presets.
- Space: Opens the unit select, or presses a preset.
- ↑ + ↓: Moves through units in the open select.
- Enter: Chooses a unit, or presses a preset.

Known gaps (follow the system, not the gap):
- The unit select is always named Unit and the chip group Presets, so a settings page with several pickers has many controls with the same name.
- `formatDuration` keeps only the two largest parts, so 1 day 2 hours 30 minutes reads 1 day 2 hours. It groups counts with `toLocaleString()` and no locale, so a count over 999 can render differently on the server and in the browser.
- `formatDurationShort` abbreviates every unit except days (30 s, 2 min, 1 h, 7 days), which mixes styles in one row of chips.
- Preset chips are hand-built buttons that copy the active filter chip's look rather than reusing Filter chip or Toggle group.
- Widths are fixed at 96px and 128px; there is no size prop for a 28px toolbar or a table cell.

API `DurationPicker`:
- `value: number`. The duration in milliseconds.
- `onChange: (value: number) => void`. Called with milliseconds when a valid value is typed or a preset is pressed.
- `units?: DurationUnit[] ("ms" | "s" | "min" | "h" | "d")` = ["s", "min", "h", "d"]. The units offered, in any order.
- `presets?: number[]`. Preset values in milliseconds, shown as chips.
- `min?: number`. Lower bound in milliseconds.
- `max?: number`. Upper bound in milliseconds.
- `readout?: ((human: string, ms: number) => ReactNode) | false` = (human) => human. Wraps the plain-language value. `false` hides it.
- `id?: string`. The number input's id.
- `aria-label?: string` = "Duration". Names the group, and the input when there's no `id`.
- `aria-describedby?: string`. Extra ids for the input's description.
- `disabled?: boolean`. Disables every part.
- `className?: string`. On the root.

API `formatDuration`:
- `ms: number`. Milliseconds.

API `formatDurationShort`:
- `ms: number`. Milliseconds.

API `DurationUnit`:

### Calendar

- Level: Molecule
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/calendar`
- Exports: `Calendar`, `CalendarDayButton`
- Docs: /design/components/calendar

Calendar is a month grid for picking one date, several dates or a range, built on react-day-picker 10 and styled with Canon buttons. Selected days are Quiet Indigo, today and the days inside a range are Well Gray, and days that can't be chosen are dimmed. Oration uses it to mark holidays on a business-hours schedule, and it is the grid to put in a Popover when a form needs a date. The mistake people make is disabling days without saying why: when weekends, past dates or bank holidays can't be picked, say so beside the calendar.

When to use:
- To pick a payment date or a callback date, inside a Popover opened from a button.
- To pick a period, such as the statement range for a remittance report, with `mode="range"`.
- To mark several dates, such as holidays on a schedule, with `mode="multiple"`.
- When some days are not allowed, such as weekends and bank holidays for ACH.

When not to use:
- For a length of time, such as a retention window. Use /design/components/duration-picker instead.
- For recurring weekly hours. Use /design/components/business-hours-picker instead.
- For a date people know and type, such as an invoice date copied from a PDF. A text field with a format hint is faster. Use /design/components/input instead.
- For a time zone next to a date. Use /design/components/timezone-select instead.

Rules:
- The Quiet Indigo Rule: Indigo marks the selected day and the ends of a range, because they are selection. Today, range middles and hover are Well Gray; nothing else in the grid is colored.
- Disabled days explain themselves: When days can't be chosen, a line beside or under the calendar says why: ACH runs on business days. Oct 12 is a bank holiday.

Anatomy:
- Caption: The month and year at 14px weight 500, centered, or month and year dropdowns with `captionLayout="dropdown"`.
- Navigation: Previous and next month buttons: 28px ghost buttons with 16px chevrons.
- Weekdays: Two-letter day names in Slate Meta.
- Day: A 28px square ghost button with 8px corners. Days from the neighboring months show in Slate Meta.
- Today: A Well Gray fill.
- Selected day: A Quiet Indigo fill with Indigo Paper text.

States:
- Rest: Graphite Ink numbers on the White Plane.
- Hover: The ghost button's Well Gray fill.
- Focus visible: An indigo border and a 3px ring at 50% on the focused day.
- Today: Well Gray fill.
- Selected: Quiet Indigo fill, Indigo Paper text.
- Range: Start and end are indigo with rounded outer corners; the days between are Well Gray with square corners, joined into one band.
- Outside: Days from the previous and next month in Slate Meta. Hide them with `showOutsideDays={false}`.
- Disabled: Slate Meta at 50% opacity. It can't be selected, and arrow keys skip it.

Behavior:
- `mode` is `single`, `multiple` or `range`. Each takes `selected` and `onSelect`; `required` stops people from clearing the selection.
- `disabled` takes matchers: a date, an array of dates, `{ before: date }`, `{ after: date }`, `{ dayOfWeek: [0, 6] }`, `{ from, to }` or a function.
- In range mode the first click sets the start and the next sets the end. `min` and `max` bound the number of days, and `excludeDisabled` restarts the range if it would cross a disabled day.
- `today` sets which day is marked as today, and `defaultMonth` which month opens. Pass both from your data rather than the device clock when the page is about a fixed date.
- `numberOfMonths={2}` shows two months side by side from 768px and stacked below.
- `captionLayout="dropdown"` adds month and year selects; bound them with `startMonth` and `endMonth`.
- Inside a Popover or a card the background becomes transparent, so it takes the surface's color.
- `weekStartsOn`, `locale` and `timeZone` pass through to react-day-picker, along with every other DayPicker prop. A partial locale such as `{ code: "en-US" }` is merged over the default English one.

Do and don't:
- Do: Open it from a button that shows the chosen date in words, and close it once a date is picked.
- Don't: Leave a full calendar open inline in a form for a single date.
- Do: Disable the days that can't be chosen and say why under the calendar.
- Don't: Let people pick a Saturday and reject it after they submit.

Content:
- Show the chosen date in full on its trigger: Friday, October 2, 2026, or Oct 2, 2026 where space is tight.
- Write ranges with an en dash and no repeated month: Sep 1 – 30, 2026.
- The trigger's empty state says what to pick: Pick a date, Pick a period.
- Explain disabled days in one sentence, naming the rule: Payments go out on business days.

Accessibility:
- The month is a grid of buttons; each day's name includes the full date, and selected days announce as selected.
- The grid has one tab stop: Tab lands on the selected day, or today, and arrow keys move from there with a visible ring.
- In a Popover, focus returns to the trigger on close. Name the trigger with its purpose and the current value: Payment date, Friday, October 2.
- Explain disabled days in text; dimming alone is a color-only cue.
- Day cells are 28px, above the 24px minimum. For touch-first screens, raise `--cell-size` through `className`.
- ← + →: Previous or next day.
- ↑ + ↓: Same day in the previous or next week.
- Page Up + Page Down: Previous or next month.
- Shift + Page Up: Previous year; with Page Down, next year.
- Home + End: Start or end of the week.
- Enter: Selects the focused day. Space does the same.

Known gaps (follow the system, not the gap):
- Without a `locale`, CalendarDayButton writes `data-day` with the runtime's default date format, which differs between the server and the browser (`30/8/2026` against `30/08/2026` here), so every server-rendered Calendar logs a hydration mismatch, including the holidays section in business hours. Pass `locale={{ code: "en-US" }}`, as every example on this page does, until it is fixed.
- One product screen uses it, to mark holidays. Campaign scheduling uses native `<input type="date">` (`apps/web/src/components/ai/campaigns/steps/schedule-step.tsx`), and there is no Canon date picker; compose Popover and Calendar as in the example above.
- Weekday headers and week numbers are 12.8px (`text-[0.8rem]`), off the 12, 13 and 14px ramp.
- Today and the middle of a range share the Well Gray fill, so today can't be told apart inside a range.
- Day cells are 28px, under the 32px touch target the suite uses on touch surfaces.

API `Calendar` (extends react-day-picker `DayPicker`):
- `mode?: "single" | "multiple" | "range"`. What can be selected. Omit for a display-only calendar.
- `selected?: Date | Date[] | DateRange | undefined`. The selection, typed by `mode`.
- `onSelect?: (selected, triggerDate, modifiers, event) => void`. Called with the next selection.
- `required?: boolean`. Prevents clearing the selection.
- `disabled?: Matcher | Matcher[]`. Days that can't be selected.
- `defaultMonth?: Date`. The month shown first.
- `month?: Date`. The month shown, controlled with `onMonthChange`.
- `today?: Date`. The day marked as today.
- `numberOfMonths?: number` = 1. Months shown side by side.
- `captionLayout?: "label" | "dropdown" | "dropdown-months" | "dropdown-years"` = "label". Month and year as text or as selects.
- `startMonth?: Date`. Earliest month people can navigate to.
- `endMonth?: Date`. Latest month people can navigate to.
- `showOutsideDays?: boolean` = true. Show days from the neighboring months.
- `min?: number`. In range and multiple mode, the fewest days.
- `max?: number`. In range and multiple mode, the most days.
- `excludeDisabled?: boolean`. In range mode, restart the range rather than include a disabled day.
- `locale?: Partial<DayPickerLocale>`. Month and day names, and the format of each day's `data-day`. Pass at least `{ code }` on server-rendered pages.
- `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6`. First day of the week.
- `showWeekNumber?: boolean`. Adds a week number column.
- `buttonVariant?: Button variant` = "ghost". The variant of the previous and next buttons.
- `classNames?: Partial<ClassNames>`. Per-part classes, merged over Canon's.

API `CalendarDayButton` (extends react-day-picker `DayButton` props):
- `locale?: Partial<Locale>`. Used to format the `data-day` attribute.

### Dropzone

- Level: Molecule
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/dropzone`
- Exports: `Dropzone`
- Docs: /design/components/dropzone

Dropzone is the dashed target for uploading files: drag files onto it, or click it (or press Space while it has focus) to browse. Oration uses it for CSV imports, OpenAPI specs, knowledge base documents and deal files. It hands you `File[]` and nothing more: no file list, no progress, no size limit. The mistake people make is trusting `accept`. It only filters the browse dialog; dropped files arrive unfiltered, so check type and size in `onFiles` and say exactly what went wrong.

When to use:
- For importing a file that starts a flow: a remittance CSV, a supplier list, an OpenAPI spec.
- For attaching documents to a record, such as W-9s or signed order forms on a supplier.
- For adding sources to a knowledge base, several files at a time by drag and drop.
- In a dialog or an empty state, where the upload is the main thing to do.

When not to use:
- For showing files already attached, with their size and a remove action. Use /design/components/attachment instead.
- For an attach button beside a message or a note. Use /design/components/prompt-bar instead.
- For upload progress once files are on their way. Use /design/components/progress instead.
- For an empty list whose first action is an upload. Put the dropzone inside the empty state, not instead of it. Use /design/components/empty instead.

Rules:
- Say what fits before it fails: The description names the types, the size limit and anything about the contents: CSV up to 50,000 rows. The first row should be column names.
- Errors name the file: A rejected file is named in the error with the fix: remittance.xlsx isn't a CSV. Save it as .csv from your spreadsheet app and try again.

Anatomy:
- Zone: A `<label>` with a 1px dashed Firm Hairline border, 12px corners and a Row Mist fill, 40px of vertical padding.
- Icon tile: A 36px White Plane tile with the hairline lift and a 16px upload icon in Slate Meta.
- Title: 14px weight 500: Drop a file here, or browse by default.
- Description: Optional 13px Slate Meta text, up to 20rem wide.
- File input: A visually hidden `<input type="file">` inside the label; it takes focus and opens the browser.

States:
- Rest: Dashed Firm Hairline border on Row Mist.
- Hover: Well Gray at 60%, over 150ms.
- Focus visible: When the hidden input has keyboard focus, the zone takes a 3px Focus Indigo ring at 40%.
- Drag over: While files are over it, `data-over` turns the border Quiet Indigo and the fill a 5% indigo tint.
- Error: Not drawn by the component. Show a Signal Red message under the zone, naming the file.
- File picked: Not drawn by the component. Replace the title with the file name, or show the file in a row below.

Behavior:
- Dropping calls `onFiles` with every dropped file. Browsing calls it with the one file picked; the input has no `multiple`.
- `accept` is passed to the file input, so it filters the browse dialog only.
- The zone is a `<label>` for the hidden input, so a click anywhere on it opens the browser.
- Drag over sets `data-over`, which you can target from `className`; leaving or dropping clears it.
- The input keeps its value after a pick, so choosing the same file again doesn't call `onFiles`.
- Every file is handed over as-is. Read, parse and upload them yourself, and show progress outside the zone.

Do and don't:
- Do: Check type and size in `onFiles`, and put an error under the zone that names the file and the fix.
- Don't: Rely on `accept` and let a dropped spreadsheet fail later, deep in the import, with no message.
- Do: Once a file is picked, show its name, size and a way to remove it before starting the import.
- Don't: Start importing the moment a file lands, with no chance to check it was the right one.

Content:
- Title: the action with the type, ending in or browse: Drop a CSV here, or browse.
- Description: types, limits and what the contents should be, in one or two short sentences.
- After a pick, the title can become the file name, as the new tool dialog does with its spec.
- Errors: {file} isn't a CSV. or {file} is 62 MB. Upload files up to 50 MB.

Accessibility:
- The hidden file input is the control. It is named by the zone's text, so the title and description are read together.
- Keyboard users Tab to it and press Space or Enter to browse; dragging has no keyboard equivalent, which is why browse is always offered.
- Put errors in a Field error or a `role="alert"` region right after the zone; the component has no `aria-describedby` to link them.
- The upload icon is decorative; lucide marks it hidden from assistive tech.
- Announce what happened after a pick: remittance-2026-09.csv added, 1,284 rows.
- Tab: Focuses the zone's file input and shows the ring.
- Space: Opens the file browser. Enter does the same in most browsers.

Known gaps (follow the system, not the gap):
- The file input has no `multiple`, so browsing picks one file even where drops accept many. The knowledge base upload dialog expects several.
- `accept` doesn't filter dropped files; each call site checks the type itself, and the import section is the only one that shows an error.
- The input isn't reset after a pick, so choosing the same file twice in a row does nothing.
- No `disabled`, `id`, `name`, `aria-describedby` or invalid state; errors can't be linked to the input.
- Focus draws only the ring, without the indigo border other fields add, and drag over uses an indigo border and tint, which DESIGN.md doesn't list among indigo's uses.
- `dragleave` fires when the pointer crosses the icon and text inside the zone, so the drag-over state can flicker.

API `Dropzone`:
- `onFiles: (files: File[]) => void`. Called with the dropped files, or the one browsed file.
- `accept?: string`. File types for the browse dialog, such as `.csv,text/csv`. Doesn't filter drops.
- `title?: string` = "Drop a file here, or browse". The main line.
- `description?: string`. Types, limits and contents.
- `className?: string`. On the zone. `data-over:` targets the drag state.

### Select

- Level: Molecule
- Category: Selection
- Status: Stable
- Import: `@oration/canon/components/select`
- Exports: `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`, `SelectSeparator`
- Docs: /design/components/select

Select is the composable picker for one value, or a few, from a short known list: a trigger that shows the current value and a popup list built on Base UI Select. It is the base that Option select, Select field and most settings pickers wrap, so reach for it directly only when rows need icons, tags, groups or a formatted trigger. The common mistake is using it for lists people need to search, such as suppliers or teammates; past about 15 options it becomes a Combobox.

When to use:
- To choose one value from a short, known list: payment terms, currency, run day, remittance format.
- When rows need more than text: an icon per payment method, a tag per tier, or a group label per account type.
- When the trigger should show a formatted value, such as the chosen tag or Priya Raman and 2 more.
- For a few values at once from a short list with `multiple`, when chips in a field would be too heavy.
- In toolbars at `size="sm"` for view settings such as status and sort.

When not to use:
- For a flat list of plain labels in an inspector or toolbar. The one-line wrapper does it in one element. Use /design/components/option-select instead.
- For a settings row, config page or sheet form field with a typed value. Use /design/components/select-field instead.
- For people, suppliers, invoices or any list long enough to search. Use /design/components/combobox instead.
- For two to five modes of a view that should all stay visible. Use /design/components/segmented-control instead.
- For a list of actions such as Export or Delete. Actions belong in a menu. Use /design/components/dropdown-menu instead.
- For a time zone. Use /design/components/timezone-select instead.

Rules:
- The Option Hue Rule: Tags inside rows and in the trigger are fine when the values are select options such as tier or stage. The ten hues never color-code sections, statuses or actions.
- Every field has a label: A select always has a visible label linked by `id`, or an `aria-label` in a toolbar where the value explains itself. The placeholder is never the label.

Anatomy:
- Trigger: A 32px native button (28px at `sm`) with 10px corners, a 1px Field Stroke, 10px left and 8px right padding, and 14px text.
- Value: `SelectValue` shows the chosen item's label when the root has `items`, the placeholder in Slate Meta when empty, or whatever its children function returns.
- Chevron: A 16px chevron in Slate Meta, drawn by the trigger.
- Popup: Popover White with 10px corners, the overlay shadow and a 1px ink ring at 10%. It matches the trigger width, never narrower than 9rem, and scrolls within the available height.
- Group label: `SelectLabel` inside a `SelectGroup`: 12px Slate Meta. The group adds the 4px inset around its rows.
- Item: An 8px-corner row, 14px text, with icons at 16px. It fills Menu Hover when highlighted.
- Check: The item indicator, a 16px check 8px from the right edge, shown on the selected item only.
- Separator: `SelectSeparator`, a Hairline that runs edge to edge between groups.

States:
- Rest: Transparent fill and a Field Stroke border; 30% input fill in dark.
- Hover: Dark theme only: the fill deepens to 50% input. Light has no hover change.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 50%.
- Open: The popup is showing and `aria-expanded` is true. The trigger itself does not change.
- Placeholder: With no value, `data-placeholder` sets the value text to Slate Meta.
- Highlighted item: The item under the pointer or keyboard highlight fills Menu Hover (`--accent`).
- Selected item: Shows the check at the right. The row is not tinted.
- Disabled: `disabled` on the root dims the trigger to 50% with a not-allowed cursor. Disabled items dim to 50% and are skipped by the keyboard.
- Invalid: `aria-invalid` on the trigger draws a red border and a 3px red ring at 20%.
- Read-only: `readOnly` on the root opens the list but blocks a new choice. It is not styled; say so in the description.

Behavior:
- Clicking the trigger, or Enter, Space, Down or Up on it, opens the popup with the selected item highlighted. Choosing an item closes it and focus returns to the trigger.
- By default (`alignItemWithTrigger`) the popup overlaps the trigger so the selected row sits exactly over the value. It falls back to opening below when space is short or when it was opened by touch, and `side` and `align` are ignored while it is aligned.
- Set `alignItemWithTrigger={false}` to open below the trigger at a 4px offset, centered unless you pass `align="start"`. Only this mode animates: 100ms fade and zoom from 95%.
- Typing on a closed trigger picks the next matching item, like a native select. Typing in an open list moves the highlight only. There is no filtering; that is Combobox.
- The select is modal while open: page scroll locks and outside clicks only close it. Scroll arrows appear at the top and bottom when the list overflows.
- Controlled with `value` and `onValueChange`, or uncontrolled with `defaultValue`. Pass `items` so `SelectValue` shows labels instead of raw values; `onValueChange` can report `null`, so guard it.
- With `multiple`, `value` is an array and the popup stays open while people toggle rows. Format the trigger with a children function on `SelectValue`.
- `name` posts a hidden input with forms; `required` and `readOnly` work as on native fields.

Do and don't:
- Do: Give the select a visible label linked with `id`, and use the placeholder for an empty value such as Choose terms.
- Don't: Put the label in the placeholder. It disappears the moment a value is chosen.
- Do: Use a dropdown menu button for actions such as Export CSV or Add to payment run.
- Don't: Use a select as an action menu. A select stores a value, and screen readers announce it as one.

Content:
- Label the field with a noun for the value: Payment terms, GL account, Supplier tier. Not Select terms.
- Option labels are sentence case, short and parallel: Net 15, Net 30, Due on receipt.
- Placeholders name the action on an empty field: Choose terms, Nobody. Never Select… or Please select.
- Put the most common or recommended option first, or keep a natural order (days, amounts) rather than alphabetical.
- Group labels are plain nouns, not questions: Operating expenses.
- Format several values as Priya Raman and 2 more, not a comma list that truncates.

Accessibility:
- The trigger is a native button with `role="combobox"`, `aria-haspopup="listbox"` and `aria-expanded`; the popup is a `listbox` of `option` rows. Base UI moves focus into the list and back to the trigger.
- Name it with a `<Label htmlFor>` pointing at the trigger `id`, or `aria-label` on `SelectTrigger`. The Canon wrapper does not export Base UI's `Select.Label`.
- Icons inside rows are decorative: mark them `aria-hidden`. The row's text is its name.
- Tags in rows are read as their text, so the label must stand alone without its hue.
- Rows are 28px tall, above the 24px minimum. On touch the popup opens below instead of overlapping.
- The popup's zoom is a short CSS animation; it only runs when `alignItemWithTrigger` is off.
- Enter: On the trigger, opens the list. On a row, selects it and closes the list.
- Space: Same as Enter.
- ↓ + ↑: On the trigger, opens the list. In the list, moves the highlight, skipping disabled rows.
- Home + End: Highlights the first or last row.
- A–Z: Closed: selects the next matching row. Open: highlights it.
- Esc: Closes the list without changing the value.
- Tab: Closes the list and moves focus on.

Known gaps (follow the system, not the gap):
- Rows placed straight in `SelectContent` sit flush against the popup edge: only `SelectGroup` adds the 4px inset menus use. Always wrap rows in a group. Option select and Select field don't, so their rows touch the edge.
- The trigger has no hover change in light and no open state, while Timezone select draws an indigo border when open. The select family doesn't agree on these two states.
- The popup opens in 100ms from a 95% scale, and not at all in the default aligned mode. DESIGN.md asks popovers for 160ms in from 0.97 and 110ms out.
- Base UI's `Select.Label` is not exported, so naming the trigger relies on a separate `Label` or `aria-label`.

API `Select`:
- `value?: Value | Value[] | null`. The selected value. Use with `onValueChange`.
- `defaultValue?: Value | Value[] | null`. The initial value when uncontrolled.
- `onValueChange?: (value: Value | Value[] | null, details) => void`. Called when the value changes. Can report `null`.
- `items?: { value; label: ReactNode }[] | Record<string, ReactNode> | Group[]`. The options, so `SelectValue` can render the label of the selected value.
- `multiple?: boolean` = false. Lets people select several rows; `value` becomes an array.
- `open?: boolean`. Controls the popup. Pair with `onOpenChange`.
- `onOpenChange?: (open: boolean, details) => void`. Called when the popup opens or closes.
- `modal?: boolean` = true. Locks page scroll and blocks outside pointer events while open.
- `disabled?: boolean` = false. Dims the trigger and ignores interaction.
- `readOnly?: boolean` = false. Opens the list but prevents a new choice.
- `required?: boolean` = false. Requires a value before a form submits.
- `name?: string`. Posts the value with a form through a hidden input.
- `itemToStringLabel?: (value: Value) => string`. Label for object values when they aren't `{ value, label }`.
- `isItemEqualToValue?: (item: Value, value: Value) => boolean`. Custom equality for object values. Defaults to `Object.is`.

API `SelectTrigger` (extends Base UI `Select.Trigger` (native `<button>`)):
- `size?: "sm" | "default"` = "default". 32px, or 28px with 8px corners for toolbars.
- `id?: string`. Point a `<Label htmlFor>` at it to name the select.
- `aria-invalid?: boolean`. Draws the red border and ring.
- `className?: string`. Merged after the base classes. Set the width here: the trigger is `w-fit` by default.

API `SelectValue` (extends Base UI `Select.Value` (`<span>`)):
- `placeholder?: ReactNode`. Shown in Slate Meta when there is no value.
- `children?: ReactNode | (value) => ReactNode`. Replaces the default label, for icons, tags or a summary of several values.

API `SelectContent` (extends Base UI `Select.Popup`):
- `alignItemWithTrigger?: boolean` = true. Overlaps the trigger so the selected row sits over the value. `false` opens below.
- `side?: "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end"` = "bottom". Where to open when not aligned with the trigger.
- `sideOffset?: number` = 4. Gap from the trigger in pixels.
- `align?: "start" | "center" | "end"` = "center". Alignment against the trigger when not aligned with it.
- `alignOffset?: number` = 0. Shift along the alignment axis.

API `SelectItem` (extends Base UI `Select.Item`):
- `value: Value`. The value this row selects.
- `disabled?: boolean` = false. Dims the row and skips it in keyboard navigation.
- `label?: string`. Text used for typeahead when the children aren't plain text.

API `SelectGroup` (extends Base UI `Select.Group`):

API `SelectLabel` (extends Base UI `Select.GroupLabel`):

API `SelectSeparator` (extends Base UI `Select.Separator`):

API `SelectScrollUpButton` (extends Base UI `Select.ScrollUpArrow`):

### Option select

- Level: Molecule
- Category: Selection
- Status: Stable
- Import: `@oration/canon/components/option-select`
- Exports: `OptionSelect`
- Docs: /design/components/option-select

Option select is Select in one element: pass a flat list of strings or `{ value, label }` pairs and it renders a full-width trigger and the list. It is the dense picker for workflow inspectors, run bars and sequence settings, where one line of text per option is all a row needs. The part people get wrong is the name: `label` becomes the trigger's `aria-label`, so it must repeat the visible label word for word.

When to use:
- In a workflow inspector or side panel: Notify on failure, Retry failed steps.
- In a run bar or toolbar at `size="sm"`: Sample record.
- For times, delays and other short lists where the label is the value: 9:00 AM, 1 hour.
- When the stored value is an id but people read a name, with `{ value, label }` pairs.

When not to use:
- In a settings row, agent config page or sheet form. Those surfaces use the presets with a typed value. Use /design/components/select-field instead.
- When rows need icons, tags, groups or a formatted trigger. Use /design/components/select instead.
- For people, suppliers or any list long enough to search. Use /design/components/combobox instead.
- For two to four modes that should stay visible side by side. Use /design/components/segmented-control instead.
- For a time zone. Use /design/components/timezone-select instead.

Rules:
- The Thirteen-Fourteen Rule: Option select is dense UI: its trigger and rows are meant to read at 13px beside the 13px labels of inspectors and toolbars. Today they render at 14px; see the known gaps.
- Label in name: The visible label and the `label` prop say the same words, so speech users can say what they see and screen readers announce what is on screen.

Anatomy:
- Trigger: A Select trigger at full width with `min-w-0`, 32px or 28px tall, 10px corners and a Field Stroke. `className` lands here.
- Value: The selected option's label, one line, truncated when the trigger is narrow.
- Popup: The Select popup, aligned over the trigger so the selected row sits on the value. `contentClassName` lands here.
- Row: One per option, in the order given. Filled with Menu Hover when highlighted.
- Check: Marks the selected row.

States:
- Rest: Transparent over the surface. Inspectors on the rail pass `bg-card` so the field reads as white.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 50%.
- Open: The popup overlaps the trigger with the selected row aligned to the value.
- Empty: `value=""` with a `placeholder` shows the placeholder in Slate Meta.
- Highlighted row: Menu Hover fill under the pointer or keyboard highlight.
- Disabled: `disabled` dims the trigger to 50%. A `disabled` option dims its row and is skipped by the keyboard.

Behavior:
- Everything behaves as Select: click or Enter, Space, Down or Up to open, typeahead to jump, Escape to close, focus back on the trigger.
- Strings are turned into `{ value: s, label: s }`, so the value you store is the text you show. Use pairs when the value is an id.
- Controlled only: `value` and `onValueChange` are required. The callback only fires with a string, never `null`.
- The trigger is `w-full`; size it with its container or `className`, as the product does with `w-32` and `w-48`.
- It posts nothing with a form: there is no `name`, `required` or `readOnly`. Use Select when the value must submit natively.

Do and don't:
- Do: Repeat the visible label in `label`: Notify on failure above, `label="Notify on failure"` on the component.
- Don't: Give `label` different words, such as Alert recipients dropdown. Screen readers announce that instead of the label people see.

Content:
- Options are short and parallel, sentence case, one line: Workflow owner, Owner and #ap-alerts, Nobody.
- Put the default or recommended option first.
- Name the outcome, not the mechanism: 3 times, 5 minutes apart reads better than Retry policy B.
- Placeholders name the action: Choose a queue.
- Explain a disabled option in its label or beside the field: Wen Zhou, on leave.

Accessibility:
- `label` is required and becomes the trigger's `aria-label`. It overrides any `<Label htmlFor>` for the accessible name, so the two must match.
- The trigger is a Base UI combobox button with a listbox popup; keyboard and focus handling come from Select.
- There is no way to pass `aria-invalid` or `aria-describedby`. Write errors as text beside the field, and announce them with `role="alert"` when they appear.
- Rows are at least 28px tall.
- Enter: Opens the list, or selects the highlighted row.
- ↓ + ↑: Opens the list, then moves the highlight.
- A–Z: Selects (closed) or highlights (open) the next match.
- Esc: Closes without changing the value.

Known gaps (follow the system, not the gap):
- The 13px size doesn't apply. The component adds `text-13` to the trigger and rows through the `cn` package, which keeps the base `text-sm` beside it, and `text-sm` wins in the stylesheet. Trigger and rows render at 14px.
- Rows are rendered straight into the popup without a `SelectGroup`, so they sit flush against its edge with no 4px inset.
- There is no `aria-invalid` or `aria-describedby` pass-through. The sequence sending window marks an invalid end time with `className="border-destructive"`, which draws no ring and isn't announced.
- `label` always sets `aria-label`, even when a visible label is linked by `id`, so the two can drift apart.
- No `name`, `required` or `readOnly`, so the value can't post with a native form.

API `OptionSelect`:
- `value: string`. The selected value. `""` shows the placeholder.
- `onValueChange: (value: string) => void`. Called with the chosen value.
- `options: readonly (string | SelectOption)[]`. Strings, or `{ value: string; label: ReactNode; disabled?: boolean }` pairs.
- `label: string`. The accessible name, set as `aria-label` on the trigger. Match the visible label.
- `id?: string`. The trigger's id, for a `<Label htmlFor>`.
- `size?: "sm" | "default"` = "default". 32px, or 28px for run bars and toolbars.
- `placeholder?: string`. Shown when `value` is empty.
- `disabled?: boolean`. Dims the trigger and blocks interaction.
- `className?: string`. Classes for the trigger, such as a width or `bg-card`.
- `contentClassName?: string`. Classes for the popup.

### Select field

- Level: Molecule
- Category: Selection
- Status: Beta
- Import: `@oration/canon/components/select-field`
- Exports: `SelectField`, `SettingsSelect`, `ConfigSelect`, `FieldSelect`, `ChoiceSelect`
- Docs: /design/components/select-field

Select field is a typed, controlled Select for plain-text options, with four presets that size it for the surface it sits on: `SettingsSelect` for settings rows, `ConfigSelect` for agent config pages, `FieldSelect` for sheet and dialog forms, and `ChoiceSelect` for filter bars and rule builders. It is the most used select in the suite: settings pages alone use it in nearly fifty files. The mistake to avoid is picking a preset by name alone: `FieldSelect` and `ChoiceSelect` default to the 28px size, so a stacked form field needs `size="default"`.

When to use:
- In a settings row, with `SettingsSelect` on the trailing side: Default payment terms, Remittance advice.
- On an agent config page, with `ConfigSelect`: Default language.
- In a sheet or dialog form under a stacked label, with `FieldSelect` at `size="default"`: Supplier contact, Queue.
- In a filter bar, table header or rule builder, with `ChoiceSelect` and an explicit width: Tier, Sort by.
- Whenever the value is a string union and you want `onValueChange` typed to it.

When not to use:
- In a workflow inspector, run bar or sequence panel, where the one-line picker is already the norm. Use /design/components/option-select instead.
- When rows need icons, tags or groups, or several values. Use /design/components/select instead.
- For people, suppliers, records or any list long enough to search. Use /design/components/combobox instead.
- For a setting that is on or off. Use /design/components/switch instead.
- For two to four modes where each needs a sentence of explanation. Use /design/components/choice-card instead.

Rules:
- Every field has a label: In a settings row, pass the row's `htmlFor` as the select's `id` so the row label names it. Use `label` only where there is no visible label, such as a table cell or filter bar.
- The Thirteen-Fourteen Rule: Settings and form fields read at 14px. In filter bars and table cells, pass `text-[13px]` through `className` so the value matches the 13px around it.

Anatomy:
- Trigger: A Select trigger whose width and height come from the preset: `SettingsSelect` and `ConfigSelect` are full width and 256px from 640px up; `FieldSelect` is full width; `ChoiceSelect` shrinks to fit.
- Value: The selected option's label, or the placeholder in Slate Meta when `value` is `""`.
- Popup: The Select popup, aligned over the trigger so the selected row sits on the value.
- Row: One per option, text only, filled with Menu Hover when highlighted.
- Check: Marks the selected row.

States:
- Rest: Transparent with a Field Stroke; 30% input fill in dark.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 50%.
- Open: The popup overlaps the trigger with the selected row aligned.
- Empty: `value=""` is passed to Select as `null`, so the placeholder shows in Slate Meta.
- Highlighted row: Menu Hover fill under the pointer or keyboard highlight.
- Disabled: `disabled` dims the trigger to 50% with a not-allowed cursor, as on the config page when the feature it belongs to is off.

Behavior:
- Keyboard, focus and positioning are Select's: click or Enter, Space, Down or Up opens; typeahead jumps; Escape closes and focus returns to the trigger.
- Controlled only. `value` is `V | ""`, where `""` means nothing chosen yet, and `onValueChange` is typed to `V` and never reports empty.
- The value type is inferred from `options`, or set it: `SettingsSelect<PaymentTerms>`.
- `className` is required on the base `SelectField` and optional on the presets, which merge yours after their own. On the presets a responsive width such as `sm:w-40` replaces the preset's `sm:w-64`.
- `describedBy` sets `aria-describedby`. In a settings row pass `descriptionId(htmlFor)` so the row description is read with the field.
- There is no way to clear back to empty from the list once a value is chosen.

Do and don't:
- Do: Give the select the row's `htmlFor` as its `id`, so the visible Payment terms label names it.
- Don't: Leave the row label unlinked and fall back to a generic `label` such as Select. Screen readers announce Select, not Payment terms.
- Do: Pass `size="default"` to `FieldSelect` in a stacked form so it matches the 32px inputs around it.
- Don't: Leave `FieldSelect` at its 28px default beside 32px inputs. The field row looks misaligned and cramped.

Content:
- Row labels are nouns for the setting: Default payment terms, not Choose default payment terms.
- Options are sentence case and parallel: Net 15, Net 30, Due on receipt.
- In filter bars, make the all option read as a value: All tiers, All languages.
- Sort options say the order: Spend, high to low.
- Placeholders name the action: Choose a contact.
- Put what the setting changes in the row description, not in the options.

Accessibility:
- The trigger is a Base UI combobox button with a listbox popup. Name it with a linked label through `id`, or `label` (set as `aria-label`) when there is no visible label.
- `label` overrides the linked label if both are set, so when you pass both, use the same words.
- `describedBy` points at the helper text or row description.
- There is no invalid state: the presets can't pass `aria-invalid`. Put errors in text beside the field and announce them with `role="alert"`.
- The 28px presets meet the 24px target minimum; use `size="default"` on touch-first forms.
- Enter: Opens the list, or selects the highlighted row.
- ↓ + ↑: Opens the list, then moves the highlight.
- A–Z: Selects (closed) or highlights (open) the next match.
- Esc: Closes without changing the value.

Known gaps (follow the system, not the gap):
- `SettingsSelect` and `ConfigSelect` are the same component with the same classes. Two names for one preset invite them to drift.
- `FieldSelect` defaults to 28px, but six of its ten call sites pass `size="default"` to match the 32px form fields around them. The default doesn't match its main use.
- There is no `aria-invalid` pass-through and no per-option `disabled`, so the presets can't show an error state or an unavailable option.
- Rows are rendered straight into the popup without a `SelectGroup`, so they sit flush against its edge with no 4px inset.

API `SelectField`:
- `value: V | ""`. The selected value. `""` shows the placeholder.
- `onValueChange: (value: V) => void`. Called with the chosen value.
- `options: readonly SelectFieldOption<V>[]`. The rows, in order.
- `className: string`. Trigger classes. There is no default width; the presets supply one.
- `id?: string`. The trigger's id, for a linked label.
- `label?: string`. Sets `aria-label` on the trigger.
- `describedBy?: string`. Sets `aria-describedby` on the trigger.
- `size?: "sm" | "default"` = "default". 32px, or 28px with 8px corners.
- `placeholder?: string`. Shown while `value` is empty.
- `disabled?: boolean`. Dims the trigger and blocks interaction.

API `SettingsSelect`:
- `className?: string`. Merged after `w-full sm:w-64`.

API `ConfigSelect`:
- `className?: string`. Merged after `w-full sm:w-64`.

API `FieldSelect`:
- `size?: "sm" | "default"` = "sm". Pass `"default"` beside 32px inputs.
- `className?: string`. Merged after `w-full`.

API `ChoiceSelect`:
- `size?: "sm" | "default"` = "sm". 28px, or 32px in a form grid.
- `className?: string`. Merged after `min-w-0`. Set a width such as `w-40`.

### Native select

- Level: Molecule
- Category: Selection
- Status: Stable
- Import: `@oration/canon/components/native-select`
- Exports: `NativeSelect`, `NativeSelectOption`, `NativeSelectOptGroup`
- Docs: /design/components/native-select

Native select is the platform `<select>` dressed to match the other fields: a 32px box with the Field Stroke, 10px corners and a Slate Meta chevron. The list itself is drawn by the browser and the operating system, so it is the right control on phones and in plain forms that post natively, and it is what the workflow step inspectors use today. The thing people get wrong is `className`: it lands on the wrapper, not the `<select>`, so width goes there and everything else goes through a descendant selector.

When to use:
- For a short list of plain text labels where the platform picker is the better control, such as a phone-first form.
- In workflow and procedure inspectors, where each step picks a destination, variable or tool from a short list.
- When the value must post with a native `<form>` and no JavaScript state, such as a server action.
- For a list grouped by `optgroup`, such as a chart of accounts split into expenses and liabilities.

When not to use:
- When rows need icons, tags, two lines or a formatted trigger. The platform list only draws text. Use /design/components/select instead.
- For a settings row or sheet field with a typed value on desktop. Use /design/components/select-field instead.
- For suppliers, people or invoices. Native type-ahead only matches the first letters, so long lists need search. Use /design/components/combobox instead.
- For two to five modes that should all stay visible. Use /design/components/segmented-control instead.
- For a time zone. Use /design/components/timezone-select instead.

Rules:
- Every field has a label: Point a visible `Label` at the select's `id`. An empty first option such as Choose a destination is a prompt, never the label.
- Selects match inputs: 32px tall, 10px corners, a 1px Field Stroke and a transparent fill (input at 30% in dark), so a native select sits in a form column beside inputs without a seam.

Anatomy:
- Wrapper: A relative `w-fit` box that receives `className`, dims to 50% when the select is disabled and positions the chevron.
- Select: The native `<select>`, `appearance-none`, 32px (28px at `sm`), 10px corners, a 1px Field Stroke, 10px left and 32px right padding, 14px text.
- Selected option: The browser draws the chosen option's text. An empty-value first option acts as the prompt.
- Chevron: A 16px chevron in Slate Meta, 10px from the right edge, `pointer-events-none` so clicks reach the select.

States:
- Rest: Transparent fill and the Field Stroke. In dark, the input color at 30%.
- Hover: No change in light. In dark, the fill rises to the input color at 50%.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 50%.
- Open: The platform draws the list. Options use the `Canvas` and `CanvasText` system colors so they stay legible in either theme.
- Invalid: With `aria-invalid`, a red border and a 3px red ring at 20% (40% in dark).
- Disabled: The wrapper drops to 50% opacity and the select takes no pointer events.

Behavior:
- Controlled with `value` and `onChange`, reading `event.target.value`; uncontrolled with `defaultValue`. Every value is a string.
- For an empty state, make the first option `value=""` with a prompt such as Choose a destination, as the inspectors do, and map `""` back to `undefined` in the change handler.
- The open list, its scrolling, type-ahead and the phone wheel picker are the platform's. None of them can be styled.
- `className` goes to the wrapper. Pass `className="w-full"` to fill a column; reach the `<select>` itself with a descendant selector such as `[&>select]:text-[13px]`.
- The `size` prop is the Canon height (`"default"` or `"sm"`), replacing the HTML `size` attribute. `multiple` isn't supported by the fixed 32px height.

Do and don't:
- Do: Give the select a visible label and start the list with an empty prompt option.
- Don't: Use the first option as the label. Once someone picks a value, the label is gone.
- Do: Keep native selects to short lists of plain labels.
- Don't: Put 60 suppliers in a native list. Type-ahead matches only leading letters, so people scroll.

Content:
- Labels name the thing being chosen: Transfer to, Variable, GL account.
- The prompt option starts with a verb: Choose a destination, not Select… or --.
- Option labels are sentence case and parallel. Add a qualifier after a comma when two options would read the same: AP exceptions, warm transfer.
- Don't put instructions in options. Put them in a description under the field.

Accessibility:
- It is a real `<select>`, so screen readers announce it as a combo box or pop-up button with its value, and the platform handles the list.
- Link the label with `htmlFor` and `id`; link a hint or error with `aria-describedby`.
- Set `aria-invalid` when the value fails validation and write the reason beside the field.
- On touch devices the platform shows a native picker, which meets hit-size and zoom expectations without extra work.
- The chevron is `aria-hidden`.
- Tab: Moves focus to the select.
- ↑ + ↓: Changes the value in place on Windows and Linux; opens the list on macOS.
- Space: Opens the list. Alt + ↓ also opens it on Windows.
- A–Z: Jumps to the next option starting with that letter.
- Enter: Chooses the highlighted option while the list is open.
- Esc: Closes the list without changing the value.

Known gaps (follow the system, not the gap):
- `className` lands on the wrapper, unlike every other field in `packages/canon`, so `className="text-[13px]"` doesn't reach the text. Use `[&>select]:text-[13px]`.
- The select carries `placeholder:text-muted-foreground`, which has no effect on a `<select>`. An empty prompt option renders in full ink, not Slate Meta.
- The `size` prop replaces the HTML `size` attribute, and the fixed height breaks `multiple`, so there is no native list box variant.
- The registry describes it as for long lists. Long lists belong in Combobox, which can search; native type-ahead only matches leading letters.

API `NativeSelect` (extends `<select>` (except `size`)):
- `size?: "sm" | "default"` = "default". 32px, or 28px with 8px corners for dense panels.
- `value?: string`. Controlled value. Pair with `onChange`.
- `defaultValue?: string`. Initial value when uncontrolled.
- `onChange?: (event: React.ChangeEvent<HTMLSelectElement>) => void`. Read the new value from `event.target.value`.
- `disabled?: boolean` = false. Dims the wrapper to 50% and blocks interaction.
- `aria-invalid?: boolean`. Draws the red border and ring.
- `className?: string`. Applied to the wrapper. Use it for width (`"w-full"`) and descendant selectors.

API `NativeSelectOption` (extends `<option>`):
- `value: string`. The submitted value. Use `""` for the prompt option.
- `disabled?: boolean`. Shown but not choosable.

API `NativeSelectOptGroup` (extends `<optgroup>`):
- `label: string`. The group heading the platform draws.

### Combobox

- Level: Molecule
- Category: Selection
- Status: Beta
- Import: `@oration/canon/components/combobox`
- Exports: `Combobox`, `ComboboxInput`, `ComboboxContent`, `ComboboxItem`, `ComboboxChips`, `ComboboxEmpty`
- Docs: /design/components/combobox

Combobox is a text field that filters a list as you type, built on Base UI Combobox. It is the picker for lists that are long, grow with the workspace or are easier to type than to scan: people, suppliers, GL accounts, invoices. With `multiple` it holds several values as removable chips in the field. The common mistake is reaching for it on a short fixed list, where a search box is only friction; under about 15 options, use a select.

When to use:
- To pick one record from a list people search by name: an approver, a supplier, a GL account.
- For several values from a searchable list, shown as chips in the field: watchers, approvers, email domains.
- As an add control above a list, where each pick adds a row and the field clears for the next one.
- When the list is long enough that scanning it is slower than typing three letters, about 15 options or more.

When not to use:
- For a short fixed list such as payment terms or remittance format. Use /design/components/select-field instead.
- For a short list whose rows need icons, tags or groups, without search. Use /design/components/select instead.
- For a time zone. It already searches by city, zone and offset. Use /design/components/timezone-select instead.
- For free-form values people type rather than choose, such as email domains that aren't in any list. Use /design/components/tag-input instead.
- For jumping to a page or running a command. Use /design/components/command instead.

Rules:
- Every field has a label: Link a visible `Label` to the input's `id`, or give the input an `aria-label` when it sits above the list it adds to. The placeholder says what to type, never what the field is.
- Selects match inputs: The field is an Input group: 32px, 10px corners, the Field Stroke, and the same indigo focus ring as every input, so a combobox sits in a form column without a seam.

Anatomy:
- Input: `ComboboxInput`: an Input group with the text input, 32px with 10px corners. `className` sizes the group.
- Trigger: A 24px ghost icon button with the chevron that opens the list. With `showClear`, a clear button replaces it once there is a value.
- Popup: Popover White, 10px corners, the overlay shadow and a 1px ink ring at 10%. At least the field's width plus 28px, 6px below it, scrolling at 18rem.
- Group label: `ComboboxLabel`: 12px Slate Meta over a group of rows.
- Item: `ComboboxItem`: 14px text with 8px corners and room for the check. The highlighted row fills with the accent color.
- Indicator: A 16px check, 8px from the right, on the chosen rows.
- Chips: With `multiple`: `ComboboxChips` replaces the input group, wraps chips and a `ComboboxChipsInput`, and grows from 32px.
- Chip: `ComboboxChip`: 21px, 12px medium text on Well Gray with 6px corners and a remove button.

States:
- Rest: Transparent field with the Field Stroke and a Slate Meta placeholder.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 50% on the whole group, drawn when the input has focus.
- Open: The popup fades and zooms in from 95% over 100ms, sliding 8px from the field.
- Highlighted: The row under the pointer or arrow keys fills with the accent color.
- Selected: A check at the right of the row.
- Empty: `ComboboxEmpty` shows its message in 14px Slate Meta when nothing matches the text.
- Invalid: With `aria-invalid` on the input, a red border and a 3px red ring at 20% on the group or the chips box.
- Disabled: The group drops to 50% opacity on a faint input fill. A disabled item drops to 50% and can't be highlighted.

Behavior:
- Pass `items` to the root and a function as the child of `ComboboxList`; Base UI filters the items against the text and renders only the matches. For groups, pass `{ value, items }[]` and render each with `ComboboxGroup items` and `ComboboxCollection`.
- Objects work as items. Give the root `itemToStringLabel` so the input shows a name and the filter matches it; set `isItemEqualToValue` when the value and the items aren't the same objects.
- Controlled with `value` and `onValueChange`, uncontrolled with `defaultValue`. Single mode reports `null` when cleared.
- For an add control, keep `value={null}` and push the chosen item into your own list in `onValueChange`; the field clears for the next pick.
- With `multiple`, the list stays open after each pick. Anchor the popup to the chips with `useComboboxAnchor()`, passing the ref to `ComboboxChips` and `anchor` to `ComboboxContent`.
- Typing opens the list; `autoHighlight` highlights the first match so Enter picks it. Escape closes the list, and focus stays in the input.
- The popup portals to the body and flips to stay in view.

Do and don't:
- Do: Use a combobox when people know the name and typing it is faster than scanning.
- Don't: Put a search box on two options. It's a select with an extra step.
- Do: Write an empty message that says what happened and what to try next.
- Don't: Leave `ComboboxEmpty` out. When nothing matches, the popup collapses to nothing and people think it broke.

Content:
- The label names the field: Approver, Supplier, GL account.
- The placeholder says what to type: Search people, Add an approver by name. Not Select….
- The empty message names the miss and a way forward: No suppliers match. Check the spelling or add one.
- A trailing detail in a row, such as the team, is 12px Slate Meta and helps tell two similar names apart.
- In an add control, say when there's no one left: Everyone is already an approver.

Accessibility:
- The input has `role="combobox"` with `aria-expanded`, `aria-controls` and `aria-activedescendant`, so focus stays in the text while arrow keys move through the list.
- Name the input with a `Label` linked by `id`, or `aria-label` when there's no visible label.
- The chevron trigger and the chip remove buttons are out of the tab order (`tabIndex=-1`); keyboard users open with the arrow keys and remove chips with Backspace.
- Set `aria-invalid` on the input for errors and link the message with `aria-describedby`.
- Every item in a list of objects needs a unique `key` and a readable string label for the input.
- ↓: Opens the list, then moves the highlight down.
- ↑: Moves the highlight up.
- Enter: Chooses the highlighted item. In multiple mode, toggles it.
- Esc: Closes the list. Focus stays in the input.
- ←: With chips, from the start of the text, highlights the last chip; then moves between chips.
- Backspace: With chips, removes the highlighted chip, or the last chip when the text is empty.

Known gaps (follow the system, not the gap):
- The popup draws its edge with `ring-1` plus `shadow-md` rather than the single composite overlay shadow the Hairline-and-Lift Rule asks for.
- `ComboboxChip` is 21px with 6px corners, off the tag ramp (20px, 8px corners). Chips aren't tags, but the size isn't on any ramp.
- The chip remove button has no accessible name. It is out of the tab order, so keyboard users remove chips with Backspace, but screen reader users browsing the field meet an unnamed button.
- `ComboboxClear` isn't exported. Clearing is only available through `showClear` on `ComboboxInput`, so the chips field has no clear-all button.
- Three product files use it, all in team settings, so its patterns are less proven than Select's.

API `Combobox` (extends Base UI `Combobox.Root`):
- `items?: readonly Item[] | readonly { value: string; items: Item[] }[]`. The list to filter. Groups use `{ value, items }` objects.
- `value?: Value | Value[] | null`. Controlled value. An array with `multiple`.
- `defaultValue?: Value | Value[] | null`. Initial value when uncontrolled.
- `onValueChange?: (value, eventDetails) => void`. Called with the new value, or `null` when cleared.
- `multiple?: boolean` = false. Allows several values, usually rendered as chips.
- `itemToStringLabel?: (item: Value) => string`. The text for an object item, shown in the input and used by the filter.
- `isItemEqualToValue?: (item: Value, value: Value) => boolean`. Compares items to the value when they aren't the same objects.
- `filter?: ((item, query) => boolean) | null`. Replaces the default filter. `null` turns it off, for server search.
- `inputValue / onInputValueChange?: string / (value: string) => void`. Control the text, for example to search a server.
- `open / onOpenChange?: boolean / (open: boolean) => void`. Control the popup.
- `autoHighlight?: boolean` = false. Highlights the first match as people type.
- `disabled?: boolean` = false. Disables the whole control.

API `ComboboxInput` (extends Base UI `Combobox.Input`):
- `showTrigger?: boolean` = true. Shows the chevron button that opens the list.
- `showClear?: boolean` = false. Shows a clear button in place of the chevron once there is a value.
- `disabled?: boolean` = false. Disables the input and its buttons.
- `placeholder?: string`. What to type, such as Search people.
- `children?: ReactNode`. Extra addons rendered inside the group.

API `ComboboxContent` (extends Base UI `Combobox.Popup`):
- `side?: "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end"` = "bottom". Preferred side. It flips to stay in view.
- `sideOffset?: number` = 6. Gap from the field in px.
- `align?: "start" | "center" | "end"` = "start". Alignment along the field.
- `alignOffset?: number` = 0. Offset along the alignment axis.
- `anchor?: RefObject<HTMLDivElement | null>`. The element to position against. Pass the `useComboboxAnchor()` ref used on `ComboboxChips`.

API `ComboboxList` (extends Base UI `Combobox.List`):

API `ComboboxItem` (extends Base UI `Combobox.Item`):
- `value: Value`. The item this row picks.
- `disabled?: boolean` = false. Shown at 50% and skipped by the highlight.

API `ComboboxGroup` (extends Base UI `Combobox.Group`):
- `items?: readonly Item[]`. The group's items after filtering.

API `ComboboxLabel` (extends Base UI `Combobox.GroupLabel`):

API `ComboboxCollection` (extends Base UI `Combobox.Collection`):

API `ComboboxEmpty` (extends Base UI `Combobox.Empty`):

API `ComboboxSeparator` (extends Base UI `Combobox.Separator`):

API `ComboboxChips` (extends Base UI `Combobox.Chips`):
- `ref?: RefObject<HTMLDivElement | null>`. Pass the `useComboboxAnchor()` ref.

API `ComboboxChip` (extends Base UI `Combobox.Chip`):
- `showRemove?: boolean` = true. Shows the remove button.

API `ComboboxChipsInput` (extends Base UI `Combobox.Input`):

API `ComboboxValue` (extends Base UI `Combobox.Value`):

API `ComboboxTrigger` (extends Base UI `Combobox.Trigger`):

API `useComboboxAnchor`:

### Timezone select

- Level: Molecule
- Category: Selection
- Status: Beta
- Import: `@oration/canon/components/timezone-select`
- Exports: `TimezoneSelect`, `listTimeZones`, `formatUtcOffset`, `formatLocalTime`
- Docs: /design/components/timezone-select

Timezone select picks an IANA time zone from every zone the browser knows, grouped by region, with each zone's current UTC offset and local time. Search matches city, zone ID, region or offset, so tokyo, Asia/ and +05:30 all find something. Business hours picker uses it, and so should anything that stores a zone. The common mistake is a hand-written list of four abbreviations: people outside it can't find their city, and labels like CST go wrong the day daylight saving changes.

When to use:
- Whenever a setting stores a time zone: the workspace zone, a supplier's calling hours, a payment run's schedule.
- Beside business hours or a scheduled time, so people see the offset and the local time they're committing to.
- In a settings row, where its 288px trigger matches the other controls in the column.

When not to use:
- To show a zone that can't be changed. Render the city and offset as text with `timeZoneCity` and `formatUtcOffset`.
- For a short list of regions or offices that aren't zones. Use /design/components/select-field instead.
- For a full weekly schedule with a zone. The composed picker already includes it. Use /design/components/business-hours-picker instead.
- For people, suppliers or other long searchable lists. Use /design/components/combobox instead.

Rules:
- The Tabular Figures Rule: Offsets and local times are set in tabular figures, and the offset uses a true minus sign, so the column of offsets aligns down the list.
- The Machine Mono Rule: The IANA ID under each city, such as `America/Chicago`, is a machine string and is set in Geist Mono. The city and the offset stay in Geist Sans.

Anatomy:
- City: The chosen zone's city in 14px, truncated. `America/Argentina/Buenos_Aires` reads Buenos Aires, Argentina.
- Offset and chevron: The current UTC offset in Slate Meta tabular figures, then a 16px chevron. The trigger is 32px with 10px corners, full width and 288px from 640px up.
- Search: An Input group at the top of the popup, Search city, zone or offset, focused when the list opens.
- Region label: Americas, Europe, Africa, Asia and so on, 12px Slate Meta, sticky while its zones scroll.
- City and zone ID: A 36px two-line row: the city in 13px and the IANA ID in 11px Geist Mono.
- Offset and local time: 12px Slate Meta tabular figures at the right: the offset and the current time in that zone.

States:
- Rest: Transparent trigger with the Field Stroke. In dark, the input color at 30%, rising to 50% on hover.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 50%.
- Open: The trigger keeps its indigo border. The popup is 22rem wide and scrolls at 20rem, with the first match highlighted.
- Highlighted and selected: The highlighted row fills with the accent color; the chosen zone carries a check.
- Empty: No time zones match “…”. Try a city like Chicago.
- Disabled: 50% opacity and a not-allowed cursor.

Behavior:
- Controlled only: pass an IANA ID as `value` and update it in `onValueChange`. There's no empty state, so start from a saved zone or the browser's `Intl.DateTimeFormat().resolvedOptions().timeZone`.
- The list comes from `Intl.supportedValuesOf("timeZone")`, falling back to 28 common zones on older browsers. UTC is always included, and a `value` missing from the list is added so it still shows.
- Within a region, zones sort by offset, then by city. Search ignores case and treats a true minus sign and a hyphen alike; the text clears when the list closes.
- Offsets are for the current moment, so they follow daylight saving: Chicago reads UTC−05:00 in summer and UTC−06:00 in winter.
- Nothing is computed until the list opens, and during server rendering the local times are omitted. While open, local times refresh every 30 seconds.
- `hour12` only changes the local time preview in the rows. Pair it with the same 12h or 24h setting used elsewhere on the page.

Do and don't:
- Do: Store an IANA ID and let people search every zone by city.
- Don't: Offer a short list of abbreviations. Lisbon, Lagos and Kolkata aren't in it, and CST is wrong half the year.

Content:
- Label it Time zone. Say in the description what follows the zone: Payment runs, reminder calls and business hours use this zone.
- Show cities, not abbreviations. Chicago, UTC−05:00 is unambiguous; CST isn't.
- When a zone is locked, say who set it and who can change it, beside the control.

Accessibility:
- The trigger is a button with the Base UI combobox semantics. Name it with a `Label` pointed at its `id`, or `aria-label` when there's no visible label.
- Link a description with `aria-describedby`; in a settings row, use `descriptionId(id)`.
- The search input is labelled Search time zones, and focus moves into it when the list opens.
- Offsets use a true minus sign, which screen readers read as minus.
- Enter: Opens the list from the trigger. Space does too.
- A–Z: Typing in the search box filters the zones.
- ↓ + ↑: Moves the highlight through the matches.
- Enter: Chooses the highlighted zone and closes the list.
- Esc: Closes the list, clears the search and returns focus to the trigger.

Known gaps (follow the system, not the gap):
- Zone IDs in the rows are 11px (`text-[0.6875rem]`). The Thirteen-Fourteen Rule keeps 11px for footnotes; meta text is 12px.
- There's no invalid state or `aria-invalid` prop, no size prop and no light-mode hover fill, unlike Select.
- No pinned group for the browser's own zone or recent picks, so people search even for their own city.
- In the app it renders only inside Business hours picker; the settings pages import `timeZoneCity` alone.

API `TimezoneSelect`:
- `value: string`. The IANA ID, such as `America/Chicago`.
- `onValueChange: (value: string) => void`. Called with the chosen IANA ID.
- `id?: string`. Set on the trigger, for a `Label`'s `htmlFor`.
- `aria-label?: string`. Names the trigger when there's no visible label.
- `aria-describedby?: string`. Links a description or error to the trigger.
- `hour12?: boolean` = true. 12-hour local times in the rows; `false` for 24-hour.
- `disabled?: boolean`. Dims the trigger and blocks opening.
- `className?: string`. Merged onto the trigger, for width.

API `listTimeZones`:

API `timeZoneCity`:

API `offsetMinutes`:

API `formatUtcOffset`:

API `formatLocalTime`:

### Segmented control

- Level: Molecule
- Category: Selection
- Status: Stable
- Import: `@oration/canon/components/segmented-control`
- Exports: `SegmentedControl`
- Docs: /design/components/segmented-control

Segmented control is a small radio group drawn as a Well Gray track with a white thumb that slides to the chosen option. It switches the mode of what is already on screen: a list filter, a date range, 12h or 24h, list or board. It is one of the most used controls in the suite. The common mistake is using it to switch between different panels of content, which is the job of Tabs, or stretching it past five options, where the labels start to wrap and overflow.

When to use:
- To filter or re-sort the list or chart right below it: All, Open, Overdue, Paid.
- For a date range on a chart or report: 7 days, 30 days, 90 days.
- For a binary format setting that applies at once, such as 12h and 24h.
- To switch the view of the same records, such as list, board and calendar, with icons.
- When all two to five options should stay visible and the choice applies immediately.

When not to use:
- To move between panels with different content, such as a record's Overview and Activity. Use /design/components/tabs instead.
- For six or more options, or options with long labels. Use /design/components/select-field instead.
- When several options can be on at once, such as formatting or channel filters. Use /design/components/toggle-group instead.
- For a choice in a form that needs a description per option. Use /design/components/choice-card instead.
- For an on and off setting. Use /design/components/switch instead.

Rules:
- Two to five modes: Every option is a short word or two, and all of them fit on one line at the narrowest width the view supports. Past five, use a select.
- Every group has a name: `label` is required and becomes the radio group's `aria-label`. Name what is being chosen, such as Filter invoices by status, even when a visible heading sits beside it.

Anatomy:
- Track: A 28px Well Gray pill with 2px padding and 10px corners. It hugs its options.
- Segment: A 24px button with 8px corners and 8px side padding. Unselected segments are Slate Meta.
- Thumb: White Plane with the hairline lift behind the selected segment. It slides between segments on a 0.3s spring with no bounce.
- Label: Medium weight in ink when selected, regular in Slate Meta otherwise.
- Icon: Optional, 14px, before the label. With `hideLabel`, the icon stands alone and the label becomes the `aria-label`.

States:
- Rest: Slate Meta label on the Well Gray track.
- Hover: The label darkens to ink over 150ms. No fill.
- Selected: The white thumb with hairline lift sits behind it, and the label turns medium weight in ink.
- Focus visible: A 3px Focus Indigo ring at 40% around the focused segment.
- Moving: The thumb slides to the new segment on a 0.3s spring. With reduced motion, the app's motion config makes it jump.

Behavior:
- Controlled only: pass `value` and update it in `onValueChange`. The value type narrows to the option values, so `SegmentedControl<Filter>` rejects a typo.
- Clicking a segment selects it. Arrow keys move focus and select in one step, wrapping at the ends, so the choice applies as people move.
- Only the selected segment is in the tab order; Tab enters and leaves the group in one stop.
- Each instance has its own thumb, so several controls on one page animate independently.
- The track hugs its content. `w-full` widens the track but not the segments; add `[&>button]:flex-1` to stretch them.
- Counts in labels come from the string you pass, such as Open 48. Update them as the list changes.

Do and don't:
- Do: Keep to two to five short options that fit on one line.
- Don't: Put seven weekdays in a segmented control. It overflows, and a run day belongs in a select.
- Do: Use it to change the mode of the list or chart right beside it.
- Don't: Use it to switch between panels of different content. That's Tabs, with its tab and panel semantics.

Content:
- One or two words per option, sentence case, parallel in form: Week, Month, Quarter.
- Counts follow the word with a space: Overdue 9. No brackets or dots.
- Spell out units: 7 days, not 7d, except for established forms such as 12h.
- The `label` names the choice as a phrase: Filter invoices by status, Time format.

Accessibility:
- The track is `role="radiogroup"` with `aria-label` from `label`; each segment is `role="radio"` with `aria-checked`.
- Icon-only segments (`hideLabel`) get the label as `aria-label`. There's no tooltip, so pick icons people already know.
- Mark icons `aria-hidden="true"`; the label names the option.
- Segments are 24px tall, the minimum target size. Don't shrink them further on touch layouts.
- Selection follows focus, so don't attach slow work to a change without a pending state.
- Tab: Moves focus to the selected segment, then out of the group.
- →: Selects the next option, wrapping to the first.
- ←: Selects the previous option, wrapping to the last.
- Space: Selects the focused option (it already is, after arrow keys).

Known gaps (follow the system, not the gap):
- Segment labels are meant to be 13px, but the `cn` package drops `text-13` next to the text color, so they inherit the parent's size, usually 14px. Pass `className="text-[13px]"` on the track until it's fixed.
- There's no `disabled` prop for the control or for single options, and no size other than 28px.
- Only ← and → move the selection. The radio group pattern also expects ↑ and ↓, and Home and End aren't handled.
- Icon-only segments have no tooltip, unlike icon buttons elsewhere, so sighted people get no name for the icon.
- Counts in labels are plain strings in proportional figures, so segment widths shift as counts change, against the Tabular Figures Rule.

API `SegmentedControl`:
- `value: T`. The selected option's value.
- `onValueChange: (value: T) => void`. Called on click and on arrow keys.
- `options: SegmentedOption<T>[]`. Two to five options, in order.
- `label: string`. The radio group's accessible name.
- `className?: string`. Merged onto the track. Pass `text-[13px]` so the labels get their size (see Known gaps).

API `SegmentedOption`:
- `value: T`. The value reported on change.
- `label: string`. The visible label, or the `aria-label` with `hideLabel`.
- `icon?: ReactNode`. A 14px icon before the label.
- `hideLabel?: boolean` = false. Shows only the icon and moves the label to `aria-label`.

### Toggle group

- Level: Molecule
- Category: Selection
- Status: Beta
- Import: `@oration/canon/components/toggle-group`
- Exports: `ToggleGroup`, `ToggleGroupItem`
- Docs: /design/components/toggle-group

Toggle group is a row of toggle buttons built on Base UI Toggle group, where one or several can be pressed at once. It suits formatting and on-and-off filters that apply as you press: bold and italic in a remittance template, the channels shown in a report. With single selection it acts like a radio group, except that pressing the pressed item clears the value, so guard against the empty array when a value is required. For view modes that should read as one control, use a segmented control instead.

When to use:
- For formatting controls in an editor toolbar: bold, italic, underline, alignment.
- For filters that combine, such as which channels a report shows.
- For a single choice with icons and labels that may wrap, such as a chart's visualization in a settings sheet.
- For a joined set of icon toggles, such as column alignment, with `spacing={0}`.

When not to use:
- For two to five view modes or a date range beside a list or chart. Use /design/components/segmented-control instead.
- For one on and off button on its own, such as Mute. Use /design/components/toggle instead.
- For a setting that is on or off in a settings row. Use /design/components/switch instead.
- For actions such as Approve or Export. Toggles hold state; actions don't. Use /design/components/button-group instead.
- For a form choice that needs a description per option. Use /design/components/choice-card instead.

Rules:
- Name the group and every icon: Give the group an `aria-label` or point `aria-labelledby` at its heading. Icon-only items carry an `aria-label` and a tooltip with the same words.
- Toggles apply at once: Pressing an item changes what is on screen right away. If the change needs a Save, it belongs in a form control, not a toggle.

Anatomy:
- Group: A `role="group"` row with an 8px gap (`spacing={2}`). `spacing={0}` joins the items.
- Item: A 32px toggle button (28px at `sm`, 36px at `lg`) with 10px corners and 14px medium text. Outline adds the Field Stroke.
- Icon: 16px (14px at `sm`). Mark it `data-icon="inline-start"` beside a label so the padding tightens by 2px.
- Pressed fill: Well Gray behind a pressed item, set from `aria-pressed`.

States:
- Rest: Transparent. Outline items show the Field Stroke.
- Hover: Well Gray fill and ink text over 150ms.
- Pressed: Well Gray fill, `aria-pressed="true"` and `data-pressed`. The same fill as hover.
- Focus visible: A 3px Focus Indigo ring at 50%. Outline items also take an indigo border.
- Disabled: 50% opacity and no pointer events. `disabled` on the group disables every item.

Behavior:
- The value is always an array of item values, even with one choice: `value={[align]}`. Control it with `value` and `onValueChange`, or start it with `defaultValue`.
- Without `multiple`, pressing an item releases the others, and pressing the pressed item empties the array. Ignore the empty array when the setting needs a value: `if (next[0]) setAlign(next[0])`.
- With `multiple`, each item toggles on its own.
- Arrow keys move focus between items and loop at the ends (`loopFocus`); Home and End jump to the first and last. Moving focus doesn't press anything.
- `variant` and `size` set on the group apply to every item. Item-level values are used only when the group doesn't set one.
- `spacing` is the gap in spacing units (2 is 8px). At `0`, inner corners go square and outline borders collapse to one hairline.
- `orientation="vertical"` stacks the items for layout only; see Known gaps.

Do and don't:
- Do: Name the group and give every icon-only item an `aria-label` and a tooltip.
- Don't: Ship bare icons. Screen readers announce toggle button, pressed, and nothing else.
- Do: Use toggles for filters and formatting that combine and apply at once.
- Don't: Use a single-choice toggle group for view modes. The segmented control reads as one choice and has the sliding thumb.

Content:
- Labels are one word where possible: Email, Voice, Bar.
- Tooltips and `aria-label`s name the effect, not the icon: Align left, not Left lines icon.
- Don't change the label when pressed. The pressed fill carries the state.

Accessibility:
- The group is `role="group"`. Name it with `aria-label`, or with `aria-labelledby` pointing at a visible heading or a `<legend>`.
- Each item is a `<button>` with `aria-pressed`, so screen readers announce it as a toggle button, pressed or not pressed.
- Icon-only items need an `aria-label` and a tooltip; mark icons `aria-hidden="true"`.
- The group is one tab stop; arrow keys move within it.
- `sm` items are 28px, above the 24px minimum target. Use the default size on touch layouts.
- Tab: Moves focus into the group, then out of it.
- ← + →: Moves focus to the previous or next item, looping at the ends.
- Home + End: Moves focus to the first or last item.
- Space: Presses or releases the focused item.
- Enter: Presses or releases the focused item.

Known gaps (follow the system, not the gap):
- `sm` sets labels at `0.8rem` (12.8px), off the type ramp. The Thirteen-Fourteen Rule calls for 13px in dense UI.
- Pressed and hover share the same Well Gray fill, so a hovered item and a pressed one look identical.
- `orientation` is used for layout and not passed to Base UI, so a vertical group still moves focus with ← and →, not ↑ and ↓.
- One product use, the visualization picker in the insight sheet, which uses it for a single required choice.

API `ToggleGroup` (extends Base UI `ToggleGroup` (`<div>`)):
- `value?: readonly string[]`. Controlled pressed values. An array even without `multiple`.
- `defaultValue?: readonly string[]`. Initial pressed values when uncontrolled.
- `onValueChange?: (groupValue: string[], eventDetails) => void`. Called with the new array. It can be empty.
- `multiple?: boolean` = false. Lets several items be pressed at once.
- `variant?: "default" | "outline"`. Applied to every item. Items default to `default`.
- `size?: "default" | "sm" | "lg"`. Applied to every item: 32, 28 or 36px.
- `spacing?: number` = 2. Gap in spacing units. `0` joins the items.
- `orientation?: "horizontal" | "vertical"` = "horizontal". Row or column layout.
- `disabled?: boolean` = false. Disables every item.
- `loopFocus?: boolean` = true. Arrow keys wrap from the last item to the first.

API `ToggleGroupItem` (extends Base UI `Toggle` (`<button>`)):
- `value: string`. The value added to the group's array when pressed.
- `variant?: "default" | "outline"` = "default". Used when the group sets none.
- `size?: "default" | "sm" | "lg"` = "default". Used when the group sets none.
- `disabled?: boolean` = false. Disables this item.

### Choice card

- Level: Molecule
- Category: Selection
- Status: Beta
- Import: `@oration/canon/components/choice-card`
- Exports: `ChoiceCard`, `ChoiceCards`
- Docs: /design/components/choice-card

Choice card turns each option of a radio choice into a card with a title and a one-line description, for picking between a few modes whose difference needs a sentence. It comes in two forms: `ChoiceCard`, one card you place inside a `RadioGroup` with optional leading and trailing slots, and `ChoiceCards`, a self-contained grid built from an `options` array. Campaign steps and agent config pages use them. The common mistake is cards for choices that explain themselves, such as days, weeks and months, where a segmented control or a plain radio group is lighter.

When to use:
- For two to five modes that change how something works, each needing a sentence: what happens when a call reaches voicemail, who places reminder calls.
- When the choice carries a consequence worth showing in the card, such as a cost in credits or a threshold.
- In a campaign or setup step where the choice is the main decision on the screen.
- On agent config pages, as `ChoiceCards` in a grid of two to five columns.

When not to use:
- For short labels that explain themselves. Use a segmented control beside a list, or a radio group in a form. Use /design/components/segmented-control instead.
- For a plain list of options in a form. Use /design/components/radio-group instead.
- For more than five options. Use /design/components/select-field instead.
- For a setting that is on or off. Use /design/components/switch instead.
- When several options can be chosen. Choice cards are single choice only. Use /design/components/checkbox instead.

Rules:
- The Quiet Indigo Rule: Selection is one of the few places indigo is spent: the chosen card takes an indigo ring or border, a faint indigo tint and an indigo radio. Icons inside cards stay Slate Meta.
- The Hairline-and-Lift Rule: A card takes its edge from the composite hairline shadow, as `ChoiceCards` does. `ChoiceCard` still draws a CSS border; see Known gaps.

Anatomy:
- Card: The whole card is the label, so a click anywhere selects. `ChoiceCard`: 10px corners, a 1px border and 10px padding. `ChoiceCards`: 12px corners, the hairline lift and 12px padding.
- Radio: A 16px radio at the top left. It fills with indigo when chosen.
- Title: 14px medium ink, one line. In `ChoiceCards`, an optional 14px Slate Meta icon leads it.
- Description: 13px Slate Meta, one sentence, wraps with `text-pretty`.
- Trailing: `ChoiceCard` only: a node at the right, such as a cost or a threshold in 12px tabular figures. `leading` adds one between the radio and the title.

States:
- Rest: `ChoiceCard`: Card White with a hairline border. `ChoiceCards`: Card White with the hairline lift.
- Hover: `ChoiceCard` fills Well Gray at 50%. `ChoiceCards` deepens to the hover lift over 150ms.
- Checked: `ChoiceCard`: indigo border at 30% and a 5% indigo tint. `ChoiceCards`: a 1.5px indigo ring and a 4% indigo tint. The radio fills with indigo in both.
- Focus visible: `ChoiceCard`: an indigo border and a 3px ring at 50% on the card. `ChoiceCards`: a 3px Focus Indigo ring at 40%.
- Disabled: `ChoiceCard` dims to 50% when its `RadioGroup` is disabled. `ChoiceCards` has no disabled state.

Behavior:
- `ChoiceCard` must be a child of `RadioGroup`, which owns `value`, `onValueChange` and the keyboard. Each card needs a unique `id`; it links the label to the radio.
- `ChoiceCards` is controlled with `value` and `onValueChange` and needs a `label` for the group. The value type narrows to the option values.
- In both, arrow keys move between cards and select as they go, and only the chosen card is in the tab order.
- `ChoiceCards` lays out one column below 640px. `columns` sets the grid above that: 2 or 3 from 640px, 4 as two then four from 1024px, 5 as three then five.
- `ChoiceCards` renders buttons with radio roles, not native inputs, so it doesn't submit with a native form.

Do and don't:
- Do: Use cards when each option needs a sentence to choose well.
- Don't: Put one-word options with nothing to explain in cards. Three cards that say Days, Weeks and Months are a segmented control.
- Do: Keep one treatment per surface: `ChoiceCards` on config pages, `ChoiceCard` in campaign steps.
- Don't: Mix the bordered and the lifted card on one screen. They read as two different controls.

Content:
- Titles name the outcome in a few words, sentence case: Leave a message, Hang up and try later.
- Descriptions are one sentence on what happens, in plain words: The supplier is called again in four hours, up to three times.
- Head the group with a question or a situation: When a call reaches voicemail.
- Put costs and thresholds in the trailing slot in tabular figures, not in the title.

Accessibility:
- `ChoiceCard` uses Base UI Radio: each card is a `<label>` for a `role="radio"`. Name the `RadioGroup` with `aria-labelledby` pointing at its heading.
- `ChoiceCards` renders `role="radiogroup"` with `aria-label` from `label`, and each card is a `<button role="radio">` with `aria-checked`.
- The title and description are both inside the label, so screen readers read the description as part of the option's name. Keep it to one sentence.
- Mark icons `aria-hidden="true"`.
- The whole card is the hit area, well above the 24px minimum.
- Tab: Moves focus to the chosen card, then out of the group.
- ↓ + →: Selects the next card, wrapping to the first.
- ↑ + ←: Selects the previous card, wrapping to the last.
- Space: Selects the focused card.

Known gaps (follow the system, not the gap):
- Two components, two looks. `ChoiceCard` draws a CSS border with 10px corners, breaking the Hairline-and-Lift Rule; `ChoiceCards` uses the hairline lift with 12px corners. The checked states differ too.
- `ChoiceCard` passes `text-13` to `FieldDescription` through the `cn` package, which treats it as a color and drops `text-muted-foreground`, so the description renders in ink instead of Slate Meta.
- Neither has a per-option `disabled`, and `ChoiceCards` can't be disabled at all.
- `ChoiceCards` isn't built on Base UI Radio, so it has no hidden input and doesn't post with a native form.

API `ChoiceCard`:
- `id: string`. Unique id that links the card's label to its radio.
- `value: string`. The value the group reports when this card is chosen.
- `title: ReactNode`. The option's name.
- `description?: ReactNode`. One sentence on what the option does.
- `leading?: ReactNode`. Rendered between the radio and the title, such as an icon tile.
- `trailing?: ReactNode`. Rendered at the right, such as a cost or threshold.

API `ChoiceCards`:
- `value: V`. The chosen option's value.
- `onValueChange: (value: V) => void`. Called on click and arrow keys.
- `options: { value: V; label: string; description?: ReactNode; icon?: ReactNode }[]`. The cards, in order.
- `label: string`. The radio group's accessible name.
- `columns?: 2 | 3 | 4 | 5` = 2. Grid columns from 640px up. Always one column below.
- `className?: string`. Merged onto the grid.

### Filter chip

- Level: Molecule
- Category: Selection
- Status: Beta
- Import: `@oration/canon/components/filter-chip`
- Exports: `FilterChip`, `FilterChipRow`
- Docs: /design/components/filter-chip

Filter chip shows one active filter above a list: the field's icon, the field, the operator, the values and a remove button, in a 28px chip with a 6% indigo tint and a 22% inset indigo ring. Chips sit in a `FilterChipRow` after the list's filter menu, followed by Clear all, as in the tickets and records toolbars. It is a control, not a value. The common mistake is reaching for a tag to show a filter; tags show a record's values and never take the indigo tint.

When to use:
- To show each active filter on a list or table so people can see why rows are missing.
- To let people remove one filter without opening the filter menu.
- In a toolbar row with a filter menu before it and Clear all or Save as view after it.

When not to use:
- To show a record's stage, tier or other option value. Use /design/components/tag instead.
- For a quick filter that is always visible and has two to five values. Use /design/components/segmented-control instead.
- For filters that combine and toggle on and off in place, such as channels. Use /design/components/toggle-group instead.
- For values people type into a field, such as email domains. Use /design/components/tag-input instead.
- For a status that needs a label beside a colored dot. Use /design/components/status-label instead.

Rules:
- The Quiet Indigo Rule: An active filter is live state with a text label, one of the few places indigo is spent: a 6% tint and a 22% inset ring. The text stays ink and Slate Meta.
- Chips are controls, tags are values: Tags show what a record is, in the option hues, and never take a remove button. Filter chips show what the list is narrowed to, always in the indigo tint.

Anatomy:
- Chip: 28px, 8px corners, 8px left and 2px right padding, a 6% indigo fill and a 22% inset indigo ring. 13px text.
- Icon: The field's icon at 14px in Slate Meta, passed through `icon`.
- Field and operator: The field name and is or is any of, both Slate Meta.
- Values: `valuesLabel` in medium ink, truncated at 192px.
- Remove: A 24px button with a 14px X, labelled Remove {field} filter.

States:
- Rest: Indigo tint and ring, with Slate Meta field and operator.
- Remove hover: The remove button fills Well Gray and the X turns ink.
- Remove focus visible: A 3px Focus Indigo ring at 40% around the remove button.
- Truncated: Values longer than 192px end in an ellipsis. There's no tooltip with the full list.
- Empty: With no filters, render no chips. Say what the list shows instead, such as Showing all 212 invoices, or let the count carry it.

Behavior:
- The chip holds no state. Keep the filters with the list, render one chip per filter and remove it in `onRemove`.
- `multiple` switches the operator text from is to is any of. Pass `values.length > 1`.
- `valuesLabel` is a ready string: join the labels yourself, such as `labels.join(", ")`.
- Only the remove button is interactive. To change a filter's values, open the filter menu beside the chips.
- `FilterChipRow` is a wrapping flex row with a 6px gap; it accepts any `<div>` props.
- Removing a chip unmounts its button, so move focus to the next chip's remove button or to the filter menu trigger.

Do and don't:
- Do: Show active filters as filter chips with the field, the operator and the values.
- Don't: Show a filter as a colored tag. It reads as the record's status, not as a filter on the list.

Content:
- The field is the column's name as it appears in the table header: Supplier, Status, Owner.
- Values use the same labels as the cells, joined with a comma and a space: Northwind Freight, Halcyon.
- Date values are plain ranges: Next 7 days, This quarter, not a pair of ISO dates.
- Follow the row with Clear all, and Save as view when views exist, both as small ghost buttons.

Accessibility:
- The chip is a `<span>`; its text reads as a phrase: Supplier is any of Northwind Freight, Halcyon.
- The remove button is named Remove {field} filter from `field`, so each one is distinct.
- After a removal, move focus somewhere useful; otherwise it falls to the page.
- Announce the new result count near the list, for example in a polite live region, so screen reader users learn what changed.
- The remove button is 24px, the minimum target size.
- Tab: Moves focus to each chip's remove button in turn.
- Enter: Removes the filter.
- Space: Removes the filter.

Known gaps (follow the system, not the gap):
- The chip body isn't a button, so there's no way to edit a filter from its chip. The tickets and records toolbars reopen the full filter menu instead.
- The operator is fixed to is and is any of. There's no is not, before or after, so date and negative filters can't be shown honestly.
- Truncated values have no tooltip or `title`, so a long supplier list can't be read without opening the menu.
- `FilterChip` accepts no `className` or other props, so it can't take a `ref`, a test id or a different width.

API `FilterChip`:
- `icon: ReactNode`. The field's icon, usually 14px in Slate Meta with `aria-hidden`.
- `field: string`. The field name. Also names the remove button.
- `valuesLabel: string`. The chosen values as one string.
- `multiple: boolean`. Shows is any of instead of is.
- `onRemove: () => void`. Called when the remove button is pressed.

API `FilterChipRow` (extends `<div>`):

### Button group

- Level: Molecule
- Category: Actions
- Status: Beta
- Import: `@oration/canon/components/button-group`
- Exports: `ButtonGroup`, `ButtonGroupSeparator`, `ButtonGroupText`
- Docs: /design/components/button-group

Button group joins buttons, inputs and text addons into one control: the inner corners go square, neighboring borders collapse into one hairline and the outer corners keep the button radius. It is for actions that belong together, most often a split button where a chevron opens variants of the main action. The agent header's preview button is the product's one use today. The common mistake is joining unrelated actions, or mixing variants inside one group, which turns a toolbar into a single confusing shape.

When to use:
- For a split button: a main action joined to a chevron that opens its variants, such as Download PDF with CSV and remittance formats.
- For a pair of icon buttons that act as one control, such as previous and next record, or zoom in and out.
- For a fixed prefix or suffix joined to an input and its action, such as INV- before an invoice number.
- For two or three closely related actions on the same object, all in the same variant.

When not to use:
- For a set of modes where one is selected. Use /design/components/segmented-control instead.
- For toggles that stay pressed, such as bold and italic. Use /design/components/toggle-group instead.
- For a row of unrelated page actions. Space them with a 6px gap instead. Use /design/components/toolbar instead.
- For an input with an icon or a button inside its border. Use /design/components/input-group instead.
- For a long list of actions behind one trigger. Use /design/components/dropdown-menu instead.

Rules:
- The One Filled Button Rule: A group counts as one control. Keep its buttons outline, secondary or ghost; if the view's primary action has variants, the filled button stands alone and the variants move to a menu.
- Concentric radii: Only the outer corners of the group keep the button radius. Inner corners are square so the group reads as one shape.

Anatomy:
- Group: A `role="group"` flex row (or column) that fits its content. Name it with `aria-label`.
- Leading button: Keeps its outer corners; its trailing corners go square.
- Seam: The next child drops its left border (top border when vertical), so neighbors share one hairline.
- Trailing button: Keeps 10px trailing corners, here a square icon button with the chevron.

States:
- Rest: Each child draws its own variant; the group adds nothing.
- Hover and pressed: From Button: Well Gray on outline and ghost, a 0.96 press scale.
- Focus visible: The focused child moves above its neighbors (`z-10`) so its indigo border and 3px ring aren't clipped by the next button.
- Expanded: A chevron that opens a menu keeps its hover fill while the menu is open.
- Disabled: Per child. A disabled button dims to 50% and the seam stays in place.

Behavior:
- Only direct children with a `data-slot` take part in the joining: Button, Input, Select trigger, `ButtonGroupText` and `ButtonGroupSeparator` all have one.
- Each button is its own tab stop. There's no roving focus, so Tab moves through the group one button at a time.
- An `Input` grows to fill the group (`flex-1`); a Select trigger shrinks to its content unless it has a width class.
- Groups nested in a group sit 8px apart, for a toolbar made of several joined controls.
- Small and extra-small buttons switch to 10px corners inside a group so the outer corners match.
- `ButtonGroupSeparator` is vertical by default and draws a 1px rule in the input color between borderless buttons.

Do and don't:
- Do: Join a main action to its variants, in one variant.
- Don't: Join unrelated actions in mixed variants. Edit, Export, a red Delete and a filled Approve read as one broken control.

Content:
- The main button names the default variant: Download PDF, Export CSV.
- The chevron's `aria-label` says what the menu holds: More download formats, not More or Options.
- Prefix text in `ButtonGroupText` is the literal string the value needs, such as INV- or https://.

Accessibility:
- The group is `role="group"`. Give it an `aria-label` that names the set, such as Download or Move between invoices.
- Icon-only buttons in a group still need an `aria-label` and a tooltip.
- A chevron that opens a menu is a menu trigger: it exposes `aria-haspopup` and `aria-expanded` through Dropdown menu.
- An input in a group needs its own label, visible or `sr-only`; the prefix text isn't a label.
- Tab: Moves to the next button in the group, then out.
- Enter: Activates the focused button.
- Space: Activates the focused button.

Known gaps (follow the system, not the gap):
- DESIGN.md says buttons inside groups step down to 8px corners. In code, small and extra-small buttons step up to 10px (`in-data-[slot=button-group]:rounded-lg`), and inner corners go square instead.
- `ButtonGroupText` draws a CSS border in `--border`, while the outline buttons beside it use `--input` in dark mode, so the seam color can differ.
- Nothing enforces a name: `role="group"` without `aria-label` is announced as an unnamed group.
- One product use, the agent header's preview split button.

API `ButtonGroup` (extends `<div>`):
- `orientation?: "horizontal" | "vertical"` = "horizontal". Join left to right, or stack top to bottom.
- `aria-label?: string`. Names the group for screen readers.
- `className?: string`. Merged onto the group, for width.

API `ButtonGroupText` (extends `<div>` through Base UI `useRender`):
- `render?: ReactElement | (props, state) => ReactElement`. Render as another element, such as a `<label>`.
- `className?: string`. Merged onto the addon.

API `ButtonGroupSeparator` (extends Separator):
- `orientation?: "horizontal" | "vertical"` = "vertical". Vertical between side-by-side buttons; horizontal in a vertical group.

### Icon action

- Level: Molecule
- Category: Actions
- Status: Beta
- Import: `@oration/canon/components/icon-action`
- Exports: `IconAction`
- Docs: /design/components/icon-action

Icon action is an icon-only button with its tooltip, accessible name and pressed state built in: one `label` becomes both the `aria-label` and the tooltip. It is a 28px ghost button in Slate Meta by default, for composers, call bars, toolbars and row actions where space is tight. Pass `active` and it becomes a toggle. The common mistake is an icon nobody can guess, such as a custom glyph for Reconcile; when the action needs a word to be understood, use a button with a label.

When to use:
- For familiar actions in a composer or editor toolbar: attach a file, insert a macro, insert a variable.
- For call controls that toggle, such as mute and hold, with `active`.
- For row actions at the end of a table row or list item, at `icon-xs`.
- For actions with a keyboard shortcut you want to teach, through `shortcut`.

When not to use:
- When the action needs a word to be understood, or is the main action of the view. Use /design/components/button instead.
- To open a menu or popover. Icon action doesn't forward the props a trigger needs; use a Button with a Tooltip. Use /design/components/dropdown-menu instead.
- To copy a value. The ready-made version confirms with a check. Use /design/components/copy-button instead.
- For a set of formatting toggles that act as one group. Use /design/components/toggle-group instead.

Rules:
- Icon-only buttons carry a name: `label` is required. It is announced as the button's name and shown in the tooltip, so sighted and screen reader users get the same words.
- The One Filled Button Rule: Icon actions are never the filled button. Variants stop at ghost, outline and secondary, so a toolbar of them never competes with the view's primary action.

Anatomy:
- Button: A square ghost Button, 28px with 8px corners by default. Here in its active state, with the Well Gray fill.
- Icon: 16px (12px at `icon-xs`), Slate Meta at rest, ink on hover and when active.
- Tooltip: Ink fill with 12px Plane text, 6px corners, showing `label`. Opens on hover and keyboard focus.
- Shortcut: Optional `shortcut` node, usually a `Kbd`, after the label.

States:
- Rest: Transparent with a Slate Meta icon. Outline adds the hairline and control shadow.
- Hover: Well Gray fill and an ink icon over 150ms; the tooltip opens.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 40%; the tooltip opens.
- Pressed: Scales to 0.96 while held, when motion is allowed.
- Active: With `active`, the Well Gray fill and ink icon stay on and `aria-pressed="true"` is set.
- Disabled: 50% opacity, no pointer events and no tooltip, so nothing explains why.

Behavior:
- `label` sets the `aria-label` and the tooltip text. Change it with the state for toggles: Mute and Unmute.
- `active` is `aria-pressed`. Leave it undefined for a plain action; pass `true` or `false` to make it a toggle.
- `onClick` takes no arguments. Use a Button with a Tooltip if you need the event.
- `shortcut` is display only. Bind the key yourself, and keep the key and the tooltip in sync.
- It renders its own `Tooltip`, so don't wrap it in another one. It accepts no `ref` and doesn't spread other props, so it can't be the `render` target of a menu, popover or dialog trigger.

Do and don't:
- Do: Use icon actions for actions people recognize from the icon alone: attach, download, close.
- Don't: Hide uncommon actions behind abstract icons. Nobody guesses that braces mean Reconcile with bank feed.

Content:
- Labels start with a verb and name the object when it isn't obvious: Attach a file, Download statement.
- In repeated rows, name the row: Download remittance for Halcyon, so each button has a distinct name.
- For toggles, the label says what pressing will do now: Mute when live, Unmute when muted.
- Use the shortcut people actually press: E, /, Esc. No modifier glyphs you haven't bound.

Accessibility:
- The name comes from `label` through `aria-label`. The tooltip repeats it for sighted users and opens on keyboard focus too.
- Toggles expose `aria-pressed`, so screen readers announce pressed or not pressed.
- Mark the icon `aria-hidden="true"`; the label names the action.
- The shortcut is only in the tooltip, so screen reader users don't hear it. Mention it in help or onboarding as well.
- `icon-xs` is 24px, the minimum target size. Use `icon-sm` or larger on touch layouts.
- Row actions that fade until hover must stay visible on focus (`group-focus-within`), as in the example.
- Tab: Moves focus to the button and opens its tooltip.
- Enter: Activates the action or flips the toggle.
- Space: Activates the action or flips the toggle.
- Esc: Closes the tooltip.

Known gaps (follow the system, not the gap):
- It accepts no `ref` and doesn't spread props, so it can't be a menu, popover or dialog trigger, and it can't take `aria-expanded`, `aria-controls` or `type`.
- A disabled icon action shows no tooltip (no `focusableWhenDisabled`), so people can't learn what it is or why it's off.
- The shortcut isn't exposed to assistive tech; there's no `aria-keyshortcuts`.
- Only the contact center uses it (6 files), while about 59 product files compose `Tooltip` by hand, many of them around an icon Button.

API `IconAction`:
- `label: string`. The accessible name and the tooltip text.
- `children: ReactNode`. The icon, with `aria-hidden`.
- `onClick?: () => void`. Called on activation.
- `active?: boolean`. Sets `aria-pressed` and keeps the Well Gray fill. Undefined means not a toggle.
- `disabled?: boolean`. Dims to 50% and blocks interaction and the tooltip.
- `size?: "icon-xs" | "icon-sm" | "icon" | "icon-lg"` = "icon-sm". 24, 28, 32 or 36px.
- `variant?: "ghost" | "outline" | "secondary"` = "ghost". Button variant. No filled option.
- `shortcut?: ReactNode`. Shown after the label in the tooltip, usually a `Kbd`.
- `className?: string`. Merged onto the button.

### Pending button

- Level: Molecule
- Category: Actions
- Status: Beta
- Import: `@oration/canon/components/pending-button`
- Exports: `PendingButton`
- Docs: /design/components/pending-button

Pending button is a Button that shows work in progress without changing size: while `pending`, the label fades out in place and a 16px spinner sits on top, so the row never jumps. It also swallows clicks while pending, so a payment run can't be scheduled twice. It takes every Button variant and size. The common mistake is swapping the label for Saving…, which changes the width and moves everything beside it.

When to use:
- For any button whose action waits on the network: Schedule run, Send remittance, Sync bank feed.
- For a form's submit button, so double submits are ignored while the request is in flight.
- For sign-in provider buttons that redirect after a short wait.
- In a dialog or sheet footer, where a width change would shift the buttons beside it.

When not to use:
- For an action that completes instantly. Show the result instead, such as a toast or the updated row. Use /design/components/button instead.
- For a long job such as an import. Close the dialog and show progress where the result will appear. Use /design/components/progress instead.
- For a destructive action that needs deliberate confirmation. Use /design/components/hold-button instead.
- For loading a region of the page. Use /design/components/skeleton instead.

Rules:
- The One Filled Button Rule: Pending doesn't change the variant. The filled button stays the one filled button while it works, and the buttons beside it keep their weight.
- Hold the width: The label stays in the layout at zero opacity, so the button keeps the width of its resting label. Don't change the label while pending.

Anatomy:
- Button: A regular Button in any variant and size, with `cursor-progress` while pending.
- Label: The children, wrapped in a span that fades to 0 over 150ms on the house ease-out but keeps its space.
- Spinner: A 16px spinner centered over the label, in the variant's text color, only while pending.

States:
- Rest: Exactly a Button of the same variant.
- Hover, focus, pressed: From Button: the variant's hover fill, the indigo focus ring, the 0.96 press scale.
- Pending: Label at 0% opacity, spinner centered, `aria-disabled="true"`, `data-pending` and a progress cursor. The fill doesn't dim, and focus stays on the button.
- Disabled: From Button: 50% opacity and no pointer events. Use it for the other buttons in the footer while one is pending.

Behavior:
- `pending` is controlled by you. Set it when the request starts and clear it when it settles, success or failure.
- While pending, clicks call `preventDefault()` and skip `onClick`, which also stops a submit button from submitting the form again.
- It sets `aria-disabled` rather than `disabled`, so the button stays focusable and keyboard focus doesn't jump to the page when the request starts.
- Every other prop goes to Button: `variant`, `size`, `type`, `render`, `className`.
- Icons inside the children fade with the label, so the spinner is the only thing visible.

Do and don't:
- Do: Keep the label and let the spinner replace it in place, so the width holds.
- Don't: Swap the label for a longer pending message. The button grows, and everything beside it moves.

Content:
- Keep the resting label; it's still there for screen readers while pending.
- Report the outcome after, not during: a toast titled Payment run scheduled, or an error that says what to do next.
- If a wait runs past a few seconds, say what is happening near the button, such as Sending to Northwind Freight.

Accessibility:
- While pending, the button has `aria-disabled="true"` and stays in the tab order, so focus isn't lost.
- The label is hidden with opacity only, so it still names the button. The spinner adds `role="status"` with the label Loading.
- A status inside a button isn't reliably announced. For waits over a second, add polite status text nearby or confirm with a toast.
- The spinner's rotation is CSS `animate-spin`; it isn't paused for reduced motion, but it is small and doesn't move across the screen.
- Enter: Activates the button. Ignored while pending.
- Space: Activates the button. Ignored while pending.

Known gaps (follow the system, not the gap):
- The spinner is 16px at every size, so it crowds `xs` and `icon-xs` buttons, where icons are 12px.
- The spinner's `role="status"` inside a button can make the accessible name read as the label followed by Loading, and announcements vary by screen reader.
- One product file uses it, the auth screens' provider buttons. Check other pending states before assuming they hold their width.

### Hold button

- Level: Molecule
- Category: Actions
- Status: Stable
- Import: `@oration/canon/components/hold-button`
- Exports: `HoldButton`
- Docs: /design/components/hold-button

Hold button confirms a destructive action by a sustained press: a solid red fill sweeps across the 10% red tint over two seconds, and the action runs only if you hold to the end. Letting go early snaps the fill back. Settings uses it to delete agents, workspaces and accounts, often behind a typed name. It replaces a second confirmation dialog, not the first; the common mistake is using it for everyday deletes that can be undone, where a toast with Undo is kinder.

When to use:
- For a delete that can't be undone: a supplier with its bank details, an agent, a workspace, an account.
- As the confirming action in a danger zone or a delete dialog, beside Cancel.
- After a typed confirmation for the most serious deletes, disabled until the name matches.

When not to use:
- For a delete that can be undone. Delete at once and offer Undo in a toast. Use /design/components/toast instead.
- For a destructive action that needs explanation and a choice first. Use /design/components/alert-dialog instead.
- For a non-destructive action. Holding is friction reserved for loss. Use /design/components/button instead.
- For an action that waits on the network after one press. Use /design/components/pending-button instead.

Rules:
- Destructive is a tint: At rest it is the 10% Signal Red tint with red text, like every destructive button. The solid red appears only as progress while held.
- The label says hold: The resting label starts with Hold to and names what goes: Hold to delete supplier. Nothing else on screen tells people to keep pressing.

Anatomy:
- Container: 32px, 10px corners, 12px side padding, the 10% red tint (20% in dark) and 14px medium red text.
- Label: The children, in red on the tint.
- Fill: A solid red layer with white text, `holdingLabel` while held. It is clipped away at rest.
- Sweep edge: The fill's leading edge, moving left to right in linear time over `duration`.

States:
- Rest: The 10% red tint with red text.
- Hover: The tint deepens to 15% over 150ms.
- Focus visible: A 3px red ring at 25%.
- Holding: `data-holding` is set; the fill sweeps across in linear time over `duration`, showing `holdingLabel`. The button scales to 0.97 when motion is allowed.
- Released early: The fill snaps back in 200ms ease-out and nothing happens.
- Confirmed: `onConfirm` runs once and the button resets. Close the dialog or replace the button with the result.
- Disabled: 50% opacity and no pointer events, for example until a typed name matches.

Behavior:
- Pressing with a pointer, or holding Enter or Space, starts a timer for `duration` (2000ms). Key repeats are ignored.
- Lifting the pointer or key, leaving the button, a pointer cancel or losing focus all cancel the hold.
- When the timer completes, `onConfirm` runs once and the hold resets. The timer is cleared on unmount.
- The fill is a `clip-path` transition, linear while holding and 200ms ease-out on release, so it always shows how far along the hold is.
- It renders a native `<button type="button">`; it never submits a form.

Do and don't:
- Do: Say Hold to in the label and name what goes, with a holding label that names the outcome.
- Don't: Label it Delete. People click, nothing happens, and they click again.

Content:
- Resting label: Hold to delete supplier, Hold to delete workspace. Verb, object, no punctuation.
- Holding label: Keep holding to delete, or the specific outcome such as Keep holding to cancel the run.
- The text around it states the loss in numbers: Removes the supplier, its bank details and 38 invoices.
- After it confirms, say what happened in a toast, and what remains: Paid remittances stay in your reports.

Accessibility:
- It is a native button named by its children. The fill and the holding label are `aria-hidden`, so screen readers hear only the resting label; it must say Hold to.
- Keyboard users hold Enter or Space for the same duration. Moving focus away cancels.
- Holding is a timing requirement. Keep `duration` at two seconds or less for most actions, and never use a hold for anything that isn't destructive.
- Progress isn't announced. Confirm the outcome with a toast or by moving focus to the result.
- The sweep is the only feedback that the hold is working, so it runs even with reduced motion; the press scale doesn't.
- Tab: Moves focus to the button.
- Enter: Hold for the duration to confirm. Releasing early cancels.
- Space: Hold for the duration to confirm. Releasing early cancels.

Known gaps (follow the system, not the gap):
- Any pointer button starts the hold, including a right-click, because `onPointerDown` doesn't check `event.button`.
- The focus ring is red at 25% while destructive Buttons use 20%, and there is no size prop: it is 32px only.
- There is no accessible hint or progress: screen reader users depend on the label saying Hold to, and nothing announces that the hold has started.
- It takes no `ref`, `id` or `aria-*` props, so it can't be described by nearby text with `aria-describedby`.

API `HoldButton`:
- `children: ReactNode`. The resting label. Start with Hold to.
- `onConfirm: () => void`. Runs once when the hold completes.
- `duration?: number` = 2000. How long to hold, in milliseconds.
- `holdingLabel?: ReactNode` = "Keep holding". Shown on the fill while held.
- `disabled?: boolean`. Dims to 50% and blocks the hold.
- `className?: string`. Merged onto the button.

### Copy button

- Level: Molecule
- Category: Actions
- Status: Stable
- Import: `@oration/canon/components/copy-button`
- Exports: `CopyButton`
- Docs: /design/components/copy-button

Copy button is a small icon button that writes a value to the clipboard and confirms with a green check for 1.6 seconds. It sits beside machine strings people paste elsewhere: signing secrets, workspace and payment IDs, forwarding addresses, join codes. It is one of the most used components in settings. The common mistake is leaving `label` at its default Copy, so a page of copy buttons all announce the same name.

When to use:
- Beside a secret, key or token that people paste into another system.
- Beside a record or run ID in a header or table row, at `icon-xs`.
- Beside a generated address or code, such as an email forwarding address or a team join code.
- Inside a tint well with the value, when you need a layout `CopyValue` doesn't give you.

When not to use:
- For a labelled read-only value in a well with its copy button. The ready-made row does it in one element. Use /design/components/copy-row instead.
- For a block of code with its own copy control. Use /design/components/code-block instead.
- For any other icon action, such as download or open. Use /design/components/icon-action instead.
- For sharing a link with people, where a labelled Copy link button is clearer. Use /design/components/button instead.

Rules:
- The Machine Mono Rule: What it copies is usually a machine string: show that value beside it in Geist Mono, so people can check what they're about to paste.
- Icon-only buttons carry a name: Set `label` to name the value: Copy signing secret, Copy INV-20418. The default Copy is only acceptable when it is the only one in view.

Anatomy:
- Button: A square ghost Button, 28px by default, with Slate Meta icons that turn ink on hover.
- Icon: A 16px copy icon that cross-fades to a Ledger Green check on copy, with a 0.3s spring that scales and blurs between them.

States:
- Rest: Transparent with a Slate Meta copy icon. Outline adds the hairline and control shadow.
- Hover: Well Gray fill and an ink icon over 150ms.
- Focus visible: Indigo border and a 3px Focus Indigo ring at 40%.
- Pressed: Scales to 0.96 while held, when motion is allowed.
- Copied: The icon swaps to a green check and the name changes to Copied for 1.6 seconds, then swaps back.

Behavior:
- On click it calls `navigator.clipboard.writeText(value)`, shows the check and calls `onCopied`.
- The check resets after 1.6 seconds. Clicking again restarts it.
- Clipboard errors are swallowed, and the check shows either way; see Known gaps.
- The icon swap uses Icon swap: both icons share one grid cell, so the button never shifts. With reduced motion, the app's motion config drops the scale and keeps the fade.
- It renders `type="button"`, so it's safe inside forms.

Do and don't:
- Do: Name each copy button after the value it copies.
- Don't: Leave `label` at its default. Every button on the page is announced as Copy.

Content:
- `label` is Copy plus the value's name: Copy signing secret, Copy forwarding address, Copy join code.
- In repeated rows, name the instance: Copy INV-20418.
- When you add a toast through `onCopied`, title it with what was copied and, if useful, where it goes next: Signing secret copied, Paste it into your webhook handler's config.

Accessibility:
- The name is `label`, and switches to Copied while the check shows. Name changes aren't reliably announced, so add a toast through `onCopied` when confirmation matters.
- There is no tooltip. Keep the value visible beside it so sighted people know what the button copies.
- Icons inside are decorative; the name comes from `aria-label`.
- `icon-xs` is 24px, the minimum target size. Use `icon-sm` on touch layouts.
- Tab: Moves focus to the button.
- Enter: Copies the value.
- Space: Copies the value.

Known gaps (follow the system, not the gap):
- It shows the check and calls `onCopied` even when the clipboard write fails or `navigator.clipboard` is missing, as on plain HTTP, so people can be told it copied when it didn't.
- There's no tooltip, unlike other icon-only buttons in the system.
- The Copied confirmation is only an `aria-label` change, with no live region.

API `CopyButton`:
- `value: string`. The text written to the clipboard.
- `label?: string` = "Copy". The accessible name. Name the value.
- `size?: "icon-xs" | "icon-sm" | "icon"` = "icon-sm". 24, 28 or 32px.
- `variant?: "ghost" | "outline"` = "ghost". Button variant.
- `onCopied?: () => void`. Called after each click, for a toast or analytics.
- `className?: string`. Merged onto the button.

### Copy row

- Level: Molecule
- Category: Actions
- Status: Stable
- Import: `@oration/canon/components/copy-row`
- Exports: `CopyRow`, `CopyValue`
- Docs: /design/components/copy-row

Copy row shows a read-only machine value with its copy button: a 12px Slate Meta label over a Well Gray well that holds the value in Geist Mono. `CopyValue` is the well alone, for lists where the name lives elsewhere, such as a key's row. SSO setup and the public keys list use them for entity IDs, ACS URLs and keys. The common mistake is a read-only Input for these values; it looks editable, and people click in and try to type.

When to use:
- For values people paste into another system during setup: an entity ID, an ACS URL, a sign-in link, a forwarding address.
- For API keys and other credentials listed by name, with `CopyValue` beside the name.
- In a sheet, dialog or settings card, stacked with other rows or fields.

When not to use:
- When the value should be editable. Use an input with a label. Use /design/components/input instead.
- For an ID inline in a header or a table cell. A bare copy button beside the text is lighter. Use /design/components/copy-button instead.
- For a multi-line snippet or a code sample. Use /design/components/code-block instead.
- For a label and value pair that isn't copied, such as a record's details. Use /design/components/meta instead.

Rules:
- The Tint Well Rule: Inside a card, the value sits in a Well Gray well at 70% with 10px corners, never a second bordered box.
- The Machine Mono Rule: The value is a string a machine produced or will parse, so it is set in Geist Mono at 12px. The label stays in Geist Sans.

Anatomy:
- Label: `CopyRow` only: 12px Slate Meta above the well, 4px gap.
- Well: Well Gray at 70% with 10px corners, 10px left and 4px right padding.
- Value: 12px Geist Mono in ink, one line, truncated with an ellipsis.
- Copy button: A 28px ghost Copy button. In `CopyRow` it is named Copy {label}.

States:
- Rest: The well, the value and a Slate Meta copy icon.
- Copy hover and focus: From Copy button: Well Gray fill on hover, the indigo focus ring.
- Copied: The icon turns into a green check for 1.6 seconds.
- Truncated: A value wider than the well ends in an ellipsis; the button copies all of it.
- Dimmed: Pass `opacity-60` to `CopyValue` for a turned-off or revoked credential, and say why beside it.

Behavior:
- Both are stateless wrappers around Copy button; the full `value` goes to the clipboard whatever is visible.
- `CopyRow`'s button is named Copy plus `label`. `CopyValue` uses its `label` as the whole name, so pass Copy Production key.
- The value is plain selectable text, so people can also select and copy part of it.
- `CopyValue` fills its container's width. Size it with `className`, such as `min-w-0 flex-1` in a row.

Do and don't:
- Do: Show copyable setup values in a well with a copy button.
- Don't: Put them in a read-only Input. It looks editable, and people try to type in it.

Content:
- Labels use the other system's term exactly, so people can match fields: Entity ID, ACS URL, not Our ID.
- Values are shown in full, never masked. If the value is a secret people shouldn't see, don't show it in a copy row.
- Say where to paste it in the text around the rows: Paste these into a new SAML app in Okta.

Accessibility:
- The copy button carries the name: Copy Entity ID in `CopyRow`, or your `label` in `CopyValue`.
- The visible label is a `<p>`, not a `<label>`; the value isn't programmatically labelled, so screen reader users hear the value and then the named button.
- Truncation is visual only; screen readers read the full value.
- Copied confirmation is a name change on the button. Add a toast through Copy button when confirmation matters.
- Tab: Moves focus to the copy button.
- Enter: Copies the value.
- Space: Copies the value.

Known gaps (follow the system, not the gap):
- The label is a `<p>` with no relationship to the value, so the value has no programmatic label.
- A truncated value can't be read in full anywhere on screen: no tooltip, no wrap option.
- `CopyRow` takes no `className`, description or `id`, so it can't carry a hint or be described by an error.
- It inherits Copy button's gaps: it confirms even when the clipboard write fails, and the button has no tooltip.

API `CopyRow`:
- `label: string`. Shown above the well and used in the button's name.
- `value: string`. The value shown and copied.

API `CopyValue`:
- `value: string`. The value shown and copied.
- `label: string`. The copy button's full accessible name, such as Copy Production key.
- `className?: string`. Merged onto the well.

### AI generate button

- Level: Molecule
- Category: AI
- Status: Stable
- Import: `@oration/canon/components/ai/ai-button`
- Exports: `AIGenerateButton`, `AIFieldAction`, `useAIGenerate`
- Docs: /design/components/ai-generate-button

AI generate button is the sparkles action that drafts text for a field. It sits beside the field's label (`AIGenerateButton`) or inside the field's corner (`AIFieldAction`), shimmers while it works, hands the text to your field and confirms with a toast that offers Undo. Every free-text field that describes something, such as an agent description, a ticket summary, a macro or a campaign message, gets one. The thing people get wrong is weight: it is a quiet ghost button that helps fill one field, never the view's filled action, and it always leaves a way back.

When to use:
- Beside the label of any descriptive textarea: agent, tool and ticket type descriptions, procedure steps, scorecard criteria, skill instructions.
- Inside the corner of a field when the label row is taken or the form is dense, with `AIFieldAction`.
- Below a field, right-aligned, for a rewrite of existing text: Rewrite from the thread.
- In a composer toolbar to draft a reply from the conversation: Draft reply.
- With `useAIGenerate` when the trigger has to look different, such as a toolbar button that adds a note.

When not to use:
- For long-form prompts. They get the full editor with its slash menu and AI rewrites. Use /design/components/prompt-editor instead.
- To rewrite, shorten or translate a selection inside text. Use /design/components/selection-actions instead.
- When the result sends, publishes or changes a record. Propose it and let someone approve. Use /design/components/approval-card instead.
- For a summary that people read rather than edit. Use /design/components/streaming-text instead.
- For short structured fields such as names, amounts, dates and IDs. Generating them adds nothing.
- When generating is the view's main action, such as building a report. Use the filled button. Use /design/components/button instead.

Rules:
- The One Filled Button Rule: Generate is an assist. It is ghost (or outline) at 24 or 28px, so the form's Save stays the one filled button.
- The Quiet Indigo Rule: The sparkles icon is Slate Meta and turns ink on hover. It is never indigo, never a gradient, and never set in a colored tile.
- AI everywhere, without noise: One generate affordance per descriptive field, placed the same way across the suite: in the label row, or in the field's corner. Every result can be undone.

Anatomy:
- Sparkles icon: 12px at `xs`, 14px at `sm`, with the inline-start padding. It pulses softly while pending when motion is allowed.
- Label: Generate by default, or a verb for the job. Replaced by Generating… in a shimmer while pending.
- Field action: `AIFieldAction`: a 24px icon-only ghost button 6px from the field's top-right (or bottom-right) corner. A pixel grid replaces the sparkles while pending.
- Reserved padding: `pr-9` on the field, so typed text never runs under the field action.
- Undo toast: After the text lands: a toast titled Draft added (or your `toastTitle`) with an Undo action when `onUndo` is set. Not drawn above.

States:
- Rest: Ghost: Slate Meta text and icon on no fill. Outline adds the hairline and control shadow.
- Hover: Ink text on Well Gray, over 150ms.
- Focus visible: An indigo border and a 3px Focus Indigo ring at 40%.
- Pressed: Scales to 0.96 while held, when motion is allowed.
- Pending: The label shimmers as Generating…, the icon pulses, `aria-busy` is set and clicks are ignored. The button stays focusable.
- Done: The field shows the draft and a toast confirms it, with Undo when `onUndo` is set.
- Failed: An error toast: Couldn't generate a draft, Nothing changed. Try again in a moment., with Try again. The field is untouched.
- Disabled: 50% opacity. Use it when there is nothing to work from, such as Improve with AI on an empty field.

Behavior:
- `onGenerate` may return a string or a promise. A string resolves after `simulateMs` (900ms by default), so demos feel like real work.
- While pending, a second click does nothing; `run` is guarded so only one request is in flight.
- On success it calls `onResult(text)`, then toasts. The toast has an Undo action only when you pass `onUndo`.
- Undo is yours to implement. Snapshot the old value in `onGenerate` (or read it from the closure) and restore it in `onUndo`.
- On failure (a thrown error or a rejected promise) it toasts the error with Try again, which runs the same request.
- If the component unmounts while pending, it skips the state update; the toast still fires.
- `tooltip` wraps the button in a tooltip, for short labels such as Describe that need a sentence of explanation.

Do and don't:
- Do: Put a ghost Generate in the label row, beside the field it fills. Save stays the one filled button.
- Don't: Make Generate with AI a filled button. It competes with Save and reads as the reason the page exists.
- Do: Pass `onUndo` so the toast offers a way back to what was there.
- Don't: Overwrite the field with no undo. Someone's own words are gone after one click.
- Do: Reserve `pr-9` on a field that holds a corner action.
- Don't: Drop the field action on a field without padding. Text runs under the icon.

Content:
- The label is a verb for what it writes: Draft reply, Improve with AI, Rewrite from the thread, Describe. Generate is fine in a label row, where the field names the object.
- The pending label repeats the verb in -ing form with one ellipsis character: Drafting…, Improving…, Rewriting…
- The toast title names the result in the past tense: Description drafted, Macro improved, Draft ready.
- The toast description says what it was written from, and asks for review when it matters: Written from the conversation and the payment record. Review before sending.
- `AIFieldAction` labels name the field: Draft a description from the title, Draft a greeting.

Accessibility:
- The button's name is its label. The field action's name is its `label` (Generate with AI by default), repeated in its tooltip.
- While pending the button uses `aria-disabled` and `aria-busy` rather than `disabled`, so focus stays on it. A hidden `role="status"` says Generating a draft.
- The field action swaps its name and tooltip to Generating a draft and Generating… while pending.
- Results arrive in a toast, which is announced politely. Undo is a real button in it.
- The shimmer and pulse stop under reduced motion; the pending words still change.
- Both sizes are at least 24px. On touch-first forms prefer `size="sm"` (28px).
- Tab: Moves to the button or the field action.
- Enter: Generates. Ignored while pending.
- Space: Generates. Ignored while pending.

Known gaps (follow the system, not the gap):
- Some screens still hand-roll the pattern: Draft with Quill buttons in the compose email dialog and the inbox reply thread, and the contact center composer's tone rewrite, which re-implements the pending state, toast and undo.
- Undo is left to each caller, so call sites snapshot the old value three different ways (closure, ref, parent callback).
- The error toast's wording is fixed (Couldn't generate a draft) even for improve and rewrite actions, and can't be changed.
- The success toast has no `type`, and the Undo toast times out like any other toast.
- While pending the button still shows its hover fill, because it is only `aria-disabled`.

API `AIGenerateButton` (extends Nothing. Only the props below are read; it renders a Button.):
- `onGenerate: () => Promise<string> | string`. Produces the text. A string resolves after `simulateMs`.
- `onResult: (text: string) => void`. Receives the text. Put it in the field.
- `onUndo?: () => void`. Adds Undo to the success toast. Restore the old value here.
- `toastTitle?: string` = "Draft added". Success toast title.
- `toastDescription?: string`. Success toast description.
- `simulateMs?: number` = 900. How long a synchronous `onGenerate` pretends to work.
- `label?: string` = "Generate". Button label.
- `pendingLabel?: string` = "Generating…". Label while pending.
- `size?: "xs" | "sm"` = "xs". 24 or 28px.
- `variant?: "ghost" | "outline"` = "ghost". Ghost in label rows, outline below a field or in a sheet footer.
- `tooltip?: React.ReactNode`. Wraps the button in a tooltip.
- `disabled?: boolean`. Disables it, e.g. when there is nothing to improve.
- `className?: string`. Merged onto the button.

API `AIFieldAction` (extends Nothing):
- `label?: string` = "Generate with AI". Accessible name and tooltip.
- `position?: "top-right" | "bottom-right"` = "top-right". Which corner of the `relative` wrapper it sits in.
- `disabled?: boolean`. Disables it.
- `className?: string`. Merged onto the button.

API `useAIGenerate`:
- `options: { onGenerate; onResult; onUndo?; toastTitle?; toastDescription?; simulateMs? }`. As for `AIGenerateButton`.
- `returns?: { pending: boolean; run: () => Promise<void> }`. Call `run` from your trigger; render from `pending`.

### Tabs

- Level: Molecule
- Category: Navigation
- Status: Stable
- Import: `@oration/canon/components/tabs`
- Exports: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
- Docs: /design/components/tabs

Tabs switch between views of the same object without leaving the page: a supplier's overview, activity and invoices, or a payment run's summary and exceptions. Canon has two looks. The default is a 32px Well Gray track with a raised white pill, for small groups inside a card, dialog or toolbar. The line variant has no track and marks the active tab with a 2px ink underline; record, agent, report and sequence pages use it, scrolling sideways with a faded edge. The common mistake is using tabs to change a setting or filter a list. Tabs pick which panel you are looking at; they never change data.

When to use:
- To split one record into views that don't need to be seen together: Overview, Activity, Invoices, Files.
- For the sticky tab bar under a record, agent, report or sequence header, as the line variant with `scrollable`.
- For two to four sibling panels inside a card, sheet or dialog, as the default track.
- When each panel is substantial enough to deserve its own heading, and switching doesn't lose work.

When not to use:
- To choose a mode or filter that changes what a single view shows, such as Day, Week and Month. Use /design/components/segmented-control instead.
- For the local navigation of a settings or master and detail page with many items and metadata. Use /design/components/side-tabs instead.
- To move between steps of a flow that must be done in order. Use /design/components/stepper instead.
- For sections a reader may want open at the same time. Use /design/components/accordion instead.
- For switching between whole pages or routes. Use links in the sidebar or a breadcrumb switcher so the URL and history stay honest. Use /design/patterns/navigation instead.

Rules:
- The Scroll Edge Rule: Clipped content shows its edge. A horizontal tab row that overflows scrolls instead of wrapping, fades the clipped side over 2rem, and keeps the selected tab in view. `scrollable` does all three.
- The Quiet Indigo Rule: The active tab is drawn in ink: a white pill on the track or a 2px Graphite Ink underline. Indigo is only its focus ring, never its fill, text or underline.

Anatomy:
- List: The `tablist`. In the default variant it is the track: 32px tall, Well Gray, 10px corners and a 3px inset. The line variant has no fill and a 4px gap between tabs.
- Tab: A button with the Control type (14px, medium) at 60% ink, 8px corners and `flex-1`, so tabs share the track evenly. Icons are 16px.
- Active tab: Full ink. On the track it is a raised White Plane pill with a small shadow; in the line variant a 2px ink underline fades in beneath it.
- Count: Optional. A 12px Slate Meta figure in tabular numerals after the label, written inline in the trigger.
- Panel: The `tabpanel` for the selected tab. Hidden panels unmount unless `keepMounted` is set.

States:
- Rest: Label at 60% ink (Slate Meta in dark) on the track or plane.
- Hover: The label goes to full ink over 150ms. The track and underline don't change.
- Focus visible: An indigo border, a 3px ring at 50% and a 1px indigo outline. In a `scrollable` list the ring is inset so the scroller doesn't clip it.
- Selected: Full ink. The track variant raises a White Plane pill with a small shadow (a 1px input border and 30% input fill in dark). The line variant fades in a 2px ink underline.
- Disabled: 50% opacity and no pointer events. It stays in arrow-key order but can't be selected. Say why it's unavailable in the panel or beside the list.
- Overflowing: With `scrollable`, a 2rem fade on whichever edge is clipped: the end only at the start, both in the middle, the start only at the end.

Behavior:
- Built on Base UI Tabs. Uncontrolled with `defaultValue`, or controlled with `value` and `onValueChange`. Base UI's own `defaultValue` is `0`, so tabs with string values must pass one or nothing starts selected.
- Click, Enter or Space selects a tab. Arrow keys only move focus unless `activateOnFocus` is set on the list, and they wrap at the ends (`loopFocus`).
- Hidden panels unmount by default, so a draft typed into one is lost when you switch. Lift that state up or pass `keepMounted` to the `TabsContent`.
- `scrollable` makes the list scroll sideways with a hidden scrollbar, fades the clipped edge over 2rem, and scrolls the selected tab into view with a 24px margin: instantly on mount, smoothly on change, and instantly again under reduced motion.
- `orientation="vertical"` on `Tabs` puts the list beside the panel. Tabs fill the list width and left-align, the line underline becomes a 2px bar on the right edge, and Up and Down replace Left and Right.
- Label color and the active fill transition over 150ms; the line underline fades rather than slides.
- For a record tab bar that sticks under the header, wrap the list in a `sticky top-0 z-10 border-b border-border bg-background` div, as record pages do, and keep the panels outside it.

Do and don't:
- Do: Switch the range or mode of a single view with a segmented control, and keep tabs for separate panels.
- Don't: Use tabs for Day, Week and Month. No panel changes; the same chart re-filters, which is a segmented control's job.
- Do: Let a long row of record tabs scroll with `scrollable` so the clipped edge fades and the selected tab stays in view.
- Don't: Let tabs wrap onto a second line. Two rows of tabs read as two groups, and the active underline loses its baseline.
- Do: Keep labels to one or two nouns, and put a count after the label in Slate Meta.
- Don't: Write sentences, verbs or counts in brackets. Tab labels are names of places, not actions.

Content:
- Nouns, sentence case, one or two words: Overview, Buying committee, Remittances.
- Counts follow the label as a plain 12px figure: Invoices 38, not Invoices (38).
- Keep the same tab names and order across every record of a type, so muscle memory carries over from one supplier to the next.
- Don't repeat the object in each label: on a supplier record it's Invoices, not Supplier invoices.

Accessibility:
- Base UI renders `role="tablist"`, `role="tab"` with `aria-selected` and `aria-controls`, and `role="tabpanel"` with `aria-labelledby`, so each panel is named by its tab.
- Roving focus: only the selected tab is in the tab order; arrow keys move between the others.
- Icon-only tabs are not allowed. Every tab needs visible text, and icons are `aria-hidden`.
- A count read on its own is ambiguous. Keep it inside the trigger so it is announced with the label, as in Invoices 38.
- The open panel is focusable (`tabIndex` 0), so keyboard users can reach content that has no controls of its own.
- Motion is color and opacity only, and the scroll-into-view jump is instant under reduced motion.
- Tab: Moves focus to the selected tab, then on into the open panel.
- ← + →: Moves focus to the previous or next tab, wrapping at the ends. Up and Down in a vertical list.
- Home: Moves focus to the first tab.
- End: Moves focus to the last tab.
- Enter: Selects the focused tab and shows its panel.
- Space: Selects the focused tab and shows its panel.

Known gaps (follow the system, not the gap):
- `TabsContent` sets `outline-none`, but Base UI makes the open panel focusable, so tabbing from the list into a panel draws no focus indicator. Until that changes, add a `focus-visible` ring to panels that have no controls of their own.
- `scrollable` removes the track's 3px inset and stretches tabs to full height, so it only suits the line variant. The tool action editor needs a scrolling default track and hand-rolls `overflow-x-auto` on it instead, without the edge fade.
- There is no count slot. Every record tab bar repeats a hand-styled `text-xs text-muted-foreground tabular-nums` span inside its triggers, with small drifts in weight between pages.
- The Agents reports index renders a `Tabs` root with a list and no panels, and switches the content outside it. Tabs that control no `tabpanel` are a view switch, which is the Segmented control's job.

API `Tabs` (extends Base UI `Tabs.Root` (`<div>`)):
- `defaultValue?: Tabs.Tab.Value` = 0. The initially selected tab when uncontrolled. Pass it whenever tab values are strings.
- `value?: Tabs.Tab.Value`. The selected tab when controlled.
- `onValueChange?: (value: Tabs.Tab.Value, eventDetails) => void`. Called when a tab is selected.
- `orientation?: "horizontal" | "vertical"` = "horizontal". Stacks the list above the panel, or puts it beside the panel with Up and Down arrow keys.
- `className?: string`. Merged after the defaults (`flex gap-2`, and `flex-col` when horizontal). Record pages pass `gap-0`.

API `TabsList` (extends Base UI `Tabs.List` (`<div>`)):
- `variant?: "default" | "line"` = "default". `default` is the Well Gray track with a raised pill. `line` has no track and a 2px ink underline.
- `scrollable?: boolean` = false. Scrolls sideways instead of overflowing, fades the clipped edge over 2rem and keeps the selected tab in view.
- `activateOnFocus?: boolean` = false. Selects a tab as soon as arrow keys focus it, instead of on Enter or Space.
- `loopFocus?: boolean` = true. Wraps arrow-key focus from the last tab to the first.
- `className?: string`. Merged last. Record tab bars pass a height (`h-9` or `h-10`) and a gap.

API `TabsTrigger` (extends Base UI `Tabs.Tab` (`<button>`)):
- `value: Tabs.Tab.Value`. Matches the `value` of its `TabsContent`.
- `disabled?: boolean` = false. Dims the tab to 50% and prevents selecting it.
- `className?: string`. Merged last. Line tabs on record pages pass `px-0` so labels sit on the page gutter.

API `TabsContent` (extends Base UI `Tabs.Panel` (`<div>`)):
- `value: Tabs.Tab.Value`. The tab this panel belongs to.
- `keepMounted?: boolean` = false. Keeps the panel in the DOM while hidden, so local state survives a switch.
- `className?: string`. Merged after `flex-1 text-sm outline-none`.

### Side tabs

- Level: Molecule
- Category: Navigation
- Status: Beta
- Import: `@oration/canon/components/side-tabs`
- Exports: `SideTabs`, `sideTabId`
- Docs: /design/components/side-tabs

Side tabs are the vertical list on master and detail settings pages: roles, objects, queues, dispositions and ticket types. Each item names one sibling, with an optional icon, a line of meta such as 9 members and a trailing tag, and the panel beside it shows the selected one. Below 1280px the list wraps into a horizontal strip above the panel. The part people get wrong is the panel: Side tabs render only the tab list, so you render one `role="tabpanel"` yourself and label it with `sideTabId`.

When to use:
- For a settings page that edits one of several siblings of the same kind: Roles, Queues, Disposition sets, Ticket types.
- When each item benefits from a second line of meta, such as a member or record count.
- For three to about fifteen items that fit without scrolling. Longer lists need search, which is a combobox or a table.
- Beside a panel that is long enough to justify keeping the list in view while you edit.

When not to use:
- For two to six views of one record, such as Overview and Activity. Use /design/components/tabs instead.
- For the app's own navigation between pages and sections. Use /design/components/sidebar instead.
- For choosing one option in a form that is saved with the rest of it. Use /design/components/radio-group instead.
- For a long, searchable list of siblings, such as every supplier. Use /design/components/data-grid instead.

Rules:
- The Thirteen-Fourteen Rule: Labels are Body Dense at 13px and meta is 12px in tabular figures. The selected label turns medium weight without shifting its neighbours, because an invisible bold copy reserves its width.
- The Option Hue Rule: A trailing tag carries a real option value such as Custom or System. Don't use tag hues to color-code the items themselves.

Anatomy:
- Tab list: A `tablist` named by `label`. Vertical with 1px gaps from 1280px; below that it wraps into a strip with 4px gaps.
- Icon: Optional, 16px, Slate Meta at rest and ink when selected. Always decorative.
- Label: 13px, one line, truncated. Medium weight when selected, with the width reserved so nothing jumps.
- Meta: Optional 12px Slate Meta line under the label in tabular figures, such as 9 members.
- Badge: Optional trailing node, usually a Tag such as Custom.
- Selected fill: Menu Hover (`--accent`) on a 10px-corner item at least 32px tall.

States:
- Rest: No fill. Label in ink, icon and meta in Slate Meta.
- Hover: One highlight at 60% Menu Hover glides to the item under the pointer on the fast spring. It fades in at the first item you enter rather than sliding from where it last was.
- Focus visible: A 3px Focus Indigo ring at 40% around the item.
- Selected: Full Menu Hover fill, medium-weight label and an ink icon. `aria-selected` is true and the item is the one tab stop.
- Disabled: 50% opacity, not clickable, and skipped by arrow keys. Use the meta line to say why.

Behavior:
- Controlled only: pass `value` and update it in `onValueChange`. There is no internal state.
- Selection follows focus. Arrow keys, Home and End select the next item immediately and move focus to it, wrapping at the ends and skipping disabled items.
- Down and Right both move forward and Up and Left both move back, so the same keys work in the vertical list and the wrapped strip.
- `orientation="responsive"` (the default) is a wrapping strip below 1280px and a vertical list from 1280px. Pin it with `"vertical"` or `"horizontal"` when the container, not the viewport, decides.
- Render one panel beside the list with `role="tabpanel"`, `id={panelId}` and `aria-labelledby={sideTabId(value)}`, and swap its content by the selected id.
- Item ids become DOM ids through `sideTabId(id)`, so they must be unique on the page. Prefix them when two lists could share an id.
- Settings pages lay the list and panel out as `grid gap-6 xl:grid-cols-[12rem_minmax(0,1fr)]`, so the strip sits above the panel until the list moves beside it.
- Under reduced motion the hover highlight fades between items instead of sliding.

Do and don't:
- Do: Put the count on the meta line in Slate Meta, and keep the label to the item's name.
- Don't: Pack the count and the kind into the label. It truncates first, and the list stops scanning as names.
- Do: Use side tabs when the page edits one of many siblings, such as roles or queues, and the panel is long.
- Don't: Use side tabs for two or three views of one record. That is Tabs, above the content, where record pages keep them.
- Do: Label the panel with `aria-labelledby={sideTabId(value)}` so it is announced with the selected item's name.
- Don't: Render the panel as an unlabelled div. Screen reader users hear a change of content with no name for it.

Content:
- Labels are the item's own name in sentence case: AP clerk, Short pay dispute, Priority suppliers.
- Meta is one short fact that helps choose, with its unit: 9 members, 14 attributes, 3 queues.
- Badges are tags with one word: Custom, System, Default. Never a sentence.
- The list's `label` names the set in the plural: Roles, Ticket types.

Accessibility:
- The list is a `tablist` named by `label`. Each item is a `tab` with `aria-selected`, `aria-controls={panelId}` and an id from `sideTabId`.
- Roving tab stop: only the selected item has `tabIndex` 0. If `value` matches no enabled item, nothing is reachable with Tab, so always select one.
- Icons are `aria-hidden`; the label, meta and badge are all read as the tab's name, so keep them short.
- Items are at least 32px tall, above the 24px minimum target.
- The hover highlight is decorative and `aria-hidden`.
- Tab: Moves focus to the selected item, then on into the panel.
- ↓ + →: Selects and focuses the next enabled item, wrapping at the end.
- ↑ + ←: Selects and focuses the previous enabled item, wrapping at the start.
- Home: Selects the first enabled item.
- End: Selects the last enabled item.

Known gaps (follow the system, not the gap):
- `sideTabId` returns `side-tab-` plus the item id, with no per-instance prefix, so two lists on one page that share an item id produce duplicate DOM ids and a panel labelled by the wrong tab.
- When `value` matches no enabled item, every tab gets `tabIndex` -1 and the list can't be reached with Tab. The roles settings page passes `selected?.id ?? ""`, which hits this when no role is selected.
- In `responsive` mode the list reports `aria-orientation="vertical"` even while it is laid out as a horizontal strip below 1280px.
- Items use 10px corners. DESIGN.md gives view tabs and nav items the 8px small corner.
- Side tabs have no disabled reason, no count slot separate from meta, and no search. Long sibling lists fall back to hand-built tables.

API `SideTabs` (extends Nothing. Only the props below are accepted.):
- `label: string`. The accessible name of the tab list, such as Roles.
- `items: { id: string; label: ReactNode; meta?: ReactNode; badge?: ReactNode; icon?: ReactNode; disabled?: boolean }[]`. The items, in order. `id` must be unique on the page because it becomes a DOM id.
- `value: string`. The id of the selected item.
- `onValueChange: (id: string) => void`. Called on click and on every arrow, Home and End move.
- `panelId: string`. The id of the panel the tabs control. Every tab points at it with `aria-controls`.
- `orientation?: "responsive" | "vertical" | "horizontal"` = "responsive". `responsive` wraps into a strip below 1280px and stacks from 1280px. The others pin one layout.
- `className?: string`. Merged onto the list.

### Breadcrumb

- Level: Molecule
- Category: Navigation
- Status: Beta
- Import: `@oration/canon/components/breadcrumb`
- Exports: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`
- Docs: /design/components/breadcrumb

Breadcrumbs show where a page sits: Companies, then Northwind Freight. In Oration they live in one place, the 48px app header, set in 13px Body Dense with the current crumb in ink at medium weight. On detail pages the last crumb is a sibling switcher: its label opens a searchable list of the other companies, deals or agents, so you can move sideways without going back to the index. The mistake to avoid is treating breadcrumbs as the page title. The header's crumbs are wayfinding; the page still has one h1.

When to use:
- In the app header of every workspace page, from the app or section down to the current record.
- On detail pages, with a sibling switcher on the last crumb so people can jump to the next deal or company.
- When the path has two to four levels that each have a page of their own.

When not to use:
- As the only heading of a page. Pages still render one h1, visibly or as screen reader text through the header's `heading`. Use /design/components/page-title instead.
- For moving between views of the same record. Use /design/components/tabs instead.
- For steps of a flow, where order matters and later steps aren't reachable yet. Use /design/components/stepper instead.
- For primary navigation between apps and sections. Use /design/components/sidebar instead.

Rules:
- The Thirteen-Fourteen Rule: Breadcrumbs are dense UI: 13px Body Dense, parents in Slate Meta, the current crumb in ink at medium weight. The primitive defaults to 14px and normal weight, so the header passes `text-13` and `font-medium`.
- One h1 per page: The header's crumbs are navigation, not a heading. Dense list pages that show no visible title pass `heading` so the header renders the h1 as screen reader text.

Anatomy:
- Breadcrumb list: A `nav` with an ordered list. In the header it doesn't wrap: parents keep their width and the last crumb truncates.
- Link: A parent level in Slate Meta that turns ink on hover, rendered through `render={<Link href />}`. An optional 14px icon sits 6px before it.
- Separator: A 14px chevron in its own hidden list item, with 6px on each side.
- Current page: The last crumb, in ink at medium weight, marked `aria-current="page"`. On detail pages it is the switcher button.
- Switcher chevron: A 14px up-down chevron in Slate Meta after the current label. It opens a 20rem popover with a search field and the sibling list.

States:
- Link rest: Slate Meta text.
- Link hover: Ink, over the 150ms color transition.
- Link focus visible: The global link ring: a 2px Focus Indigo outline at a 2px offset with 6px corners.
- Current page: Ink at medium weight, not interactive, `aria-current="page"`.
- Switcher hover: The 28px trigger fills Menu Hover behind the label and chevron.
- Switcher open: The Menu Hover fill stays while the popover is open (`data-popup-open`).
- Switcher focus visible: A 2px Focus Indigo ring at 50% around the trigger.
- Truncated: A long current label truncates with an ellipsis; parent crumbs never shrink.

Behavior:
- `BreadcrumbLink` renders an anchor, or any element through `render`. In the app always pass `render={<Link href="…" />}` so navigation stays client-side.
- The app header renders crumbs from data: `AppHeader({ crumbs: { label, href?, icon?, render?, switcher? }[] })` in `apps/web/src/components/shell/page-header.tsx`. Parents with an `href` become links; the last crumb, or any without an `href`, becomes the page.
- `switcher` on the last crumb takes a preset (`"companies"`, `"deals"`, `"people"`, `"lists"`, `"tables"`, `"meetings"`, `"sequences"`, `"workflows"`, `"agents"`) or `{ items, label?, searchPlaceholder?, currentId? }`. Items are `{ id, label, href, icon?, description? }`.
- The switcher is a Popover aligned to the crumb's start, 6px below it and 20rem wide. Opening moves focus to its search field; typing filters, Up and Down move the highlight, Enter opens that sibling and Escape closes and returns focus to the crumb.
- The current sibling is checked and set in medium weight. A highlight glides between rows under the pointer, the list scrolls inside a 20rem cap with a 16px fade on the clipped edge, and an empty search says No matches.
- Preset lists load lazily the first time the pointer or focus reaches the crumb, so the popover opens with its list ready.
- When a crumb is already a control, such as an editable record name passed through `render`, the switcher renders as a 24px chevron-only button beside it, labelled Switch deal.
- Under 768px the switcher trigger grows to 32px and its rows to 40px for touch.

Do and don't:
- Do: Keep parents short and let only the last crumb truncate, so the path is always readable.
- Don't: Let the crumb list wrap onto a second line in a 48px header. The header grows, and the path reads as two rows.
- Do: Give detail pages a sibling switcher on the last crumb, with the current item checked.
- Don't: Make people go back to the index to reach the next record. Every detail page in every app passes a switcher.
- Do: Name each level the way the sidebar names it: Companies, then the record's own name.
- Don't: Repeat the section in the record crumb or add the record type: Companies, then Company: Northwind Freight.

Content:
- Each crumb is the destination page's own name, in sentence case, matching the sidebar and the page title.
- Records are named by their display name, never their ID. Use the mono ID in the page body if it matters.
- Switcher descriptions are one short fact: the stage and amount, the owner, or the last activity.
- Search placeholders name the noun: Find a company…, Find a deal….

Accessibility:
- `Breadcrumb` is a `nav` with `aria-label="breadcrumb"`, and `BreadcrumbList` is an ordered list, so the path is announced as a list of levels.
- Separators and the ellipsis are `aria-hidden`; screen readers hear only the crumbs.
- The current crumb carries `aria-current="page"`. The switcher trigger keeps it and adds screen reader text such as , switch company, so its purpose is announced.
- The switcher's search field is a combobox with `aria-activedescendant`, and each row is an option. The current row adds , current after its name.
- Links use the global focus ring. The switcher uses a 2px ring at 50%.
- Hit areas: links are text-height in a 48px bar, and the switcher is 28px tall (32px under 768px).
- Tab: Moves through the parent links and the switcher.
- Enter: Follows a link or opens the switcher.
- ↑ + ↓: In the switcher, moves the highlight through the siblings.
- Enter: In the switcher, opens the highlighted sibling.
- Esc: Closes the switcher and returns focus to the crumb.

Known gaps (follow the system, not the gap):
- `BreadcrumbList` defaults to `text-sm` (14px) and `BreadcrumbPage` to `font-normal`. DESIGN.md sets breadcrumbs at 13px with the current crumb in medium weight, so every use has to override both, as the app header does.
- `BreadcrumbPage` renders `role="link"` with `aria-disabled="true"`, so screen readers announce the current page as a disabled link. `aria-current="page"` on a plain span says the same thing without the fake role.
- `BreadcrumbEllipsis` is `aria-hidden`, so its screen reader text More is never read, and it is a span rather than a button. Collapsed paths need a labelled menu trigger around it.
- The sibling switcher lives in `apps/web/src/components/shell/breadcrumb-switcher.tsx`, not in `packages/canon`. It is only reachable through `AppHeader`'s `Crumb.switcher`, and its trigger uses a 2px focus ring where other controls use 3px.
- The landmark name is the lowercase `breadcrumb`, against sentence case everywhere else.

API `Breadcrumb` (extends `<nav>`):
- `aria-label?: string` = "breadcrumb". The landmark's name. Override it when a page has two.
- `className?: string`. The header passes `min-w-0` so the list can truncate.

API `BreadcrumbList` (extends `<ol>`):
- `className?: string`. Merged after `flex flex-wrap items-center gap-1.5 text-sm text-muted-foreground`. The header passes `flex-nowrap text-13`.

API `BreadcrumbItem` (extends `<li>`):
- `className?: string`. The header passes `shrink-0` to parents and `min-w-0` to the last item.

API `BreadcrumbLink` (extends `<a>` through Base UI `useRender`):
- `render?: ReactElement | (props, state) => ReactElement`. Render a Next `Link` instead of a plain anchor.
- `href?: string`. The destination, when not using `render`.
- `className?: string`. Merged after `transition-colors hover:text-foreground`.

API `BreadcrumbPage` (extends `<span>`):
- `className?: string`. Merged after `font-normal text-foreground`. Pass `font-medium` to match the header.

API `BreadcrumbSeparator` (extends `<li>`):
- `children?: ReactNode` = <ChevronRightIcon />. Replaces the chevron. Canon uses the default.

API `BreadcrumbEllipsis` (extends `<span>`):
- `className?: string`. Merged last.

### Pagination

- Level: Molecule
- Category: Navigation
- Status: Experimental
- Import: `@oration/canon/components/pagination`
- Exports: `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationNext`, `PaginationPrevious`, `PaginationEllipsis`
- Docs: /design/components/pagination

Pagination is a row of page links for a long, stable result set where position matters: page 4 of the remittance archive should be page 4 tomorrow. Every page is a real link, so it can be bookmarked, shared and opened in a new tab. Oration's grids scroll instead, and the few paged lists use a compact footer of a range, two chevrons and Page 1 of 9. Reach for Pagination only when people need to jump to a specific page; the common mistake is using it where a scrolling grid or a filter would get them there faster.

When to use:
- For archives and exports people browse by position: remittance history, audit logs, import results.
- When the page belongs in the URL, so a link to page 4 of a filtered list can be shared.
- When the total is known and stable while someone is paging.

When not to use:
- For records people work through. Grids scroll, with sticky headers and a totals footer. Use /design/components/data-grid instead.
- To find a specific record in a long list. Search or filter narrows faster than paging. Use /design/components/search-field instead.
- For a small table inside a card or settings section. Show the rows, or a View all link. Use /design/components/card-table instead.
- For moving through the steps of a flow. Use /design/components/stepper instead.

Rules:
- The One Filled Button Rule: The current page is an outline button and every other page is ghost. Pagination never takes the view's filled indigo button.
- The Tabular Figures Rule: Ranges and totals beside pagination, such as 26–50 of 212, are set in 12px tabular figures so they don't jitter as you page.

Anatomy:
- Navigation: A `nav` named pagination, centered, holding a list with 2px gaps.
- Previous: A 32px ghost link with a chevron and the word Previous, which hides below 640px.
- Page link: A 32px square ghost link with the page number.
- Current page: The same square as an outline button with the control shadow, marked `aria-current="page"`.
- Ellipsis: A 32px decorative gap for skipped pages.
- Next: The mirror of Previous, with the chevron after the word.

States:
- Rest: Ghost: no fill, ink text.
- Hover: Well Gray fill over 150ms, from Button's ghost variant.
- Focus visible: An indigo border and a 3px Focus Indigo ring at 40%.
- Pressed: Scales to 0.96 while held, when motion is allowed.
- Current: Outline variant: White Plane, hairline border and control shadow, with `aria-current="page"` and `data-active`.
- Unavailable: There is no disabled prop. On the first or last page, drop the `href`, set `aria-disabled` and dim Previous or Next yourself.

Behavior:
- Every item is an anchor styled by Button, so it keeps link semantics: Enter follows it, ⌘-click opens a new tab and the browser shows the URL on hover.
- Put the page in the URL (`?page=4`). For client-side paging, keep the real `href` and call `event.preventDefault()` in `onClick` before updating state, so middle-click still works.
- `PaginationLink` has no `render` prop, so it can't render a Next `Link`. Without an `onClick` handler, a page change is a full navigation.
- Show at most seven slots: first, last, the current page with one neighbour each side, and ellipses for the gaps.
- `PaginationPrevious` and `PaginationNext` hide their words below 640px and keep their `aria-label`, so on phones they become 32px chevron buttons.
- After a page change, move focus to the top of the results or announce the new range, so keyboard users aren't left at the bottom of a list that just changed.

Do and don't:
- Do: Keep the window short: first, last, the current page and its neighbours, with an ellipsis for the gaps.
- Don't: Render every page number. Twenty links wrap, and none of them tells you where you are.
- Do: Pair a paged list with its range in 12px tabular figures: 26–50 of 212.
- Don't: Show page numbers with no total, so people can't tell how much is left.

Content:
- Previous and Next stay as single words. Don't write Previous page or Older.
- Ranges use an en dash and of: 26–50 of 212. Say Page 2 of 9 only in compact footers without page links.
- Name the unit when the range stands alone: 26–50 of 212 invoices.

Accessibility:
- The `nav` is named pagination. Name it more specifically, such as Remittance pages, when a page has more than one.
- The current page has `aria-current="page"`, so screen readers announce it as the current link.
- Previous and Next are named Go to previous page and Go to next page, which still contains their visible words.
- The ellipsis is `aria-hidden`. Its More pages text is never read, which is fine because it isn't interactive.
- Links are 32px squares, above the 24px minimum target.
- An unavailable Previous or Next needs `aria-disabled="true"` and no `href`, or it remains a working link to the same page.
- Tab: Moves through Previous, the pages and Next.
- Enter: Follows the focused link.

Known gaps (follow the system, not the gap):
- Pagination isn't used anywhere in the product yet. The conversation history and campaign contacts lists hand-roll a compact footer instead: a 12px range, `icon-xs` chevron buttons and Page 1 of 9. Either adopt the component there or add that compact variant to it.
- There is no disabled state. On the first or last page, `PaginationPrevious` and `PaginationNext` stay live links unless you remove the `href` and style them yourself.
- `PaginationLink` spreads its props onto a plain `<a>` and has no `render`, so it can't use Next's `Link` for client-side navigation.
- `Pagination` sets `role="navigation"` on a `nav`, which is redundant, and names it with the lowercase `pagination`.
- `PaginationEllipsis` hides its screen reader text with `aria-hidden` on the parent, so More pages is dead markup.

API `Pagination` (extends `<nav>`):
- `aria-label?: string` = "pagination". Override it when the page has more than one.
- `className?: string`. Merged after `mx-auto flex w-full justify-center`.

API `PaginationContent` (extends `<ul>`):
- `className?: string`. Merged after `flex items-center gap-0.5`.

API `PaginationItem` (extends `<li>`):

API `PaginationLink` (extends `<a>`):
- `isActive?: boolean` = false. Marks the current page: outline variant, `aria-current="page"` and `data-active`.
- `size?: Button["size"]` = "icon". Any Button size. `icon-sm` for dense footers.
- `href?: string`. The page's URL. Always set it.
- `className?: string`. Passed to Button, merged after its variant classes.

API `PaginationPrevious` (extends `PaginationLink`):
- `text?: string` = "Previous". The visible word, hidden below 640px.

API `PaginationNext` (extends `PaginationLink`):
- `text?: string` = "Next". The visible word, hidden below 640px.

API `PaginationEllipsis` (extends `<span>`):
- `className?: string`. Merged last.

### Stepper

- Level: Molecule
- Category: Navigation
- Status: Beta
- Import: `@oration/canon/components/stepper`
- Exports: `Stepper`, `Step`
- Docs: /design/components/stepper

Stepper is the stage track: one 4px segment per stage with 4px gaps, so you can see how far a deal, an import or a setup has come. Completed stages are Ink 25 with a check, the current one is Ink 80 with a medium label, and upcoming stages are Well Gray. It is drawn in ink, not indigo, because position is a magnitude, not a decision. When the stage can be changed, pass `onStepSelect` and every segment becomes a button. The mistake is making it clickable when moving isn't allowed: a segment that looks pressable and does nothing is worse than a static track.

When to use:
- For a deal's pipeline stage on its record page, with segments that move the deal when clicked.
- For the steps of an import, a campaign setup or onboarding, so people see where they are and how much is left.
- For three to seven ordered stages with short labels.

When not to use:
- For a percentage of a known task, such as an upload. Use /design/components/progress instead.
- For switching between views that have no order. Use /design/components/tabs instead.
- For a list of tasks an agent is working through, each with its own state. Use /design/components/task-list instead.
- For a multi-step dialog whose pages stack like cards. Use /design/components/stacked-dialog instead.
- To show a stage value in a table cell. Stages in rows are tags. Use /design/components/tag instead.

Rules:
- The Ink Fill Rule: The stage track is a magnitude, drawn in ink steps on a Well Gray track: Ink 25 for done, Ink 80 for current. It is never indigo, and it turns semantic only when the value is a verdict, which a stage never is.
- The Label-Beside-Color Rule: Segment shade alone doesn't say which stage is current. The current label is always visible, in ink at medium weight, and completed labels carry a check.

Anatomy:
- Track: An ordered list named by `label`, one equal-width item per stage with 4px gaps.
- Completed segment: A 4px round-ended bar in Ink 25. Its label is Slate Meta with a 12px check.
- Current segment: Ink 80. The list item carries `aria-current="step"`.
- Current label: 12px, medium weight, ink. The only label shown below 640px.
- Upcoming segment: Well Gray with a Slate Meta label.

States:
- Completed: Ink 25 segment, check icon, Slate Meta label, and (complete) for screen readers.
- Current: Ink 80 segment and a medium ink label, with (current stage) for screen readers.
- Upcoming: Well Gray segment and a Slate Meta label.
- Hover: Only when clickable: a completed or upcoming segment deepens to Ink 45. The current segment doesn't change.
- Focus visible: Only when clickable: a 3px Focus Indigo ring at 40% around the segment and its label.
- Changing: Segment colors cross-fade over 200ms when `current` moves.

Behavior:
- Stages before `current` read as complete, `current` as current, and the rest as upcoming. The component has no other states: no skipped, failed or lost stage.
- If `current` isn't in `steps`, every stage reads as upcoming and none is marked current. Deal records draw Closed lost as a separate notice instead of the track.
- Without `onStepSelect` each stage is a plain block. With it, each stage is a 32px-tall button that calls `onStepSelect(id)`, including the current one.
- The handler can't disable individual stages. To allow only going back, as the import flow does, ignore forward ids in the handler, and consider leaving the track static so forward stages don't look pressable.
- Labels truncate to their segment's width. Below 640px only the current label shows, the last stage's label aligns right, and the others stay available to screen readers.
- Pair a clickable track with an explicit next action, as deal records do: the exit criterion to check off and a Move to Negotiation button beside it.

Do and don't:
- Do: Draw stages in ink steps and let the current label carry the meaning.
- Don't: Fill the track in indigo or in stage hues. Position is a magnitude, and the indigo belongs to the view's one action.
- Do: Keep stage labels to one or two words so each fits its segment.
- Don't: Write sentences as labels. They truncate at every width and the track stops being scannable.

Content:
- Stage names are nouns in sentence case and match the pipeline's own stage options: Discovery, Proposal, Closed won.
- Flow steps start with a verb: Upload, Map columns, Review, Import.
- Name the track for what it measures: Deal stage, Import progress, Setup progress.

Accessibility:
- The track is an ordered list named by `label`, so screen readers announce it as, for example, Deal stage, list, 5 items.
- Each stage adds (complete) or (current stage) as screen reader text, and the current list item has `aria-current="step"`.
- Segments are `aria-hidden`; only the labels are read. Hidden labels below 640px stay in the accessibility tree.
- Clickable stages are native buttons at least 32px tall. They don't announce that clicking changes the stage, so say so nearby, such as in a Move to button.
- The only motion is a 200ms color change.
- Tab: Moves through the stages when they are clickable.
- Enter: Selects the focused stage.
- Space: Selects the focused stage.

Known gaps (follow the system, not the gap):
- `onStepSelect` is all or nothing. The import flow passes a handler that ignores forward stages, so Review and Import hover and focus like buttons but do nothing when clicked.
- The screen reader suffix is always (current stage), which reads oddly on flow steps such as Map columns (current stage). There is no prop to change it.
- There are no skipped, failed or lost stages. A deal that closes lost can't be drawn on the track at all.
- `aria-current="step"` sits on the list item, not on the button, so it isn't announced when a clickable stage takes focus. The screen reader suffix covers it.

API `Stepper` (extends Nothing. Only the props below are accepted.):
- `steps: Step[]`. The stages in order.
- `current: string`. The id of the current stage. Earlier stages read as complete.
- `label: string`. The accessible name of the track, such as Deal stage.
- `onStepSelect?: (id: string) => void`. Makes every stage a button and is called with its id on click.
- `className?: string`. Merged onto the list.

### Tooltip

- Level: Molecule
- Category: Overlays
- Status: Stable
- Import: `@oration/canon/components/tooltip`
- Exports: `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`
- Docs: /design/components/tooltip

A tooltip is a short Graphite Ink label that names an icon button or explains a control when you hover or focus it. It waits 400ms before the first one appears, then opens instantly as you move along a toolbar, so scanning a row of icons is quick. Keyboard shortcuts ride along as keys after the label. What people get wrong is putting information in it that someone needs: tooltips never open on touch, disappear on the next move, and aren't the accessible name. If it has to be read, it belongs on the page or in an info tip.

When to use:
- On every icon-only button, repeating its `aria-label`: Download remittance, Copy link.
- To show a control's keyboard shortcut: Next invoice with J.
- To explain why a control is unavailable, on a trigger that stays focusable.
- To show the full text of a truncated label in a dense row.

When not to use:
- For a definition or explanation someone might need to read twice, or with a link or video. Use /design/components/info-tip instead.
- For anything interactive, such as a button or a form field. Use /design/components/popover instead.
- For a preview of a record behind a link. Use /design/components/hover-card instead.
- For errors or validation. Put the message beside the field. Use /design/components/field instead.
- On a button whose visible label already says the same thing. Use /design/components/button instead.

Rules:
- Icon-only buttons carry a name: Every icon-only button has an `aria-label` that names the action and a tooltip with the same words. The tooltip is for sighted pointer and keyboard users; the label is for everyone.
- The Machine Mono Rule: Shortcut keys in a tooltip are Kbd chips in Geist Sans, never mono: ⌘ and ↵, not a code span.

Anatomy:
- Trigger: The control the tooltip describes, usually an icon button rendered through `render`.
- Container: Graphite Ink fill, 8px corners, 6px by 12px padding, up to 20rem wide, 4px from the trigger.
- Label: 12px Caption text in the plane color, one short phrase.
- Shortcut: Optional Kbd chips, tinted to 20% of the plane color. The container's right padding tightens to 6px around them.
- Arrow: A 10px rotated square that points at the trigger.

States:
- Closed: Nothing rendered.
- Opening: After 400ms of hover it fades in from a 95% scale and slides 8px from the trigger side, over 125ms on the house ease-out.
- Instant: Opened by keyboard focus, or by moving to an adjacent trigger within 400ms of the last tooltip closing: no delay and no animation (`data-instant`).
- Open: Stays while the pointer is on the trigger or the tooltip.
- Closing: Fades and scales back to 95% over 125ms when the pointer leaves, the trigger is clicked, or Escape is pressed.
- Disabled: `disabled` on `Tooltip` or `TooltipTrigger` stops it opening. A natively disabled button gets no pointer events, so its tooltip never opens either.

Behavior:
- The delay comes from `TooltipProvider`. The root layout wraps the app in `<TooltipProvider delay={400}>`; the component's own default is 0, so a nested provider without a `delay` opens tooltips instantly.
- Tooltips under one provider are grouped. Once one has shown, the next opens immediately with no animation, until 400ms (`timeout`) after the last one closed.
- Keyboard focus opens the tooltip at once, without animation. Escape closes it and focus stays on the trigger.
- Clicking the trigger closes the tooltip (`closeOnClick`), so it doesn't cover the menu or result the click opened.
- The popup can be hovered without closing, so the pointer can cross onto it. Pass `disableHoverablePopup` to turn that off.
- It portals to the body, sits above the trigger 4px away by default, and flips to the opposite side when there is no room.
- Tooltips don't open from touch. On a phone, the icon's `aria-label` and the surrounding layout have to carry the meaning.
- Under reduced motion the scale and slide drop out and only the fade remains.

Do and don't:
- Do: Name the action in two to four words, exactly as the button's `aria-label` does.
- Don't: Write a paragraph in a tooltip. Nobody can reread it, and it disappears on touch. Use an info tip.
- Do: Show the shortcut as Kbd chips after the label.
- Don't: Write the shortcut in brackets as plain text. It reads as part of the name and doesn't look like keys.
- Do: Keep a disabled control focusable with `focusableWhenDisabled` and let the tooltip say why.
- Don't: Put a tooltip on a natively disabled button. It can't be hovered or focused, so the reason is never shown.

Content:
- Sentence case, no trailing period, verb first for actions: Download remittance, Copy link.
- Match the `aria-label` word for word, so what people see and what screen readers say agree.
- For unavailable controls, say what unlocks them: Maya Okafor approves runs over $1M.
- Write keys as symbols in their own Kbd: ⌘ ↵, J, Shift C.

Accessibility:
- The tooltip is not the accessible name. Give icon-only triggers an `aria-label` with the same words.
- Mark the trigger's icon `aria-hidden="true"`.
- Tooltips open on keyboard focus as well as hover, so keyboard users see the same hints.
- Content must be short and non-essential: it never shows on touch and can't hold focus.
- A disabled control needs `focusableWhenDisabled` (or `aria-disabled`) so it can still be focused and hovered.
- Motion is 125ms and reduces to a fade under reduced motion.
- Tab: Focusing the trigger opens its tooltip immediately.
- Esc: Closes the tooltip. Focus stays on the trigger.

Known gaps (follow the system, not the gap):
- `TooltipProvider` defaults `delay` to 0. The 400ms in DESIGN.md exists only because the root layout passes it; any nested provider without a `delay` opens tooltips instantly.
- `TooltipContent` still carries `data-[state=delayed-open]` animation classes from Radix. Base UI never sets that attribute, so they never apply.
- Many product tooltips pass `className="flex items-center gap-1.5"` for a label and Kbd. The popup is already `inline-flex items-center gap-1.5`, so the class is redundant.
- A Button with `focusableWhenDisabled` gets `aria-disabled` instead of `disabled`, and Button only dims on `disabled:`. A focusable disabled trigger looks enabled unless you add `aria-disabled:opacity-50`, as the example below does.

API `TooltipProvider` (extends Base UI `Tooltip.Provider`):
- `delay?: number` = 0. Milliseconds of hover before a tooltip opens.
- `closeDelay?: number`. Milliseconds before a tooltip closes.
- `timeout?: number` = 400. Another tooltip opens instantly if the last one closed within this many milliseconds.

API `Tooltip` (extends Base UI `Tooltip.Root`):
- `open?: boolean`. Controls whether the tooltip is open.
- `defaultOpen?: boolean` = false. Whether it starts open when uncontrolled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when it opens or closes.
- `disabled?: boolean` = false. Stops the tooltip from opening.
- `disableHoverablePopup?: boolean` = false. Closes the tooltip when the pointer moves onto it.
- `trackCursorAxis?: "none" | "x" | "y" | "both"` = "none". Follows the cursor along an axis, for charts and bars.

API `TooltipTrigger` (extends Base UI `Tooltip.Trigger` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render your own control, usually `<Button size="icon-sm" aria-label="…" />`.
- `delay?: number` = 600. Overrides the provider's delay for this trigger. Leave it unset in the app.
- `closeDelay?: number` = 0. Milliseconds before closing after the pointer leaves.
- `closeOnClick?: boolean` = true. Closes the tooltip when the trigger is clicked.
- `disabled?: boolean` = false. Stops the tooltip opening from this trigger without disabling the element.

API `TooltipContent` (extends Base UI `Tooltip.Popup`):
- `side?: "top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"` = "top". Which side of the trigger it opens on.
- `sideOffset?: number` = 4. Distance from the trigger in pixels.
- `align?: "start" | "center" | "end"` = "center". Alignment along the trigger's edge.
- `alignOffset?: number` = 0. Offset along the alignment axis.
- `className?: string`. Merged onto the popup after its defaults.

### Info tip

- Level: Molecule
- Category: Content
- Status: Stable
- Import: `@oration/canon/components/info-tip`
- Exports: `InfoTip`
- Docs: /design/components/info-tip

Info tip is the small (i) beside a section title, metric or piece of jargon. It opens a 20rem popover with a title, one or two sentences, and optionally a help video and a link to the full article, so a page can explain Days payable outstanding or Remittance advice without a tour or a wall of help text. It is how Oration teaches in place, and it is used on nearly every settings section and metric. The common mistake is hiding required information in it: an info tip is for the curious, so the page must still work for someone who never opens one.

When to use:
- Beside a settings section title or row label whose name is jargon: Approval threshold, Positive pay, Warm transfer.
- Beside a metric in a stat strip or chart header: Days payable outstanding, Match rate.
- When a short explainer, a two-minute video or a help article would stop someone guessing.
- On dense tool screens where a page intro would push the tool down.

When not to use:
- To name an icon button or show a shortcut. Use /design/components/tooltip instead.
- To explain what a whole overview page is for, once, at the top. Use /design/components/page-intro instead.
- For instructions someone needs to fill a field in correctly. Put them under the field. Use /design/components/field instead.
- For a warning or a state that needs attention. Use /design/components/alert instead.
- For a small form or actions anchored to a button. Use /design/components/popover instead.

Rules:
- Pages explain themselves: Every page answers what it is and why you'd use it in its first viewport: through its title and description, a page intro on overview pages, or info tips beside config sections, metrics and jargon. No tours, no coach marks.
- The Quiet Indigo Rule: The (i) is Slate Meta and turns ink on hover. Its only indigo is the Learn more link, which is a link, and its focus ring.

Anatomy:
- Trigger: A 16px round button with a 14px info icon in Slate Meta, named About {title}. Its hit area extends to 24px.
- Title: 14px semibold, balanced, naming the term.
- Description: 13px on a 20px line, one or two sentences in plain words. Accepts rich content.
- Video: Optional Video facade: a thumbnail with a duration that loads the player only on play.
- Learn more: Optional 13px indigo link. External links open in a new tab with an arrow icon.

States:
- Rest: The (i) in Slate Meta with a help cursor.
- Hover: The icon turns ink over 150ms. After 350ms the popover opens.
- Focus visible: The global 2px Focus Indigo outline at a 2px offset.
- Open: The icon stays ink (`data-popup-open`). The popover grows from a 0.97 scale over 160ms.
- Closing: 150ms after the pointer leaves the trigger and the popover, it fades out over 110ms.
- Video playing: The thumbnail is replaced by the privacy-enhanced YouTube player, which takes focus.

Behavior:
- Click opens it, and so does hovering the (i) for 350ms with a pointer. Touch and keyboard users open it by tapping or pressing Enter.
- It stays open while the pointer is on the trigger or the popover, and closes 150ms after it leaves both, so there's time to cross to the play button or the link.
- Opened by click or keyboard, focus moves to the first control inside: the video's play button or the link. Escape or a click outside closes it and returns focus to the (i).
- The popover is 20rem wide, capped at the viewport minus 2rem, 4px from the trigger, and flips when it would leave the screen. `side` defaults to top and `align` to center.
- The video costs nothing until played: only the thumbnail loads, and the youtube-nocookie player loads on click with autoplay.
- `learnMoreHref` starting with `http://` or `https://` opens in a new tab with `rel="noopener noreferrer"`, an arrow icon and (opens in a new tab) for screen readers. Anything else navigates in place.
- It uses Popover's motion: 160ms in from a 0.97 scale and 110ms out, reduced to a fade under reduced motion.

Do and don't:
- Do: Explain the term in one or two plain sentences, with an example from the user's world.
- Don't: Paste the help article into the description. If it needs headings or a list, link to it with `learnMoreHref`.
- Do: Put the (i) right after the label it explains, 6px away, on the same baseline.
- Don't: Park info tips at the far edge of a row or card, where it isn't clear which label they explain.
- Do: Keep required instructions visible on the page and use the tip for background.
- Don't: Hide how to fill a field in inside a tip. Most people never open one.

Content:
- The title is the term itself, in sentence case: Days payable outstanding, not What is DPO?
- The description starts with what it is, then why it matters: The average number of days between receiving an invoice and paying it. Longer holds cash; too long strains suppliers.
- Use numbers and Cedarline's own objects in examples: suppliers, invoices, payment runs.
- Video titles read like Oration help videos, with a real duration: Match remittances to invoices, 3:12.

Accessibility:
- The trigger is a button named About {title}, so a list of buttons reads About Approval threshold, not Info.
- The popover is labelled by its title and described by its description.
- The link reads Learn more about {title}, plus (opens in a new tab) when external, so several on one page stay distinct.
- The play button is named Play video: {title}, 3 minutes 12 seconds.
- The visible icon is 16px; a pseudo-element extends the hit area to 24px. On touch layouts consider spacing it further from other targets.
- Hover opening is a convenience. Everything is reachable by click, tap and keyboard.
- Tab: Focuses the (i), then the controls inside when open.
- Enter: Opens or closes the tip.
- Space: Opens or closes the tip.
- Esc: Closes the tip and returns focus to the (i).

Known gaps (follow the system, not the gap):
- InfoTip takes no `open` or `onOpenChange`, so it can't be opened from elsewhere, such as from a What's this? link in an empty state.
- The hover delay (350ms) and close delay (150ms) are fixed and differ from the tooltip's 400ms, so a row with both opens them at different speeds.
- The trigger's hit area is 24px everywhere. DESIGN.md asks for 32px targets on touch surfaces.

API `InfoTip` (extends Nothing. Only the props below are accepted.):
- `title: string`. The term. Also names the trigger (About {title}) and the link.
- `description: ReactNode`. One or two sentences. Rendered in a div, so it can hold rich content.
- `video?: { youtubeId: string; title: string; duration: string }`. A help video shown as a click-to-load facade.
- `learnMoreHref?: string`. Adds a Learn more link. `http(s)://` opens in a new tab.
- `side?: "top" | "bottom" | "left" | "right"` = "top". Where the popover opens.
- `align?: "start" | "center" | "end"` = "center". Alignment along the trigger.
- `className?: string`. Merged onto the trigger button.

### Popover

- Level: Molecule
- Category: Overlays
- Status: Stable
- Import: `@oration/canon/components/popover`
- Exports: `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverHeader`, `PopoverTitle`, `PopoverDescription`
- Docs: /design/components/popover

Popover is a small non-modal surface anchored to the button that opened it, for a handful of controls that belong to that button: display options above a grid, sharing a list, recording settings, a date picker. The page behind stays live, so it suits adjustments that apply as you make them. Most of the product's pickers are built from it. The mistake is growing it into a dialog: once it needs a title bar, a long form or a Save and Cancel footer, use a dialog or sheet.

When to use:
- For view options that apply immediately, such as row height and visible columns in a toolbar Display popover.
- For a short form tied to one button: share a list, rename a view, set a reminder.
- For pickers: a date on a calendar, a color, a disposition or a transfer target.
- For secondary settings of the thing beside it, such as a meeting's recording settings.

When not to use:
- For a list of actions or options to pick one from. Use /design/components/dropdown-menu instead.
- For a short label on hover or focus. Use /design/components/tooltip instead.
- To explain a term, with an optional video and article link. Use /design/components/info-tip instead.
- For a task that needs focus, a title and a Save footer, or that must block the page. Use /design/components/dialog instead.
- For record details that should keep the list in view. Use /design/components/sheet instead.
- For choosing one value from a known list in a form. Use /design/components/select instead.

Rules:
- The Hairline-and-Lift Rule: The surface takes its edge and lift from the overlay shadow and a 1px ink ring at 10%, never a CSS border. Hairline dividers are only for splitting sections inside it.
- The One Filled Button Rule: A popover belongs to a view that already has its primary action. Inside it, buttons are outline or ghost, unless the popover is itself a small form whose submit is its only action.

Anatomy:
- Trigger: A button, usually outline or ghost at 28px in toolbars. It keeps its hover fill while the popover is open.
- Surface: Popover White, 10px corners, the overlay shadow and a 1px ink ring at 10%. 18rem wide with 10px padding and 10px gaps by default.
- Header: Optional. `PopoverTitle` in medium weight and `PopoverDescription` in Slate Meta, 2px apart.
- Content: Controls and text. Section it with hairlines by passing `p-0 gap-0` and padding each section.

States:
- Closed: Not rendered. The trigger shows `aria-expanded="false"`.
- Opening: Fades in from a 0.97 scale and slides 8px from the trigger side over 160ms on the house ease-out, growing from the trigger (`--transform-origin`).
- Open: The trigger has `aria-expanded="true"` and `data-popup-open`, so outline and ghost buttons keep their Well Gray fill.
- Closing: Fades out toward a 0.95 scale in 110ms, faster than it opened.
- Reduced motion: Scale and slide are zeroed; only the fade remains.

Behavior:
- Built on Base UI Popover. Click the trigger to toggle it; Escape or a click outside closes it.
- Opening moves focus to the first focusable element inside, or to the popup itself when opened by touch so the keyboard doesn't jump up. Closing returns focus to the trigger. Change either with `initialFocus` and `finalFocus`.
- Non-modal by default: the page stays scrollable and clickable. `modal` locks scroll and blocks outside clicks; `"trap-focus"` also traps focus.
- Uncontrolled by default. There is no close part exported, so to close after a submit, control it with `open` and `onOpenChange`.
- It portals to the body, opens below the trigger 4px away and centered, and flips or shifts to stay on screen. Toolbars on the right use `align="end"`.
- `openOnHover` on the trigger also opens it on hover after `delay` (300ms by default), as Info tip does.
- Motion is shared with menus, selects and comboboxes: 160ms in from 0.97 and 110ms out.

Do and don't:
- Do: Keep it to one job: a few controls that apply as you change them, or one short form.
- Don't: Build a dialog inside a popover, with a title bar, a long form and Save and Cancel. It loses focus management and the page behind stays live.
- Do: Split sections with a hairline and pad each one, with `p-0 gap-0` on the content.
- Don't: Nest a bordered card inside the popover to group controls. That is a card in a card.

Content:
- The trigger names what's inside: Display, Share, Recording settings. Not Options or More.
- Titles are short nouns in sentence case; descriptions are one sentence on what the settings apply to.
- Settings that apply immediately need no Save. Confirm with a toast when the effect isn't visible on the page.

Accessibility:
- The trigger gets `aria-haspopup="dialog"` and `aria-expanded`; the popup is `role="dialog"`, labelled by `PopoverTitle` and described by `PopoverDescription`.
- Without a visible title, name the popup with `aria-label`, such as Display options.
- `PopoverTitle` renders an `h2`. Pass `render={<h3 />}` or another element when that breaks the page outline.
- Every control inside needs a label, visible or screen reader only.
- Focus moves in on open and back to the trigger on close, so keyboard users never lose their place.
- Enter: Opens or closes the popover from its trigger.
- Space: Opens or closes the popover from its trigger.
- Tab: Moves through the controls inside.
- Esc: Closes the popover and returns focus to the trigger.

Known gaps (follow the system, not the gap):
- Base UI's `Popover.Close` isn't wrapped, so there is no way to close from inside without controlling `open`. Every form popover in the product repeats that state.
- Enter uses the 0.97 scale from globals.css, but exit keeps `zoom-out-95`, so popovers shrink to 0.95 on close.
- `PopoverTitle` is always an `h2`, which lands at the end of the body through the portal. Only 2 of the 17 files that render a popover use it; the rest hand-roll a `<p className="text-sm font-medium">` title or have none, so the dialog has no name unless an `aria-label` is set.

API `Popover` (extends Base UI `Popover.Root`):
- `open?: boolean`. Controls whether it is open.
- `defaultOpen?: boolean` = false. Whether it starts open when uncontrolled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when it opens or closes.
- `modal?: boolean | "trap-focus"` = false. `true` locks scroll and blocks outside clicks; `"trap-focus"` also traps focus.
- `onOpenChangeComplete?: (open: boolean) => void`. Called after the open or close animation ends.

API `PopoverTrigger` (extends Base UI `Popover.Trigger` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render your own button, such as `<Button variant="outline" size="sm" />`.
- `openOnHover?: boolean` = false. Also opens on hover.
- `delay?: number` = 300. Hover delay in milliseconds, with `openOnHover`.
- `closeDelay?: number` = 0. Close delay after hover ends, with `openOnHover`.
- `nativeButton?: boolean` = true. Set `false` when `render` isn't a `<button>`.

API `PopoverHeader` (extends `<div>`):

API `PopoverTitle` (extends Base UI `Popover.Title` (`<h2>`)):

API `PopoverDescription` (extends Base UI `Popover.Description` (`<p>`)):

### Hover card

- Level: Molecule
- Category: Overlays
- Status: Experimental
- Import: `@oration/canon/components/hover-card`
- Exports: `HoverCard`, `HoverCardTrigger`, `HoverCardContent`
- Docs: /design/components/hover-card

Hover card is a preview of the record behind a link: hover or focus Northwind Freight in an activity line and a 16rem card shows its stage, balance and owner without leaving the page. It is a peek, not a place to work. The link still goes to the record, and nothing inside the card is required, because touch users never see it and keyboard users can't reach into it. It is experimental and not used in the product yet.

When to use:
- On links to records inside running text or activity: a supplier, a person, an invoice.
- When a glance at two or three facts saves opening the record: stage and balance, role and email.
- In dense places where adding those facts inline would crowd the row.

When not to use:
- To name an icon or show a shortcut. Use /design/components/tooltip instead.
- To explain a term. Use /design/components/info-tip instead.
- For anything with buttons or fields. Keyboard users can't tab into a hover card. Use /design/components/popover instead.
- For the full record while keeping the list in view. Use /design/components/sheet instead.

Rules:
- The Hairline-and-Lift Rule: The card lifts with the overlay shadow and a 1px ink ring at 10%. Inside, split regions with hairlines or a Well Gray tint well, never a nested card.
- The Option Hue Rule: A stage or tier inside the preview is a Tag in its option hue, and the monogram tile takes the record's identity tint. Nothing else in the card is colored.

Anatomy:
- Trigger: A real link to the record. It opens the card on hover after 600ms, or on keyboard focus.
- Surface: Popover White, 10px corners, the overlay shadow and ring, 16rem wide with 10px padding.
- Identity: A monogram tile or avatar with the record's name and one line of meta.
- Facts: Two or three values that answer why you hovered: stage, balance, owner.

States:
- Closed: Only the link is drawn.
- Opening: After 600ms of hover, or at once on focus, the card grows from a 0.97 scale and slides 8px from the link over 160ms.
- Open: Stays open while the pointer is on the link or the card, so you can move onto it to select text.
- Closing: 300ms after the pointer leaves both, it fades out over 110ms toward a 0.95 scale.

Behavior:
- Built on Base UI Preview Card. `HoverCardTrigger` renders an `<a>`, so pass `href` or `render={<Link href="…" />}` and it navigates like any link.
- Opens after `delay` (600ms) of hover, or immediately when the link takes keyboard focus. Closes `closeDelay` (300ms) after the pointer leaves the link and card, or when focus leaves the link.
- The card portals to the body. Tab from the link moves on through the page, not into the card, so it must not hold anything interactive.
- It never opens on touch; a tap follows the link.
- Opens below the link and centered, 4px away, and flips near the viewport edge. Its default `alignOffset` is 4.
- Shares the menu and popover motion: 160ms in from 0.97, 110ms out, a fade only under reduced motion.

Do and don't:
- Do: Show two or three facts that answer why someone hovered, and keep the link as the way to the record.
- Don't: Put buttons, menus or forms in the card. Keyboard and touch users can't reach them.
- Do: Wait the full 600ms so the card doesn't flash as the pointer crosses a list of names.
- Don't: Set `delay` to 0 on names in a feed. Moving the pointer down the page sets off a card on every row.

Content:
- Lead with the record's name exactly as the link says it.
- Meta is facts with units, not sentences: Negotiation, $212,400 open, Owned by Priya Raman.
- Don't repeat what the surrounding line already says.

Accessibility:
- The trigger is a real link with its own accessible name; the card adds nothing a screen reader needs.
- Keyboard focus opens the card, but its content isn't in the tab order. Everything in it must also be on the record page.
- The card has no dialog role and isn't announced. Treat it as a visual convenience.
- Touch devices never show it.
- Tab: Focusing the link opens the card; moving focus away closes it.
- Enter: Follows the link.
- Esc: Closes the card.

Known gaps (follow the system, not the gap):
- Hover card isn't used anywhere in the product. Record names in activity, tables and transcripts are plain links with no preview.
- `HoverCardContent` defaults `alignOffset` to 4 while every other popup uses 0, so a centered card sits 4px off center.
- Like Popover, it enters from 0.97 but exits with `zoom-out-95` to 0.95.

API `HoverCard` (extends Base UI `PreviewCard.Root`):
- `open?: boolean`. Controls whether the card is open.
- `defaultOpen?: boolean` = false. Whether it starts open when uncontrolled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when it opens or closes.

API `HoverCardTrigger` (extends Base UI `PreviewCard.Trigger` (`<a>`)):
- `href?: string`. Where the link goes.
- `render?: ReactElement | (props, state) => ReactElement`. Render a Next `Link` instead of a plain anchor.
- `delay?: number` = 600. Milliseconds of hover before the card opens.
- `closeDelay?: number` = 300. Milliseconds before it closes after the pointer leaves.

API `HoverCardContent` (extends Base UI `PreviewCard.Popup`):
- `side?: "top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"` = "bottom". Which side of the link it opens on.
- `sideOffset?: number` = 4. Distance from the link in pixels.
- `align?: "start" | "center" | "end"` = "center". Alignment along the link.
- `alignOffset?: number` = 4. Offset along the alignment axis.
- `className?: string`. Merged after the defaults (`w-64 p-2.5`).

### Dropdown menu

- Level: Molecule
- Category: Overlays
- Status: Stable
- Import: `@oration/canon/components/dropdown-menu`
- Exports: `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuSub`, `DropdownMenuShortcut`
- Docs: /design/components/dropdown-menu

Dropdown menu is a list of actions or options that opens from a button: a row's More actions, a toolbar's Sort, the user menu. Items can carry an icon and a shortcut, toggle as checkboxes, pick one value as a radio group, open a submenu, or remove something in Signal Red. It is the most common overlay in the product. The two things people get wrong are using it for navigation that belongs in the page, and hiding a view's main action inside it. Menus hold the secondary actions; the primary one stays a button.

When to use:
- For a row's or record's secondary actions behind a More actions icon button: duplicate, download, copy link, delete.
- For view options that are a choice from a short list: Sort by, Group by, which columns show.
- For the user and workspace menus, with a label, groups and a theme submenu.
- For a split button's alternates, such as Save with Save as template.

When not to use:
- To choose a value for a form field. A select shows the chosen value and belongs to the form. Use /design/components/select instead.
- For controls such as switches, inputs or a segmented control. Use /design/components/popover instead.
- For searching or running any command from the keyboard. Use /design/components/command instead.
- For the same actions on right-click. Mirror this menu in a context menu instead of replacing it. Use /design/components/context-menu instead.
- For the one action the view exists for. Keep it a visible button. Use /design/components/button instead.

Rules:
- Destructive is a tint: A destructive item is Signal Red text that highlights with a 10% red tint (20% in dark), and it sits last, after a separator. It never becomes a solid red row.
- The Hairline-and-Lift Rule: The menu takes its edge from the overlay shadow and a 1px ink ring at 10%. Separators are the only lines inside it.

Anatomy:
- Trigger: A button, often a ghost `icon-sm` with `MoreHorizontalIcon` and an `aria-label` that names the object. It keeps its hover fill while open.
- Surface: Popover White, 10px corners, 4px padding, the overlay shadow and ring. At least 8rem wide, and as wide as the trigger unless you set a width.
- Group label: 12px medium Slate Meta, for naming a group or the object.
- Item: A 28px row with 8px corners, a 16px icon and 14px text, highlighted in Menu Hover.
- Shortcut: 12px Slate Meta at the end of the row.
- Submenu trigger: An item with a trailing chevron. It stays highlighted while its submenu is open.
- Separator: A Hairline that runs to the menu's edges, 4px above and below.
- Destructive item: Signal Red text and icon, last in the menu.

States:
- Closed: The trigger has `aria-expanded="false"`.
- Opening: Grows from a 0.97 scale and slides 8px from the trigger over 160ms on the house ease-out.
- Item rest: No fill. Text in Popover ink, icons 16px.
- Item highlighted: Menu Hover fill from pointer or arrow keys; the highlight follows the pointer (`highlightItemOnHover`).
- Destructive highlighted: A 10% Signal Red tint (20% in dark) behind red text.
- Checked: Checkbox and radio items show a 16px check at the right edge.
- Submenu open: The submenu trigger keeps its Menu Hover fill.
- Disabled: 50% opacity and no pointer events. Arrow keys still reach it, so screen reader users hear that it exists, but it can't be chosen.
- Closing: Fades out toward a 0.95 scale in 110ms.

Behavior:
- Built on Base UI Menu. Click, Enter, Space or Down on the trigger opens it. Focus moves into the menu, arrow keys move the highlight and wrap at the ends, and typing jumps to the item that starts with those letters.
- Choosing an item runs its `onClick` and closes the menu. Checkbox and radio items stay open by default so several can be changed; set `closeOnClick` to change either.
- Escape or a click outside closes it, and focus returns to the trigger.
- Modal by default: while open, the page doesn't scroll and outside clicks only close the menu. Pass `modal={false}` for menus in toolbars that shouldn't lock the page.
- `align` defaults to start, so the menu lines up with the trigger's left edge; row action menus at the right of a row use `align="end"`. It flips and shifts to stay on screen, and scrolls inside the available height.
- Submenus open to the right on hover after 100ms, or with Right or Enter, and close with Left or Escape. They reposition to the left near the viewport edge.
- Menu items that navigate render a Next `Link` through `render`, so they keep link behavior.
- Motion is shared with popovers and selects: 160ms in from 0.97 and 110ms out, a fade only under reduced motion.

Do and don't:
- Do: Name the trigger for the object, More actions for INV-20931, and put the destructive item last after a separator.
- Don't: Mix the destructive item into the middle of the list, where a slip of the pointer removes the supplier.
- Do: Keep the view's main action as a visible button and use the menu for the rest.
- Don't: Hide the only way to approve an invoice inside a menu. People scan for buttons, not kebabs.
- Do: Keep menus to about seven items in groups, with a submenu for a long set of values.
- Don't: List fifteen items in one column. Past a screen, it's a select, a combobox or a command menu.

Content:
- Items start with a verb and name the object when it isn't obvious: Download PDF, Copy link, Remove from Cedarline.
- Use the same verb the rest of the product uses: if the button says Void invoice, the menu does too.
- Option items are nouns in sentence case: Due date, Amount, Supplier name.
- An item that opens a dialog ends with an ellipsis only if the dialog asks for more input: Move to payment run….
- Shortcuts use symbols: ⌘D, ⇧⌘C.

Accessibility:
- The trigger gets `aria-haspopup="menu"` and `aria-expanded`; the surface is `role="menu"`, items are `menuitem`, `menuitemcheckbox` or `menuitemradio` with `aria-checked`.
- Icon-only triggers need an `aria-label` that names the object, such as More actions for INV-20931, and a tooltip.
- Group labels name their group for screen readers through `Menu.GroupLabel`; wrap labelled items in a `DropdownMenuGroup`.
- Item icons are decorative; the label names the action.
- Focus returns to the trigger on close, so keyboard users land where they started.
- Rows are 28px, above the 24px minimum target.
- Enter: Opens the menu, or runs the highlighted item.
- Space: Opens the menu, or runs the highlighted item.
- ↓ + ↑: Moves the highlight, wrapping at the ends. Down on the trigger opens the menu.
- Home: Highlights the first item.
- End: Highlights the last item.
- →: Opens the highlighted submenu.
- ←: Closes the submenu and returns to its trigger.
- Esc: Closes the menu and returns focus to the trigger.
- A–Z: Jumps to the next item starting with that letter.

Known gaps (follow the system, not the gap):
- `DropdownMenuContent` defaults to the trigger's width (`w-(--anchor-width)`, at least 8rem), so a menu opened from an icon button is 8rem wide and truncates. Nearly every call site passes a width such as `w-56`.
- `DropdownMenuShortcut` sets `tracking-widest`, letter-spacing the shortcut against the no letter-spaced captions rule, and writes plain text where tooltips use Kbd chips. Only the app sidebar's help menu uses it.
- Base UI's `Menu.LinkItem` isn't wrapped. Navigating items render a `Link` through `DropdownMenuItem`'s `render`, which works but keeps the `menuitem` role on a link.
- Submenus use `shadow-lg`, the dialog shadow, where DESIGN.md gives every menu the overlay shadow.
- Menus enter from 0.97 but exit with `zoom-out-95` to 0.95.

API `DropdownMenu` (extends Base UI `Menu.Root`):
- `open?: boolean`. Controls whether it is open.
- `defaultOpen?: boolean` = false. Whether it starts open when uncontrolled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when it opens or closes.
- `modal?: boolean` = true. Locks page scroll and outside interaction while open.
- `loopFocus?: boolean` = true. Wraps the highlight at the ends.
- `highlightItemOnHover?: boolean` = true. Moves the highlight with the pointer.
- `disabled?: boolean` = false. Stops the menu from opening.

API `DropdownMenuTrigger` (extends Base UI `Menu.Trigger` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render your own button, such as `<Button variant="ghost" size="icon-sm" />`.
- `openOnHover?: boolean` = false. Also opens on hover, for menubars.
- `delay?: number` = 100. Hover delay with `openOnHover`.
- `disabled?: boolean` = false. Disables the trigger.

API `DropdownMenuContent` (extends Base UI `Menu.Popup`):
- `align?: "start" | "center" | "end"` = "start". Alignment along the trigger. Row menus use `end`.
- `side?: "top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"` = "bottom". Which side of the trigger it opens on.
- `sideOffset?: number` = 4. Distance from the trigger in pixels.
- `alignOffset?: number` = 0. Offset along the alignment axis.
- `className?: string`. Merged after the defaults. Set a width such as `w-56`; otherwise the menu matches the trigger's width, at least 8rem.

API `DropdownMenuItem` (extends Base UI `Menu.Item` (`<div>`)):
- `onClick?: (event) => void`. Runs the action. The menu then closes.
- `variant?: "default" | "destructive"` = "default". `destructive` draws the item in Signal Red.
- `inset?: boolean` = false. Indents the label 28px to line up with items that have icons or checks.
- `disabled?: boolean` = false. Dims the item and stops it running. It stays reachable by arrow keys.
- `closeOnClick?: boolean` = true. Closes the menu after the click.
- `render?: ReactElement | (props, state) => ReactElement`. Render a Next `Link` for items that navigate.

API `DropdownMenuCheckboxItem` (extends Base UI `Menu.CheckboxItem`):
- `checked?: boolean`. Whether it is checked, when controlled.
- `defaultChecked?: boolean` = false. Initial state when uncontrolled.
- `onCheckedChange?: (checked: boolean, eventDetails) => void`. Called when it toggles.
- `closeOnClick?: boolean` = false. Keeps the menu open so several can be toggled.
- `inset?: boolean` = false. Indents the label 28px.

API `DropdownMenuRadioGroup` (extends Base UI `Menu.RadioGroup`):
- `value?: any`. The selected value, when controlled.
- `defaultValue?: any`. Initial value when uncontrolled.
- `onValueChange?: (value: any, eventDetails) => void`. Called when a radio item is chosen.

API `DropdownMenuRadioItem` (extends Base UI `Menu.RadioItem`):
- `value: any`. The value it selects.
- `closeOnClick?: boolean` = false. Closes the menu after choosing.
- `inset?: boolean` = false. Indents the label 28px.

API `DropdownMenuSub` (extends Base UI `Menu.SubmenuRoot`):

API `DropdownMenuSubTrigger` (extends Base UI `Menu.SubmenuTrigger`):
- `inset?: boolean` = false. Indents the label 28px.
- `disabled?: boolean` = false. Disables the submenu.
- `delay?: number` = 100. Hover delay before it opens.

API `DropdownMenuSubContent` (extends `DropdownMenuContent`):
- `side?: string` = "right". Which side it opens on.
- `alignOffset?: number` = -3. Lines the first item up with the trigger.
- `className?: string`. Set a width such as `w-48` or `w-64`.

API `DropdownMenuLabel` (extends Base UI `Menu.GroupLabel`):
- `inset?: boolean` = false. Indents it 28px.

API `DropdownMenuGroup` (extends Base UI `Menu.Group`):

API `DropdownMenuSeparator` (extends Base UI `Menu.Separator`):

API `DropdownMenuShortcut` (extends `<span>`):

API `DropdownMenuPortal` (extends Base UI `Menu.Portal`):

### Context menu

- Level: Molecule
- Category: Overlays
- Status: Experimental
- Import: `@oration/canon/components/context-menu`
- Exports: `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`
- Docs: /design/components/context-menu

Context menu is the menu that opens where you right-click, or long-press on touch, on a row, a card or a canvas node. It is a shortcut for people who expect one, never the only way to an action: every item must also be in a visible menu or button, because a right-click can't be discovered and has no standard key on a Mac. It shares Dropdown menu's items, sizes and motion. It is experimental and not used in the product yet.

When to use:
- On grid rows, kanban cards and flow nodes, mirroring the row's More actions menu.
- On a column header, for sort, pin and hide, when the same options are in the header's own menu.
- Where power users work fast with a pointer and expect right-click to act on what's under it.

When not to use:
- As the only home for an action. Put it in a visible menu first. Use /design/components/dropdown-menu instead.
- For controls such as fields or switches. Use /design/components/popover instead.
- For commands that apply to the whole app rather than the thing under the pointer. Use /design/components/command instead.
- On text people need to select and copy. The trigger turns off text selection. Use /design/components/copy-row instead.

Rules:
- Mirror a visible menu: A context menu repeats the actions of a menu or buttons people can see, in the same order with the same words. Build both from one list so they can't drift.
- Destructive is a tint: Destructive items are Signal Red text with a 10% red tint on highlight, last after a separator, exactly as in Dropdown menu.

Anatomy:
- Trigger area: The row, card or node that listens for right-click and long press. It turns off text selection.
- Surface: Opens at the pointer. Popover White, 10px corners, 4px padding, the overlay shadow and ring, at least 9rem wide.
- Item: A 28px row with 8px corners, an optional 16px icon and 14px text, highlighted in Menu Hover.
- Shortcut: 12px Slate Meta at the end of the row.
- Separator: A Hairline between groups, edge to edge.
- Destructive item: Signal Red, last in the menu.

States:
- Closed: The trigger area looks like any row or card.
- Opening: Grows from a 0.97 scale at the pointer over 160ms on the house ease-out.
- Item highlighted: Menu Hover fill; icons take the item's text color.
- Destructive highlighted: A 10% Signal Red tint (20% in dark).
- Checked: Checkbox and radio items show a check at the right edge.
- Disabled: 50% opacity, no pointer events, still reachable by arrow keys.
- Closing: Fades out toward a 0.95 scale in 110ms. Submenus take 160ms, a gap in the shared timing.

Behavior:
- Built on Base UI Context Menu. Right-click opens it at the pointer; on touch, a long press does. The browser's own menu is suppressed inside the trigger.
- Keyboard users can open it with the Menu key or Shift+F10 where the platform supports them. macOS has neither, so the same actions must be in a visible menu.
- Once open, it behaves like Dropdown menu: arrow keys, Home, End and typeahead move the highlight, Enter runs an item, Right and Left open and close submenus, Escape closes it.
- Unlike Dropdown menu, it takes no `modal`, `openOnHover` or `delay` props.
- It opens to the right of the pointer, aligned to its top, and flips near the viewport edge. Content scrolls inside the available height.
- The trigger sets `select-none`, so text inside it can't be selected while it is a trigger.

Do and don't:
- Do: Build the row's visible menu and its context menu from one list of actions.
- Don't: Put an action only in the context menu. Nobody finds it, and keyboard users on a Mac can't open it.
- Do: Keep the same order and words as the visible menu, destructive last.
- Don't: Reorder the items or rename them in the context menu. People learn one and trip on the other.

Content:
- Same words as the visible menu, verb first: Duplicate, Copy link, Void invoice.
- Name the object only when the menu could act on several things, such as a row and its cell.
- Shortcuts use symbols: ⌘D, ⌫.

Accessibility:
- The surface is `role="menu"` and items are `menuitem`, `menuitemcheckbox` or `menuitemradio`, as in Dropdown menu.
- A context menu is never the only path to an action. Mirror it in a visible, labelled menu button.
- Focus moves into the menu on open and back to the trigger area on close.
- Long press on touch opens it, which can clash with text selection and drag. Avoid it on draggable cards unless drag uses a handle.
- Shift + F10: Opens the menu on the focused element, where the platform supports it.
- ↓ + ↑: Moves the highlight, wrapping at the ends.
- Enter: Runs the highlighted item.
- →: Opens the highlighted submenu.
- ←: Closes the submenu.
- Esc: Closes the menu.

Known gaps (follow the system, not the gap):
- Context menu isn't used anywhere in the product. Grid rows, kanban cards and flow nodes offer their actions only through visible menus today.
- `ContextMenuSubContent` passes `className="shadow-lg"` before spreading props, so any `className` you pass, such as a width, replaces the shadow instead of adding to it.
- globals.css times `context-menu-sub-content` at 160ms to open but leaves it out of the 110ms close rule, so context submenus close slower than every other menu.
- `ContextMenuShortcut` has the same `tracking-widest` letter-spacing as the dropdown shortcut.

API `ContextMenu` (extends Base UI `ContextMenu.Root`):
- `open?: boolean`. Controls whether it is open.
- `defaultOpen?: boolean` = false. Whether it starts open when uncontrolled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when it opens or closes.
- `loopFocus?: boolean` = true. Wraps the highlight at the ends.
- `disabled?: boolean` = false. Stops it opening, so the browser menu shows instead.

API `ContextMenuTrigger` (extends Base UI `ContextMenu.Trigger` (`<div>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render the row or card element itself, such as `<li />`.
- `className?: string`. Merged after `select-none`.

API `ContextMenuContent` (extends Base UI `Menu.Popup`):
- `side?: "top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"` = "right". Which side of the pointer it opens on.
- `align?: "start" | "center" | "end"` = "start". Alignment to the pointer.
- `alignOffset?: number` = 4. Offset along the alignment axis.
- `sideOffset?: number` = 0. Distance from the pointer.
- `className?: string`. Set a width such as `w-52`.

API `ContextMenuItem` (extends Base UI `ContextMenu.Item`):
- `onClick?: (event) => void`. Runs the action. The menu then closes.
- `variant?: "default" | "destructive"` = "default". `destructive` draws it in Signal Red.
- `inset?: boolean` = false. Indents the label 28px.
- `disabled?: boolean` = false. Dims it and stops it running.

API `ContextMenuCheckboxItem` (extends Base UI `ContextMenu.CheckboxItem`):
- `checked?: boolean`. Whether it is checked, when controlled.
- `onCheckedChange?: (checked: boolean, eventDetails) => void`. Called when it toggles.
- `inset?: boolean` = false. Indents the label 28px.

API `ContextMenuRadioGroup` (extends Base UI `ContextMenu.RadioGroup`):
- `value?: any`. The selected value, when controlled.
- `onValueChange?: (value: any, eventDetails) => void`. Called when a radio item is chosen.

API `ContextMenuRadioItem` (extends Base UI `ContextMenu.RadioItem`):
- `value: any`. The value it selects.
- `inset?: boolean` = false. Indents the label 28px.

API `ContextMenuSub` (extends Base UI `ContextMenu.SubmenuRoot`):

API `ContextMenuSubTrigger` (extends Base UI `ContextMenu.SubmenuTrigger`):
- `inset?: boolean` = false. Indents the label 28px.

API `ContextMenuSubContent` (extends `ContextMenuContent`):
- `className?: string`. Replaces the default `shadow-lg` rather than merging with it.

API `ContextMenuLabel` (extends Base UI `ContextMenu.GroupLabel`):
- `inset?: boolean` = false. Indents it 28px.

API `ContextMenuGroup` (extends Base UI `ContextMenu.Group`):

API `ContextMenuSeparator` (extends Base UI `ContextMenu.Separator`):

API `ContextMenuShortcut` (extends `<span>`):

API `ContextMenuPortal` (extends Base UI `ContextMenu.Portal`):

### Alert

- Level: Molecule
- Category: Feedback
- Status: Beta
- Import: `@oration/canon/components/alert`
- Exports: `Alert`, `AlertTitle`, `AlertDescription`, `AlertAction`
- Docs: /design/components/alert

Alert is an inline message about the state of a page, section or field: a W-9 that was rejected, a channel that no longer exists, a payment run waiting on approval. It sits in the layout beside the thing it describes and stays there until the condition is resolved. The common mistake is using it as feedback for an action that just finished; a save, a send or a delete answers with a toast, and the alert is kept for conditions someone still has to act on.

When to use:
- For a condition that blocks or changes what happens next: Payments to Halcyon pause until a corrected W-9 arrives.
- Beside a field whose saved value no longer works, such as a Slack channel that was archived.
- For a failed step in a run log, with the fix as an action: Edit step, Retry.
- At the top of a section when something needs a decision before a deadline: Friday's payment run needs approval.
- When the message must stay visible until someone resolves it, not vanish after five seconds.

When not to use:
- To confirm an action that finished, such as Remittance sent. Answer with a toast, with Undo when it can be reversed. Use /design/components/toast instead.
- For a decision that must be made before continuing, such as deleting a supplier. Use /design/components/confirm-dialog instead.
- To explain what a page is for. Education belongs in a dismissible intro. Use /design/components/page-intro instead.
- For a validation error on one input. Put the error under the field. Use /design/components/field instead.
- For a failed read of a whole region. The component owns its error state, with Retry. Use /design/components/data-state instead.
- For unsaved changes. The save bar owns that message. Use /design/components/save-bar instead.

Rules:
- The Label-Beside-Color Rule: Status is never color alone. A destructive alert is red text, and the title still says what broke in words, so it reads the same in grayscale.
- Say what happened and what to do: Every alert names the condition in its title and the fix in its description or action. It never blames the reader and never says Something went wrong.

Anatomy:
- Container: A full-width grid with 10px corners, a 1px Hairline border on Card White, and 10px by 8px padding.
- Icon: Optional. A direct child `svg`, 16px, spanning both text rows in the current text color. Its presence switches the grid to two columns.
- Title: 14px at weight 500. One line that names the condition: Halcyon's W-9 was rejected.
- Description: Optional. 14px Slate Meta: the consequence and the fix. Links inside it are underlined.
- Action: Optional `AlertAction`, pinned 8px from the top and right corners. The container reserves 72px on the right for it.

States:
- Default: Graphite Ink title and Slate Meta description on Card White. For notices and conditions that need attention but aren't broken.
- Destructive: The title and icon turn Signal Red and the description red at 90%. For something that failed or is blocked.
- With icon: A direct `svg` child switches to a two-column grid; the title and description start in column two.
- With action: An `AlertAction` child adds 72px of right padding so the title never runs under the button.
- Link hover: Links in the title and description are underlined at a 3px offset and turn Graphite Ink on hover.
- Resolved: When the condition clears, remove the alert or swap it for the resolved message in place. Don't leave a stale alert on screen.

Behavior:
- Alert is static markup. It has no open, close or dismiss behavior of its own; it renders while your condition is true.
- `role="alert"` is set by default, so an alert that appears in response to something (a failed retry, a changed field) is announced right away.
- For a notice that is simply present when the page loads, pass `role="status"`; your `role` overrides the default because props spread last.
- The icon must be a direct child `svg` for the two-column layout; wrapping it in a span drops the grid.
- For one action, use `AlertAction` and keep it short (about 64px). For two or more, put them in the description as a row of `xs` buttons, as the run log does.
- No animation. If the alert replaces another, swap it in place so the layout doesn't jump.

Do and don't:
- Do: Name the condition in the title and the fix in the description: what was rejected, why, and what to do.
- Don't: Write Error and Something went wrong. The reader learns nothing and has nowhere to go.
- Do: Use an alert for a condition that persists until someone resolves it.
- Don't: Confirm a finished action with an alert. Settings saved belongs in a toast.
- Do: Summarize related failures in one alert and list what's affected.
- Don't: Stack an alert per item. Three red boxes read as three problems and push the page down.

Content:
- Title: the condition as a short statement, sentence case, no trailing period: Halcyon's W-9 was rejected.
- Description: one or two sentences with the consequence and the fix: Payments pause until a corrected W-9 arrives.
- Name the object: the supplier, the run, the channel. Avoid this item and the record.
- Give dates and amounts exactly, in tabular figures: Approve by Thursday at 5:00 PM CT, $1,284,310.00.
- Action labels start with a verb and name the fix: Request W-9, Edit step, Retry. Not OK or Learn more.
- Calm and plain, never blaming: The TIN doesn't match IRS records, not You entered an invalid TIN.

Accessibility:
- Alert renders `role="alert"`, an assertive live region. Keep it for alerts that appear after something happens; pass `role="status"` for notices that are already there on load.
- Mark the icon `aria-hidden="true"`; the title carries the meaning.
- Destructive alerts are red text on Card White. The title says what failed, so the meaning doesn't depend on color.
- Buttons in `AlertAction` or the description need visible labels that name the fix. Icon-only actions need an `aria-label` and a tooltip.
- When an alert sits under a field, also set `aria-invalid` on the control so the field itself reports the problem.
- Don't move focus to an alert. The live region announces it; focus stays where the person was working.

Known gaps (follow the system, not the gap):
- The container draws its edge with a 1px CSS border on Card White. DESIGN.md keeps CSS borders for structural dividers; an inline notice would follow the Tint Well Rule (Well Gray at 70%) instead.
- There are only `default` and `destructive` variants. DESIGN.md defines Caution Amber for warnings and Note Blue for informational notices, and the product hand-rolls warning notices as `bg-warning/10` wells in several places (public keys settings, the procedure publish dialog) rather than using Alert.
- `role="alert"` is hard-coded as the default, so every alert is assertive, including static notices present on page load. Pass `role="status"` for those.
- `AlertAction` reserves a fixed 72px (`pr-18`) on the right. An action wider than about 64px overlaps the title; keep it to one short button or move actions into the description.
- Alert is used in two places in the app today (the workflow inspector and the run log), both destructive.

API `Alert` (extends <div>):
- `variant?: "default" | "destructive"` = "default". `destructive` turns the title, icon and description red.
- `role?: AriaRole` = "alert". Pass `"status"` for a notice that is present on load and not urgent.
- `className?: string`. Merged after the variant classes.

API `AlertTitle` (extends <div>):
- `className?: string`. Merged after the defaults.

API `AlertDescription` (extends <div>):
- `className?: string`. Merged after the defaults; add `flex flex-wrap gap-2` to lay out inline buttons.

API `AlertAction` (extends <div>):
- `className?: string`. Merged after `absolute top-2 right-2`.

### Toast

- Level: Molecule
- Category: Feedback
- Status: Stable
- Import: `@oration/canon/components/toast`
- Exports: `toast`, `Toaster`, `useToastManager`
- Docs: /design/components/toast

Toast is the brief answer to an action: Remittance sent, Removed INV-20931 from the run, Couldn't send the remittance. Call `toast.add()` from any client component; the one `Toaster` is mounted in the root layout, so never mount another. Toasts stack at the bottom right, pause while hovered or focused, and leave after five seconds. The common mistake is asking for confirmation before a reversible change; do the change, then offer Undo in the toast.

When to use:
- To confirm a change whose result isn't visible where the person is looking: Remittance sent, Invite sent to Wen Zhou.
- To offer Undo after a reversible change: removing an invoice from a run, archiving a supplier, denying a request.
- To report that a background action failed, with Retry as the action.
- To show a short async task from start to finish with `toast.promise`: Sending remittances, then Sent 48 remittances.
- To summarize a bulk action in one line: Approved 12 invoices.

When not to use:
- For a condition that must stay visible until someone fixes it, such as a rejected W-9. Use /design/components/alert instead.
- For an irreversible delete that needs a decision first. Use /design/components/confirm-dialog instead.
- For a validation error on a field. Put it under the field, where it can be fixed. Use /design/components/field instead.
- For unsaved changes. The save bar holds them until they're saved or discarded. Use /design/components/save-bar instead.
- To confirm a copy. The copy button confirms in place with a check. Use /design/components/copy-button instead.
- When the change is already visible in place, such as a switch flipping or a row updating. A toast on top is noise.

Rules:
- Undo over confirm: Reversible changes happen at once and offer Undo in the toast. A confirmation dialog is only for changes that can't be undone. See Destructive actions.
- Every mutation answers back: A save, send, archive or delete always gets feedback: inline where it changed, or in a toast when the result is out of view. See Feedback and undo.

Anatomy:
- Container: Popover White with 16px corners, a 1px border and the dialog shadow. Up to 24rem wide at the bottom right, full width with 16px margins on phones.
- Icon: Drawn from `type`: a check for success, an i for info, a triangle for warning, a red octagon for error and a spinner for loading. No icon without a type.
- Title: 14px at weight 500. The outcome, in a few words.
- Description: Optional. 14px Slate Meta: the object and the detail that matters, such as the supplier and amount.
- Action: Optional, from `actionProps`. A small outline button, usually Undo or Retry. Clicking it runs your handler and closes the toast.
- Close: A small ghost icon button named Close toast, with its hit area extended 8px on each side.

States:
- Entering: Slides up from 150% below the viewport edge over 500ms on cubic-bezier(0.22, 1, 0.36, 1).
- Stacked: Older toasts sit behind the newest, each 12px higher and 10% smaller, with their content faded out. Only the front toast reads.
- Expanded: Hovering or focusing the stack fans the toasts out 12px apart at full size and pauses every timer.
- Focus visible: A Focus Indigo border and a 3px ring at 50% on the toast; its action and close button take the button focus ring.
- Limited: Past three toasts, the oldest fade to transparent and leave the tab order until newer ones close.
- Loading: `type: "loading"`, set by `toast.promise`, shows a spinner. It updates to success or error in place when the promise settles.
- Swiping: Dragging down or right follows the pointer; past the threshold the toast leaves in that direction.
- Exiting: Slides back down 150% (or out the way it was swiped) over the same 500ms.

Behavior:
- `toast` is a module-level Base UI toast manager, so `toast.add()` works from any client component, event handler or store without a hook or context.
- `toast.add()` returns the toast's id. Pass your own `id` to update a toast in place instead of stacking a new one; adding with an existing id refreshes its timer.
- Toasts close after 5000ms. `timeout: 0` keeps one open until it's dismissed; use it for an error that needs a decision.
- Timers pause while the stack is hovered or focused and while the window is in the background, so an Undo is always reachable.
- `actionProps` is spread onto the action button. `{ children: "Undo", onClick }` is the whole pattern; the toast closes after `onClick` runs.
- `toast.promise(promise, { loading, success, error })` shows a loading toast and turns it into the success or error toast when the promise settles. `success` and `error` can be functions of the result.
- `toast.close(id)` closes one toast, `toast.close()` closes all, and `toast.update(id, options)` changes one in place.
- At most three toasts show at once; older ones are marked `data-limited` and hidden until there's room.

Do and don't:
- Do: Summarize a bulk action in one toast, with one Undo for all of it.
- Don't: Fire a toast per item. Three at once stack into noise and the first ones are hidden.
- Do: Name what changed and offer Undo when the change can be reversed.
- Don't: Celebrate with Success! and give no way back. The reader can't tell which invoice, or undo it.

Content:
- Title: the outcome in past tense, with the object: Remittance sent, Removed INV-20931 from the run, Archived Orchard Street.
- Errors say what failed without blame: Couldn't send the remittance. The description says what to do: Try again in a minute.
- Description: the detail that makes it specific, such as the supplier, amount or date: Northwind Freight, $18,420.00 by ACH.
- Loading titles use a present participle and no ellipsis in the string: Sending remittances.
- The action is one verb: Undo, Retry, View. Never OK or Dismiss; the close button already dismisses.
- No exclamation points, no Success!, no emoji. Count in figures: Approved 12 invoices.

Accessibility:
- The viewport is a `role="region"` named Notifications and an `aria-live="polite"` region, so new toasts are announced without interrupting.
- Each toast is a non-modal `role="dialog"` labelled by its title and described by its description. `priority: "high"` makes it an `alertdialog` and announces it urgently; save that for failures that block work.
- F6 moves focus to the notifications region from anywhere, and Shift+Tab from there returns focus to where it was.
- The type icon is `aria-hidden`; the title carries the meaning, so an error reads as an error without the red octagon.
- Timers pause while a toast has focus or hover, so keyboard and screen reader users can reach Undo before it leaves.
- An Undo in a toast is a convenience, not the only path. The change should also be reversible from the place it was made.
- The close button is 28px with an extended hit area, above the 24px minimum.
- F6: Moves focus to the notifications region and pauses timers.
- Tab: Moves through toasts and their action and close buttons.
- Shift + Tab: From the region itself, returns focus to the element that had it before F6.
- Enter: Activates the focused action or close button.
- Esc: Closes the toast that has focus.

Known gaps (follow the system, not the gap):
- Toasts have 16px corners (`rounded-2xl`), outside the 6, 8, 10 and 12px radius ramp. DESIGN.md puts overlays at 10px and dialogs at 12px.
- Each toast draws a 1px CSS border plus `shadow-lg`, where the Hairline-and-Lift Rule gives overlays one composite shadow with a ring instead.
- Enter, exit and stacking run 500ms transforms on cubic-bezier(0.22, 1, 0.36, 1), not the spring tokens, past the 320ms ceiling in the Three Springs Rule. The classes have no `motion-reduce` variants, so the slide still runs under reduced motion, and the loading spinner keeps spinning.
- `type` is a plain string. The suite brief lists success, error and info; the component also draws warning and loading, and a misspelled type silently shows no icon.
- The info icon is drawn in the text color. DESIGN.md names Note Blue for informational toasts.
- `useToastManager` is exported, but the root layout mounts `<Toaster />` as a sibling of the page rather than around it, so calling the hook in app code throws. Use `toast` directly.

API `toast`:
- `add?: (options: ToastManagerAddOptions) => string`. Shows a toast and returns its id.
- `close?: (id?: string) => void`. Closes one toast, or every toast when called with no id.
- `update?: (id: string, options: ToastManagerUpdateOptions | (prev) => ToastManagerUpdateOptions) => void`. Changes an open toast in place.
- `promise?: <Value>(promise: Promise<Value>, options: { loading, success, error }) => Promise<Value>`. Shows a loading toast, then the success or error toast when the promise settles. Returns the same promise.

API `ToastManagerAddOptions`:
- `title?: ReactNode`. The outcome. Required in practice.
- `description?: ReactNode`. The object and the detail that matters.
- `type?: string`. Picks the icon: `"success"`, `"info"`, `"warning"`, `"error"` or `"loading"`. Any other value shows no icon.
- `actionProps?: ComponentPropsWithoutRef<"button">`. Props for the action button, such as `{ children: "Undo", onClick }`. No action renders without children.
- `timeout?: number` = 5000. Milliseconds before it closes. `0` keeps it open.
- `priority?: "low" | "high"` = "low". `high` announces urgently and renders as an `alertdialog`.
- `id?: string`. Reuse an id to update a toast in place instead of adding another.
- `onClose?: () => void`. Called when the toast starts closing.
- `onRemove?: () => void`. Called after its exit animation finishes.
- `data?: object`. Custom data for a custom toast list.

API `Toaster` (extends Base UI `Toast.Provider`):
- `toastManager?: ToastManager` = toast. The manager to listen to.
- `timeout?: number` = 5000. Default time before a toast closes.
- `limit?: number` = 3. How many toasts show at once.
- `children?: ReactNode`. Optional. Only children can call `useToastManager`.

API `useToastManager`:

API `Toast` (extends The matching Base UI `Toast.*` part):

### Empty

- Level: Molecule
- Category: Feedback
- Status: Stable
- Import: `@oration/canon/components/empty`
- Exports: `Empty`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, `EmptyContent`
- Docs: /design/components/empty

Empty is the set of primitives for an empty state: a media slot, a one-line title, one sentence about what the place is for, and the next action. Most empty states in Oration don't need the primitives at all; `EmptyState` from Data state takes an illustration name, a title, a description and an action and draws the standard layout, and `DataState` renders it for you when a query comes back empty. Reach for Empty when that layout doesn't fit, such as two actions or a page-level empty. Either way the media is an `Illustration`, never a lucide icon in a gray tile.

When to use:
- When a list, board or panel has nothing in it yet and the reader needs to know what it's for and how to fill it.
- For filtered-to-nothing states that name the filters and offer Clear filters.
- For search with no matches that repeats the query and suggests what to try.
- For a finished queue: You're all caught up on approvals or an inbox.
- When `EmptyState` can't express the layout: two actions, a link beside a button, custom media or a full-page empty.

When not to use:
- For a standard empty state with one action. Use the ready-made `EmptyState`, or `DataState`'s `empty` prop. Use /design/components/data-state instead.
- For a failed load. That is an error state with Retry, not an empty one. Use /design/components/data-state instead.
- While data is loading. Show a skeleton shaped like the result. Use /design/components/skeleton instead.
- For an empty row inside a settings table. Use /design/components/card-table instead.
- To explain a page that already has content. Use a dismissible intro. Use /design/components/page-intro instead.

Rules:
- The Owned States Rule: Every component that shows data owns its loading, empty and error states, with a skeleton shaped like its final layout. The empty state lives inside the component, not on a separate page.
- Illustrations, not icon circles: Empty states use an `Illustration`, a title, one sentence and the next action. A bare lucide icon in a circle or tile is one of the patterns Canon refuses.

Anatomy:
- Container: `Empty`: a centered column with 16px gaps and 24px padding. Give it the surface it sits on, such as `rounded-xl bg-card shadow-border`, or none inside a card.
- Media: `EmptyMedia` holding an `Illustration`: 120px wide by default, 80px (`size="sm"`) in rails and small cards.
- Title: `EmptyTitle`, 14px at weight 500. What is empty, in a few words: No payment runs scheduled.
- Description: `EmptyDescription`, 14px Slate Meta, up to 24rem wide. One sentence about what the place is for, or what hid everything.
- Content: `EmptyContent`: the next action, usually one outline button. A filled button only when filling this place is what the view exists for.

States:
- First use: Nothing has been created yet. Say what the place is for, give one example if it helps, and offer the first action.
- Filtered to nothing: Filters hide every record. Name the filters and offer Clear filters; the `filters` illustration.
- No search results: Repeat the query in quotes, suggest another way to search and offer Clear search; the `search` illustration.
- All done: A queue that was cleared. You're all caught up, what shows up here next, no action; the `done` illustration.
- Compact: In rails and small cards: the small illustration, a 13px title, a 12px description and an extra-small button.

Behavior:
- Empty and its parts are static layout with no state of their own; you decide when to render them.
- `EmptyState` is the opinionated version: `illustration`, `title`, `description`, `action` and `size` (`md` or `sm`). `DataState` renders it when `isEmpty(data)` is true and passes its `size` through.
- `Empty` is `flex-1`, so in a flex column it fills the remaining height and centers its content; use that for a page-level empty below a toolbar.
- Text is balanced (`text-balance`) so short titles and sentences break evenly.
- Filtered and search empties should change back to content in place when the filter or query clears, without a reload.

Do and don't:
- Do: Use an `Illustration` in the media slot.
- Don't: Put a lucide icon in a gray tile with `variant="icon"`. It is the refused pattern, and it reads as a placeholder.
- Do: Say what the place is for and offer the first action.
- Don't: Shrug with No data. It tells the reader nothing about what belongs here or how to add it.
- Do: Name the filters that hid everything and offer Clear filters.
- Don't: Show No results with no way out.

Content:
- Title: what is empty, in a few words and sentence case: No payment runs scheduled, No suppliers match these filters.
- Description: one sentence about what the place is for, or which filters hid everything. Not a paragraph.
- For search, repeat the query in quotes: No suppliers match "Northwind Frieght".
- Action labels start with a verb and name the object: Schedule a run, Clear filters, Request W-9s.
- Warm but brief for first use and all-done; plain for filtered states. No jokes, no exclamation points.
- Never park lasting information in an empty state. It disappears the moment content exists.

Accessibility:
- The illustration is decorative (`aria-hidden`) unless you give it a `title`. The title and description carry the meaning.
- `EmptyTitle` is a `div`. When the empty state replaces a section's content, keep the section heading above it so the page outline doesn't lose a level.
- When filters or a search empty a list, announce the new count in a polite status region so screen reader users hear it changed.
- Buttons in `EmptyContent` need visible labels that name the action.
- Don't move focus into an empty state; focus stays on the filter or search that caused it.

Known gaps (follow the system, not the gap):
- `EmptyMedia variant="icon"` draws a lucide icon in a Well Gray tile, the pattern Canon refuses. All of the roughly 30 `Empty` call sites in the app use it (Home approvals, tasks, inbox, lists, tables, the app status screens) and none uses an `Illustration`.
- `Empty` carries `border-dashed` but no border width, so it draws no outline. The class is inert.
- `EmptyTitle` is weight 500 while `EmptyState`'s title is weight 600, so the product has two empty-state title weights.
- `EmptyTitle` and `EmptyDescription` render `div`s; `EmptyDescription` is typed with `<p>` props. Neither is a heading.
- `EmptyMedia` keeps `data-slot="empty-icon"` even when it holds an illustration.

API `Empty` (extends <div>):
- `className?: string`. Add the surface here, such as `rounded-xl bg-card shadow-border`, and any padding change.

API `EmptyHeader` (extends <div>):
- `className?: string`. Merged after the defaults.

API `EmptyMedia` (extends <div>):
- `variant?: "default" | "icon"` = "default". `default` is a transparent slot for an `Illustration`. `icon` draws a 32px Well Gray tile for a lucide icon, which Canon refuses for empty states.
- `className?: string`. Merged after the variant classes.

API `EmptyTitle` (extends <div>):
- `className?: string`. Use `text-[13px]` to step it down; `text-13` doesn't override here.

API `EmptyDescription` (extends <div> (typed as <p> props)):
- `className?: string`. Merged after the defaults.

API `EmptyContent` (extends <div>):
- `className?: string`. Add `flex-row` to set two actions side by side.

### Stat strip

- Level: Molecule
- Category: Data display
- Status: Stable
- Import: `@oration/canon/components/stat`
- Exports: `Stat`, `StatStrip`, `StatDelta`
- Docs: /design/components/stat

Stat strip is how Oration shows a handful of headline metrics: `Stat` cells set side by side in a `StatStrip`, each with a label, a tabular value, an optional change and a small trend line, divided by hairlines on one card. It sits at the top of analytics, queue and report pages, where call volume, containment and handle time are read together. The mistake it exists to prevent is the hero-metric grid: a mosaic of cards, each with a huge number, a tiny label and a colored trend chip. Canon refuses that pattern; metrics are a strip, a row, a table or a real chart.

When to use:
- For three to six headline metrics at the top of an analytics, queue or report page: Calls, Containment, Avg handle time, Transfers.
- When each figure needs its change against a period and a glance at its trend.
- Inside a card, under its section header, with `framed={false}` so the strip shares the card's surface.
- When a metric needs its definition one click away, through an `InfoTip` in `info`.

When not to use:
- For label and value pairs with no change or trend, such as a report summary under a title. Use /design/components/inline-stat-strip instead.
- For a big-number card per metric in a grid. Canon refuses hero-metric grids; use this strip instead.
- For a metric over time that people read closely. Draw a real chart. Use /design/components/chart instead.
- For one share of a whole with a legend, such as containment by outcome. Use /design/components/radial-chart instead.
- For a quota or budget against a limit. Use /design/components/meter instead.
- For per-row figures in a list. Put them in table columns, right aligned. Use /design/components/table instead.

Rules:
- No hero-metric grids: Big number, tiny label, trend chip, repeated in a grid of cards: Canon refuses it. Show metrics as a stat strip, rows, a table or a real chart.
- The Tabular Figures Rule: Every number that changes or gets compared is set in tabular figures. Values and deltas in a stat are `tabular-nums`, so a strip that updates doesn't jitter.
- The Ink Fill Rule: Trend lines are Ink 65. Green and red belong to the delta, and only when you've said whether the change is good news.
- The Label-Beside-Color Rule: A delta always shows its arrow and its amount, and the label names what's measured, so the number reads without the green or red.

Anatomy:
- Strip: `StatStrip`: a grid on Card White with 12px corners and the hairline lift, one equal column per stat from 640px and two up below.
- Label: 12px Slate Meta on a 16px row. Names what's measured, and truncates if the cell is narrow.
- Info tip: Optional, from `info`. Usually an `InfoTip` that defines the metric, such as containment or AHT.
- Value: 18px at weight 600 with tightened tracking, tabular figures, on a 28px row.
- Delta: Optional. A 12px arrow and amount in Ledger Green, Signal Red or Slate Meta, followed by an optional comparison such as vs last week.
- Trend: Optional. A 64 by 24px Mini chart line in Ink 65, pushed to the right edge. Hidden below 640px.
- Divider: A 1px Hairline between cells: vertical in one row, and a grid of rules when the strip wraps two up on phones.

States:
- Rest: Label, value and any delta and trend, 16px by 12px padding per cell.
- Loading: `SkeletonStat` with the same count and `trend` flag. Its rows are the same 16px and 28px tall, so nothing shifts when data arrives.
- Good change: `good: true`: the arrow and amount turn Ledger Green, whether the direction is up or down.
- Bad change: `good: false`: the arrow and amount turn Signal Red.
- Neutral change: `good` left unset: the arrow and amount stay Slate Meta. Use it when more isn't better or worse, such as invoices received.
- No change: `direction: "flat"`: a dash icon in Slate Meta, spoken as No change.
- No trend: With fewer than two points, the trend is left out and the value row keeps its height.
- No data: Show an en dash as the value and leave out the delta. Don't show 0 for a metric that wasn't measured.
- Phone: Below 640px the strip is two columns with hairlines between rows, and trends are hidden.

Behavior:
- `Stat` reads a context from `StatStrip`. Inside a strip it renders a `div` of `dt` and `dd` with cell padding and dividers; on its own it renders its own `dl` with no padding.
- The strip is `grid-cols-2` below 640px and one auto-sized row from 640px (`sm:grid-flow-col sm:auto-cols-fr`). Every stat gets an equal share, however many there are.
- `format` runs only when `value` is a number. Strings render as given, which is what most call sites pass.
- The delta's color comes from `good`, not from `direction`: handle time going down is `good: true` and turns green.
- The delta is drawn `aria-hidden` and spoken from a screen-reader sentence: Up 6% vs last Monday, No change vs last week.
- The trend is a decorative Mini chart, since the value and delta already say what it shows.
- `framed={false}` drops the card surface so the strip can sit inside a card; add `border-t border-border` when it sits under a header.

Do and don't:
- Do: Set metrics in one strip on one card, divided by hairlines.
- Don't: Build a grid of hero cards with a big number, a tiny label and a colored chip. It's the pattern Canon refuses.
- Do: Set `good` from what the change means. Handle time going down is good news, so it's green.
- Don't: Color by direction. Red for every downward arrow tells the team their faster calls are a problem.
- Do: Say what the change is compared with, in the delta label or once above the strip.
- Don't: Show a bare 3 pts with no comparison anywhere. Down from what?

Content:
- Labels are short nouns in sentence case: Calls, Containment, Avg handle time, First-response SLA. No units in the label when the value carries them.
- Values carry their unit: 71%, 4:12, 820 ms, $4.82M, 3h 10m. Round to what a person compares, not to the database's precision.
- Deltas use the value's unit: points for percentages (2 pts), time for durations (0:18), percent for counts (6%). The arrow gives the sign, so no plus or minus.
- Comparisons start with vs: vs last week, vs last Monday. When every stat shares one, say it once above the strip.
- Define jargon in the `info` tip: Containment, AHT, Service level, FCR.

Accessibility:
- The strip is a description list: each label is a `dt` and its value and delta are the `dd`. Give the strip an `aria-label` that says what and when, such as Supplier line agents, today.
- The delta is announced as a sentence (Down 0:18 vs last week) instead of an arrow glyph and a bare number.
- The trend line is hidden from assistive tech; the value and delta already carry what it shows.
- `InfoTip` in `info` is a 16px button named About plus its title, with an extended hit area.
- Deltas pair color with an arrow and an amount; the label names the metric, so the strip reads in grayscale.

Known gaps (follow the system, not the gap):
- Whether a change is good news is carried by color alone. The arrow shows direction, not verdict, and the spoken sentence (Up 140 ms vs last week) doesn't say good or bad either.
- In a narrow cell the value truncates first: the delta and trend don't shrink, so a four-up strip in a 48rem column can cut 1,284 to 1,2…. Drop the trend or the comparison label before that happens.
- The two-up layout keys off the viewport (`max-sm:`), not the strip's width, so a strip in a narrow rail on a desktop stays one row and truncates.
- `format` is ignored for string values, and nearly every call site preformats, so number formatting is repeated per page instead of living with the stat.

API `Stat`:
- `label: string`. What's measured. Also names the trend chart.
- `value: ReactNode`. The figure, usually a preformatted string.
- `delta?: StatDelta`. The change against a period. See `StatDelta`.
- `trend?: number[]`. Points for the sparkline, oldest first. Needs at least two.
- `info?: ReactNode`. Rendered beside the label, usually an `InfoTip`.
- `format?: (value: number) => string`. Formats a numeric `value`. Ignored for strings.
- `className?: string`. Merged onto the cell.

API `StatDelta`:
- `value: string`. The amount of change without a sign: `6%`, `2 pts`, `0:18`.
- `direction: "up" | "down" | "flat"`. Picks the arrow or dash.
- `good?: boolean`. Whether this direction is good news. Unset for a neutral change.
- `label?: string`. The comparison, such as `vs last week`.

API `StatStrip` (extends <dl>):
- `framed?: boolean` = true. Sets the strip on a card surface. Turn it off inside a card.
- `aria-label?: string`. What the metrics describe and for when.
- `className?: string`. Merged after the grid classes; call sites use it for a three-up tablet layout.

### Inline stat strip

- Level: Molecule
- Category: Data display
- Status: Beta
- Import: `@oration/canon/components/inline-stat-strip`
- Exports: `InlineStatStrip`, `InlineStat`
- Docs: /design/components/inline-stat-strip

Inline stat strip is a single ruled line of label and value pairs: Runs 18, Invoices paid 3,912, Amount paid $4.82M of $4.90M scheduled. It summarizes a report, a record or a page section right under its title, in the page's own flow rather than on a card. It has no deltas, trends or definitions; the moment a figure needs its change against last week, it belongs in a Stat strip. The usual mistake is the opposite shortcut, joining the figures into one dot-separated sentence.

When to use:
- Under a report title, to summarize what the charts below show: Runs, Invoices paid, Amount paid.
- In a record header, for the few facts people check first: Open invoices, Avg days to pay, Last payment.
- When a value needs one piece of context, such as of $4.90M scheduled or 71%, through `detail`.
- For three to six figures that read left to right and may wrap on narrow screens.

When not to use:
- When figures need a change against a period or a trend line. Use /design/components/stat instead.
- For a line of small metadata under a name in a list row. Use /design/components/meta instead.
- For many attributes of a record that people edit. Use the attribute rail or a table. Use /design/components/table instead.
- For one ratio with a legend. Use /design/components/radial-chart instead.
- For a big-number card per figure. Canon refuses hero-metric grids.

Rules:
- The Layout Over Punctuation Rule: Metadata is never joined into dot-separated strings (A · B · C). Each figure gets its own label and value, separated by space.
- The Tabular Figures Rule: Values are set in tabular figures so a strip that updates, or two strips stacked on a page, line up.

Anatomy:
- Rules: A 1px Hairline above and below, with 12px of padding inside. They're structural dividers, not a card.
- Label: A `dt` in 12px Slate Meta.
- Value: A `dd` in 14px at weight 500, tabular figures. Can be any node, such as a status label.
- Detail: Optional. The same line in weight 400 Slate Meta after a space: of 1,284, 71%, $38,210.00.
- Gap: 40px between pairs, 12px between rows when the line wraps. No separators.

States:
- Rest: One line of pairs between two hairlines.
- Wrapped: When the pairs don't fit, they wrap to a second row 12px below. Order stays left to right, top to bottom.
- Loading: There's no built-in skeleton. Draw one in the same layout: the two hairlines, a 12px label bone and a 16px value bone per pair.
- No data: Show an en dash as the value for a figure that wasn't measured. Keep the label so the line doesn't reflow.

Behavior:
- Pass `stats` as an array of `{ label, value, detail? }`. The strip renders them in order; `label` is also the React key, so labels must be unique.
- The strip is `flex flex-wrap`, so it never scrolls horizontally; it wraps.
- `value` and `detail` accept nodes, so a value can be a `StatusLabel` or a link.
- It takes no `className` or other props. Wrap it in an element to position it.

Do and don't:
- Do: Give each figure its own label and value, separated by layout.
- Don't: Join them into 18 runs · 3,912 invoices · $4.82M paid. It reads as one sentence and breaks the Layout Over Punctuation Rule.
- Do: Use `detail` for context that belongs to the value: the total it's part of, or its share.
- Don't: Put a colored change in `detail`. Once a figure needs its change, move to a stat strip with a real delta.

Content:
- Labels are short nouns in sentence case: Runs, Invoices paid, Avg days to pay. No colons.
- Values carry their unit and are rounded for reading: $4.82M, 27, Sep 25, 1d 4h.
- Detail is a fragment that completes the value: of $4.90M scheduled, 71%, of 1,284. No parentheses.
- Keep the same labels in the same order across related reports, so the eye finds them in the same place.

Accessibility:
- The strip is a description list: each label is a `dt`, each value and detail a `dd`, so screen readers pair them.
- It has no accessible name of its own. The heading above it provides the context; keep the strip right after that heading.
- Values and details are text, so they read in grayscale. A status value should be a `StatusLabel`, dot plus text.
- Nothing in it is interactive unless you pass a link as a value.

Known gaps (follow the system, not the gap):
- `InlineStatStrip` takes only `stats`: no `className`, no `aria-label` and no `data-slot`. The rules above and below can't be turned off, so inside a card it draws two extra dividers.
- The one import site, `reports/report-parts.tsx`, re-exports it as `StatStrip` and its type as `Stat`, the same names as the stat strip component. Reports code reads as if it used the other component.
- `components/agents/list/stat-strip.tsx` in the app is a hand-rolled copy of the same markup instead of an import.
- Stats are keyed by `label`, so two pairs with the same label collide.

API `InlineStatStrip`:
- `stats: InlineStat[]`. The pairs, in reading order.

API `InlineStat`:
- `label: string`. What the figure is. Also the React key, so keep it unique.
- `value: ReactNode`. The figure, preformatted.
- `detail?: ReactNode`. Context after the value in Slate Meta.

### Mini chart

- Level: Molecule
- Category: Data display
- Status: Stable
- Import: `@oration/canon/components/mini-chart`
- Exports: `MiniChart`, `monotonePath`
- Docs: /design/components/mini-chart

Mini chart is a sparkline in line, area or bar form, sized to sit in a stat, a table cell or a panel: supplier calls per day, containment over two weeks, first-response SLA by queue. It draws in Ink 65 by default and turns green, amber or red only when the series is itself a verdict. It shows shape, not values, so it always travels with the number and label it summarizes. The common mistake is coloring it for decoration, in indigo or in green for a series that isn't good or bad.

When to use:
- Beside a figure to show its recent shape: calls today next to 14 days of calls.
- In a table column, one per row, to compare trends across queues, agents or suppliers.
- In a stat, through `Stat`'s `trend` prop, which draws a 64 by 24px line for you.
- In a panel or insight card with `interactive`, so people can read each day's value on hover or with the arrow keys.
- As bars when the periods are discrete counts, such as transfers per day.

When not to use:
- For a chart people read closely, with axes, a legend or several series. Use /design/components/chart instead.
- For one share of a whole, such as containment out of all calls. Use /design/components/radial-chart instead.
- For a good, fair or poor verdict per day, such as uptime. Use /design/components/health-bar instead.
- For per-turn latency on a call. Use /design/components/latency-sparkline instead.
- For a value against a limit or quota. Use /design/components/meter instead.

Rules:
- The Ink Fill Rule: Series are drawn in ink steps: a 1.5px line in Ink 65, an area at 8%, bars at Ink 45. A tone turns semantic only when the series is a verdict, and it is never indigo.
- The Label-Beside-Color Rule: A green, amber or red sparkline sits beside a status label that says the verdict in words: On track, Slowing, Rising.
- The Tabular Figures Rule: The interactive readout and the figures beside a chart are set in tabular figures.

Anatomy:
- Line: A 1.5px monotone curve with round caps, in Ink 65 or the tone's solid color. It never overshoots the data.
- Area: `type="area"` fills under the line at 8% ink, or 14% of a semantic tone.
- Marker: A 4.5px dot on the latest point (`showLast`) or any point (`highlightIndex`), with a 1.5px card-colored ring.
- Bars: `type="bar"`: one bar per point with 2px gaps (1px past 24 bars), from a zero baseline, at Ink 45 or 70% of a tone.
- Emphasized bar: The marked bar at 80%; every other bar dims to 25% so it stands out.

States:
- Rest: The series in its tone, no marker.
- Marked: `showLast` or `highlightIndex` adds the dot on a line or area, or emphasizes one bar.
- Hover: With `interactive`, a 1px Firm Hairline crosshair follows the pointer, the point under it is marked, and a Graphite Ink readout shows its label and value above.
- Focus visible: A 2px Focus Indigo outline 2px outside the chart. Focus marks the latest point and shows its readout.
- Keyboard scrub: Arrow keys move the marked point; the readout and a polite live region update with each step.
- No data: An empty `data` array draws a dashed Firm Hairline across the middle.
- One point or no change: One point draws only its marker. A flat series draws a level line through the middle instead of pinning to an edge.

Behavior:
- Width and height are fixed pixel sizes (96 by 28 by default). The chart doesn't stretch to its container; measure the container and pass `width` when it has to fill.
- Line and area scale to the series' own minimum and maximum, so small changes read as shape. Bars scale from zero, so their heights compare honestly.
- `interactive` makes the chart focusable (`tabIndex=0`) and adds pointer scrubbing, a crosshair and a readout. `labels` names each point in the readout; `formatValue` formats the number.
- Arrow Right and Arrow Up step forward, Arrow Left and Arrow Down step back, Home and End jump to the first and last point.
- `decorative` hides the chart from assistive tech and turns off focus. `Stat` and the health bar tooltip use it, because their text already says what the line shows.
- `tone="current"` draws in `currentColor`, for charts inside a tooltip or other inverted surface.
- `monotonePath(points)` is exported for drawing the same curve in your own SVG.

Do and don't:
- Do: Draw series in ink. The shape is the message.
- Don't: Color a sparkline indigo with `tone="current"` and a `text-primary` wrapper. Indigo is for action and selection, never for data.
- Do: Use a semantic tone when the series is a verdict, and say the verdict beside it.
- Don't: Paint call volume green. More calls isn't good or bad news, and the color claims it is.

Content:
- `ariaLabel` names the series and the window: Supplier calls per day, Sep 15 to Sep 28. Not Chart or Sparkline.
- `labels` are short dates or periods: Sep 21, Mon, Sep 21, Week of Sep 14.
- `formatValue` adds the unit, so the readout stands alone: 46% transferred, 1,284 calls, 820 ms.
- Put the current figure and the window in text next to the chart: 1,284 today, Last 7 days.

Accessibility:
- By default the chart is `role="img"` with your `ariaLabel`. Pass `decorative` when a nearby label and value already say what it shows, so it isn't announced twice.
- An interactive chart is a single tab stop. Its readout is mirrored in a `role="status"` region, so each arrow-key step is announced.
- The readout is drawn with `aria-hidden`; the live region carries the same text.
- The chart only shows shape. Give the actual figure in text beside it; a screen reader can't read a curve.
- Semantic tones always sit beside a status label, so the verdict reads without color.
- Tab: Focuses an interactive chart and marks its latest point.
- →: Marks the next point. Arrow Up does the same.
- ←: Marks the previous point. Arrow Down does the same.
- Home: Marks the first point.
- End: Marks the last point.

Known gaps (follow the system, not the gap):
- The chart has a fixed pixel width. The app wraps it to fill a container twice over: `FluidMiniChart` in the agent overview and a `useElementWidth` hook in the Copilot insight chart.
- The interactive chart is `role="img"` with arrow-key scrubbing, so screen readers don't announce it as something that responds to keys; only the live region reveals it.
- The readout is a custom span above the chart rather than the Tooltip component, so a parent with `overflow: hidden`, such as a table's scroll wrapper, clips it.

API `MiniChart`:
- `data: number[]`. The series, oldest first.
- `ariaLabel: string`. Names the series and window. Ignored when decorative.
- `type?: "line" | "area" | "bar"` = "line". Line for trends, area for volume, bar for discrete counts.
- `width?: number` = 96. Width in pixels.
- `height?: number` = 28. Height in pixels.
- `tone?: "ink" | "success" | "warning" | "danger" | "current"` = "ink". Ink unless the series is a verdict. `current` follows the text color.
- `showLast?: boolean` = false. Marks the latest point or bar.
- `highlightIndex?: number`. Marks one point or bar by index.
- `interactive?: boolean` = false. Adds hover and keyboard scrubbing with a crosshair and readout.
- `labels?: string[]`. A label per point for the readout, such as dates.
- `formatValue?: (value: number) => string` = toLocaleString("en-US"). Formats values in the readout.
- `decorative?: boolean` = false. Hides it from assistive tech when nearby text carries the data.
- `className?: string`. Merged onto the outer span.

API `monotonePath`:

### Radial chart

- Level: Molecule
- Category: Data display
- Status: Beta
- Import: `@oration/canon/components/radial-chart`
- Exports: `RadialChart`
- Docs: /design/components/radial-chart

Radial chart is a ring that shows one share of a whole: 71% of calls contained, 94% of tickets answered within the first-response SLA, 4 of 6 setup steps done. The fill is Ink 65 on a Well Gray track, with the figure in the middle, and it turns green, amber or red only when the share is a verdict against a target. Use it for the one ratio a panel is about, next to a legend or a sentence that explains it. It is not a donut of several categories and not a gauge for a count with no whole.

When to use:
- For the one ratio a panel is about: Containment, 7 days with 71% in the ring and the breakdown beside it.
- For a score out of a fixed maximum, such as a QA score of 92 of 100, in a verdict tone.
- For progress through a small number of whole steps with `segments`: 4 of 6 setup steps, 5 of 7 days within SLA.
- As a 40px ring on a link card that leads to the rest of a checklist.

When not to use:
- For a share that sits in a row of other metrics. Use /design/components/stat instead.
- For a value against a quota or budget, such as credits used. Use /design/components/meter instead.
- For how a value changed over time. Use /design/components/mini-chart instead.
- For progress through an ordered pipeline with named stages. Use /design/components/stepper instead.
- For several categories of one whole. Draw a real chart or a stacked meter. Use /design/components/chart instead.

Rules:
- The Ink Fill Rule: The arc is Ink 65 on a Well Gray track. Success, warning and danger tones are for a share that is a verdict against a target, such as a passing QA score. It is never indigo.
- The Label-Beside-Color Rule: A colored ring always sits beside words that give the verdict: Passed, Near target, Behind. The figure in the middle is not enough on its own.
- The Tabular Figures Rule: The label and sublabel are set in tabular figures, so a ring that updates doesn't jitter.

Anatomy:
- Track: The full circle in Well Gray. Its thickness defaults to one eleventh of the size, at least 3px.
- Arc: The share, from 12 o'clock clockwise, with round caps. Ink 65 by default.
- Label: Optional. The figure in weight 600 and tabular figures: 20px from a 96px ring, 14px from 56px, 12px below.
- Sublabel: Optional. 11px Slate Meta under the label: contained, of 100, within target.
- Segments: With `segments`, the ring splits into equal arcs with small gaps; whole steps fill in the tone and the rest stay Well Gray.

States:
- Empty: A value of 0 draws the track alone.
- Partial: The arc covers the share, clamped to 0 to 1.
- Full: A value of 1 closes the ring.
- Filling: On first mount the arc sweeps from zero on a 0.5s spring with no bounce. Segments fade in one after another over about a third of a second.
- Updating: A new value animates from the old one on the same spring, so a changed date range reads as a change.
- Reduced motion: The arc and segments appear at their value with no sweep or fade.

Behavior:
- `value` is a share from 0 to 1. Anything outside is clamped and a non-number draws as 0.
- `size` is the ring's width and height in pixels (56 by default); `thickness` overrides the stroke.
- `segments` above 1 turns the ring into that many equal arcs, up to 60. The filled count is `value × segments`, rounded to the nearest whole step.
- `label` and `sublabel` accept nodes, so the label can be a larger figure such as a QA score.
- The ring is drawn with Motion; `MotionConfig reducedMotion="user"` in the app shell turns off the sweep.

Do and don't:
- Do: Show one ratio per ring, with the rest of the breakdown written beside it.
- Don't: Nest rings for several categories. Concentric arcs can't be compared and the colors say nothing.
- Do: Use a ring for a share of a whole, with its percentage in the middle.
- Don't: Put a count in a ring. 1,284 calls isn't a share of anything, so the arc is invented.

Content:
- Label: the figure, rounded to a whole percent unless the decimal matters: 71%, 92, 4.
- Sublabel: one or two words that complete it: contained, of 100, of 6, within target.
- `ariaLabel` says the whole thing in words, including what it measures and the window: 71% of supplier calls contained, last 7 days.
- When the ring is a verdict, write the verdict beside it: Passed, Near target, Behind.

Accessibility:
- The ring is `role="meter"` with `aria-valuemin` 0, `aria-valuemax` 100 and the value as a whole percent in `aria-valuenow` and `aria-valuetext`.
- The label and sublabel are hidden from assistive tech, so put their meaning in `ariaLabel`: a QA score of 92 is announced as QA score 92 of 100, 92% only if you write it.
- The fill animation respects reduced motion.
- Colored rings sit beside a status label, so a failing score doesn't depend on red.
- A ring inside a link card is described by the card's text; keep `ariaLabel` short there so the link doesn't read twice.

Known gaps (follow the system, not the gap):
- The accessible value is always a percent. A segmented ring labelled 4 of 6 is announced as 67%, and a score of 92 as 92% unless `ariaLabel` spells it out.
- Segments round the filled count: a value of 0.75 on a 6-segment ring fills 5 segments while `aria-valuenow` says 75.
- Label size steps at fixed ring sizes (96 and 56px). Between them, such as a 72px ring, the label stays 14px, and below 56px a label like 100% crowds the ring; the product leaves the label off at 40px.

API `RadialChart`:
- `value: number`. The share, from 0 to 1.
- `ariaLabel: string`. What the share measures, in words.
- `size?: number` = 56. Width and height in pixels.
- `thickness?: number` = max(3, round(size / 11)). Stroke width in pixels.
- `label?: ReactNode`. The figure in the middle.
- `sublabel?: ReactNode`. A word or two under the label.
- `tone?: "ink" | "success" | "warning" | "danger"` = "ink". Ink unless the share is a verdict.
- `segments?: number`. Splits the ring into this many whole steps (2 to 60).
- `className?: string`. Merged onto the outer element.

### Health bar

- Level: Molecule
- Category: Data display
- Status: Stable
- Import: `@oration/canon/components/health-bar`
- Exports: `HealthBar`, `HealthPoint`, `HealthStatus`
- Docs: /design/components/health-bar

Health bar is a row of thin ticks, one per period, each colored by its verdict: good, fair or poor. Under it, the counts are written out (27 good, 2 fair, 1 poor), so the status never rides on color alone. Hover or focus a tick for its date, value and the trend around it. It answers "how has this been lately" for uptime, agent health or SLA attainment per day; the mistake is hiding the counts in a table and leaving a strip of colored ticks as the only signal.

When to use:
- For a per-day verdict over the last two to four weeks: supplier portal uptime, ERP sync health, first-response SLA per day.
- In agent lists and leaderboards, one bar per agent, so a bad day stands out down the column.
- When each period is a verdict against a threshold, not just a number.
- When people need the exact value for one period on hover or focus, without leaving the list.

When not to use:
- For a value over time with no threshold. Show its shape with a sparkline. Use /design/components/mini-chart instead.
- For the current status only. Say it with a dot and a label. Use /design/components/status-label instead.
- For one share of a whole, such as containment this week. Use /design/components/radial-chart instead.
- For per-turn latency on one call. Use /design/components/latency-timeline instead.
- For more than about 45 periods in a narrow column. Aggregate to weeks, or draw a chart. Use /design/components/chart instead.

Rules:
- The Label-Beside-Color Rule: Ticks are colored, so the counts are written beside them by default. When you turn the summary off in a table, the row must say the status in words elsewhere.
- The Ink Fill Rule: Health ticks are one of the places a fill turns semantic, because each period is a verdict. Ledger Green for good, Caution Amber for fair, Signal Red for poor; never indigo or a categorical hue.

Anatomy:
- Good tick: A fully rounded bar in Ledger Green. Ticks share the width equally with 2px gaps and are 20px tall by default.
- Fair tick: Caution Amber, for a period that missed but didn't fail.
- Poor tick: Signal Red, for a period that failed its threshold.
- Summary: 12px Slate Meta counts in tabular figures, such as 12 good, 1 fair, 1 poor, or your own sentence. It describes the bar for screen readers too.

States:
- Rest: Every tick at full color, the summary below.
- Hover: The hovered tick stays at full color and every other tick fades to 40% over 80ms. A tooltip shows the period, a status dot and label, the value and a small trend of the surrounding points.
- Focus: One tick is in the tab order (the latest). Focusing it shows the same tooltip and fade as hover.
- Keyboard moves: Arrow keys move focus tick by tick, Home and End jump to the first and last; the tooltip follows focus.
- No summary: `summary={false}` hides the counts line, for table cells where the row states the status elsewhere.
- No data: An empty `points` array draws no ticks and the summary reads No data yet.

Behavior:
- Each tick is a button wrapped in a Tooltip with no open or close delay. The tooltip's trend is a Mini chart in `currentColor` of up to `trendWindow` points either side, with the current point marked.
- The bar uses a roving tab index: one Tab stop for the whole bar, arrow keys inside it. Focus starts on the latest point.
- Each tick's hit area extends 6px above and below, so thin ticks are still easy to point at.
- `statusLabels` renames the three statuses in the tooltip, the accessible names and the default summary: Operational, Degraded and Outage, or Healthy, Watch and Low.
- `formatValue` writes each value with its unit in tooltips and tick names, such as 97.4% uptime.
- `summary` replaces the counts with your own text; `false` removes the line and its `aria-describedby`.
- You decide each point's status. Keep the thresholds in one place so the same value never reads as good in one list and fair in another.

Do and don't:
- Do: Keep the counts under the bar, so the status reads in words.
- Don't: Turn the summary off and leave the ticks alone. Red and green are the only signal, and they fail in grayscale.
- Do: Size the bar so each tick is about 4 to 8px wide: 30 days in 15 to 20rem.
- Don't: Squeeze 90 days into 10rem. Ticks turn into hairlines that can't be seen or pointed at.

Content:
- `ariaLabel` names what's measured and the window: Supplier portal uptime per day, Aug 30 to Sep 28.
- Point labels are the period: Sep 21, Week of Sep 14.
- Status labels are one word, from the reader's point of view: Operational, Degraded, Outage. Keep them the same everywhere the metric appears.
- A custom summary is one sentence with figures: Missed the 90% target on 2 of 14 days, most recently Sep 24.

Accessibility:
- The bar is a `role="group"` with your `ariaLabel`, described by the summary line.
- Each tick is a button named with its label, value and status: Sep 21: 97.4% uptime, Outage.
- One tick is in the tab order; arrow keys, Home and End move between ticks, so a 30-day bar is one Tab stop.
- The tooltip repeats the status in words next to its dot.
- The counts line says the status in words for sighted readers; keep it unless the row says it another way.
- Ticks have no focus style of their own and rely on the browser's default outline, tinted Focus Indigo at 50% by the base styles.
- Tab: Focuses the bar's current tick, the latest by default.
- →: Moves to the next period. Arrow Down does the same.
- ←: Moves to the previous period. Arrow Up does the same.
- Home: Moves to the first period.
- End: Moves to the latest period.

Known gaps (follow the system, not the gap):
- The agents table and the analytics leaderboard pass `summary={false}` with no status text in the row, so the ticks are color only there. That breaks the Label-Beside-Color Rule.
- Ticks have no `focus-visible` style of their own; focus shows as the browser's default outline tinted by the base `outline-ring/50`, not the 3px Focus Indigo ring other controls use.
- Ticks stretch to share the bar's width with no minimum or maximum. Past about 45 points in a narrow column they shrink to hairlines; a short series in a wide column, such as 14 days across 30rem, turns into round pills instead of thin ticks. Set a width on the bar to keep ticks around 4 to 8px.

API `HealthBar`:
- `points: HealthPoint[]`. One point per period, oldest first.
- `ariaLabel: string`. Names what's measured and the window.
- `height?: number` = 20. Tick height in pixels. 16 in table rows.
- `statusLabels?: Partial<Record<HealthStatus, string>>` = { good: "Good", fair: "Fair", poor: "Poor" }. Names for each status.
- `formatValue?: (value: number) => string` = toLocaleString("en-US"). Formats values in tooltips and tick names.
- `summary?: ReactNode | false`. Replaces the counts line. `false` hides it; leave it on unless the row states the status.
- `trendWindow?: number` = 6. Points either side of a tick in its tooltip trend.
- `className?: string`. Merged onto the outer element; set a width here.

API `HealthPoint`:
- `label: string`. The period, such as `Sep 21`.
- `value: number`. The measured value, shown through `formatValue`.
- `status: "good" | "fair" | "poor"`. The verdict for the period. You set the thresholds.

### Timeline

- Level: Molecule
- Category: Data display
- Status: Beta
- Import: `@oration/canon/components/timeline`
- Exports: `Timeline`, `TimelineItem`, `TimelineHeader`, `TimelineTime`, `TimelineBody`
- Docs: /design/components/timeline

Timeline is a vertical list of dated events on a thin rail: who changed a ticket's status, when an SLA breached, when a payment run was approved and sent. Each event is one sentence with the actor and the object in medium weight, a 28px icon disc on the rail and the time at the right. It's the activity log on ticket and record pages and the overnight feed on Home. The common mistake is writing events as dot-joined fragments, or coloring every icon; tones are for verdicts such as a breach or a resolution.

When to use:
- For a record's history: status changes, assignments, labels, SLA events on a ticket.
- For the steps of a run in order: scheduled, approved, remittances sent, payments failed.
- For a feed of what happened overnight across accounts, with the company linked in each event.
- When an event carries a note or a reply that people read in place, through `TimelineBody`.

When not to use:
- For a plan or checklist whose steps tick from queued to done. Use /design/components/task-list instead.
- For progress through named stages of a pipeline. Use /design/components/stepper instead.
- For a conversation between people. Use message rows. Use /design/components/message instead.
- For a call's transcript with speakers and timestamps. Use /design/components/live-transcript instead.
- For a sortable log with many columns, such as webhook deliveries. Use /design/components/data-grid instead.

Rules:
- The Layout Over Punctuation Rule: Events are sentences, never dot-joined fragments. Priya Raman assigned it to Aisha Bello with the time set apart by layout, not Priya Raman · Assigned · 9:18 AM.
- The Quiet Indigo Rule: The `primary` tone is for live state with a label, such as an agent on a call right now. It never decorates agent or enrichment events.
- The Label-Beside-Color Rule: A danger or success icon is backed by the sentence: The first-response SLA breached. The color confirms it; the words carry it.

Anatomy:
- Icon disc: A 28px circle on the White Plane with the hairline lift, holding a 14px icon in Slate Meta or the item's tone.
- Rail: A 1px Hairline from under one disc to just above the next. The last item has none.
- Header: `TimelineHeader`: 13px Slate Meta that wraps, with `<strong>` actors and objects in weight 500 Graphite Ink.
- Time: `TimelineTime`: a `<time>` in 12px Faint Slate and tabular figures, pushed to the right edge.
- Body: Optional `TimelineBody`, 8px under the header: a reply, a note in a tint well, or an action.

States:
- Neutral: The default: icon in Slate Meta. Most events.
- Primary: Icon in Quiet Indigo. Only for something live, beside a label that says so.
- Success: Icon in Ledger Green: resolved, passed, sent.
- Warning: Icon in Amber Ink (Caution Amber in dark): at risk, due soon.
- Danger: Icon in Signal Red: breached, failed.
- Last item: No rail below it and no bottom padding.
- Loading: `SkeletonList` with `icon`, which matches the disc and one line per event.
- Empty: An `EmptyState` with the `schedule` illustration: No activity yet and what will show up here.

Behavior:
- Timeline is an ordered list (`<ol>`) of `<li>` items. Order it newest first on record pages and oldest first for the steps of a run.
- Each item is a two-column grid: a 28px column for the disc and the content beside it, 12px apart, 20px between items.
- `TimelineHeader` wraps, and `TimelineTime` sits at the end of the last line with `ml-auto`, so long sentences keep the time at the right.
- Nothing in it is interactive by itself. Put links on the object (a company, a ticket) and buttons in the body.
- No entrance animation. New events can appear at the top without moving focus.

Do and don't:
- Do: Write each event as a sentence, with the actor and object in `<strong>`.
- Don't: Join fragments with dots. Priya Raman · Assigned · Aisha Bello · 9:18 AM reads like a log dump.
- Do: Keep most icons neutral and color only verdicts: a breach in red, a resolution in green.
- Don't: Tint every icon indigo. The one event that matters no longer stands out, and indigo becomes decoration.

Content:
- Past tense, actor first: Aisha Bello changed status from In progress to Resolved.
- System events name the system or say what happened: The first-response SLA breached, Payment status agent created the ticket from a call with Halcyon.
- Bold the actor and the values that changed, not the verb.
- Times: 9:18 AM for today, Sep 25, 2:26 PM for earlier, with a full ISO `dateTime` on the `<time>`.
- Bodies quote the note or reply as written, or give one sentence of context and the action to take.
- Machine strings such as conversation IDs and invoice numbers can go in Geist Mono; names and figures stay in Geist Sans.

Accessibility:
- The list is an `<ol>`, so screen readers announce the number of events and each one's position.
- The icon disc is `aria-hidden`; the header sentence must say what happened, since the icon and tone aren't announced.
- Give `TimelineTime` a `dateTime` so the time is machine-readable, especially for relative labels such as Yesterday.
- Keep the order the reader expects and say it in the section title when it isn't obvious, such as Newest first.
- Buttons and links in bodies need their own names: Retry failed payments, not Retry.

Known gaps (follow the system, not the gap):
- `TimelineHeader` and `TimelineBody` ask for 13px, but they merge classes with `cn` from the `cn` package, which reads `text-13` as a color and drops it beside `text-muted-foreground` and `text-foreground`. Both render at the inherited size, usually 14px.
- Home's overnight feed gives agent and enrichment events `tone="primary"`, which tints their icons indigo as decoration. The Quiet Indigo Rule keeps indigo for live state with a label.
- `TimelineTime` doesn't require `dateTime`, and the overnight feed passes none, so its times aren't machine-readable.
- `icon` is required on every item, even for minor events where a small dot would do.
- There is no timeline skeleton; the ticket activity log borrows `SkeletonList` with `icon`, which is close but draws no rail.

API `Timeline` (extends <ol>):
- `className?: string`. Merged after `flex flex-col`.

API `TimelineItem` (extends <li>):
- `icon: ReactNode`. A lucide icon; it's sized to 14px for you.
- `tone?: "neutral" | "primary" | "success" | "warning" | "danger"` = "neutral". Colors the icon. Neutral unless the event is a verdict or live.
- `className?: string`. Merged onto the `<li>`.

API `TimelineHeader` (extends <div>):
- `className?: string`. Merged after the defaults.

API `TimelineTime` (extends <time>):
- `dateTime?: string`. The ISO date and time, for machines and screen readers.
- `className?: string`. Merged after the defaults.

API `TimelineBody` (extends <div>):
- `className?: string`. Add `rounded-[10px] bg-muted/70 px-3 py-2` for a note in a tint well, or `text-muted-foreground` for a quoted reply.

### Meta line

- Level: Molecule
- Category: Content
- Status: Beta
- Import: `@oration/canon/components/meta`
- Exports: `Meta`
- Docs: /design/components/meta

Meta line is the 12px line of small facts under a name in a list row: Net 30, 14 open invoices, Last paid Sep 25. Its parts are separated by a 12px gap and wrap onto a second line, never joined with dots. It exists so the product never writes Net 30 · 14 open invoices · Last paid Sep 25; each part is its own span and layout does the separating. The other thing to get right is the parts themselves: short noun phrases with their numbers, not bare figures that need a legend.

When to use:
- Under a row's name in a list or settings table: a supplier's terms and open invoices, a passkey's added and last-used dates.
- For a webhook or integration's status, event count and delivery rate, with the status as a status label.
- Under a card title for the two or three facts that tell similar items apart.
- Anywhere you're tempted to join facts with a middle dot.

When not to use:
- For headline figures under a page or report title. Use /design/components/inline-stat-strip instead.
- For metrics with a change and a trend. Use /design/components/stat instead.
- For a sentence that describes the item. Write it as a description line in 13px.
- For values people filter or sort by across many rows. Give them table columns. Use /design/components/data-grid instead.
- For option values such as stage or tier on their own. Use /design/components/tag instead.

Rules:
- The Layout Over Punctuation Rule: Metadata is never joined into dot-separated strings (A · B · C). Separate it with layout, commas or words. Meta is the layout.
- The Tabular Figures Rule: Counts, amounts and rates in a meta line are `tabular-nums`, so a column of rows lines up. Meta doesn't set it for you.
- The Label-Beside-Color Rule: A status in a meta line is a status label, dot plus text, never a colored dot alone.

Anatomy:
- Line: A wrapping flex row in 12px Slate Meta, centered vertically.
- Status part: Optional, usually first: a status label, dot plus text, at 12px.
- Part: A span holding one fact as a short phrase: 6 events, Last paid Sep 25. It can hold an icon or tags.
- Gap: 12px between parts and 2px between lines when it wraps. The only separator.

States:
- One line: Parts sit on one line with 12px gaps.
- Wrapped: When the row is narrow, whole parts move to the next line 2px below. A part never breaks in the middle unless it's longer than the row.
- Emphasized part: A part that's a problem can take a semantic text color, such as a failing delivery rate in Signal Red, beside a status label that says so.

Behavior:
- Meta is a styled `div`; every prop spreads onto it. Put each fact in its own child element so the gap can separate them.
- Text nodes directly inside Meta become flex items too, so `Net 30 · 14 invoices` as one string is still one part. Split it.
- It wraps instead of truncating. If a row must stay one line, truncate the longest part yourself with `truncate` and a `title`.
- Parts can be interactive, such as a link to the queue, but the line itself is not.

Do and don't:
- Do: Set each fact in its own part and let the gap separate them.
- Don't: Join them with middle dots. Net 30 · 14 open invoices · Last paid Sep 25 breaks the Layout Over Punctuation Rule.
- Do: Write each part as a phrase with its noun: 6 open invoices, 27 days to pay.
- Don't: Show bare figures such as 6, 27d and 9/18. Nobody knows which number is which.
- Do: Show a status as a dot with its label: Failing.
- Don't: Show a red dot alone. It fails in grayscale and for anyone who can't tell red from green.

Content:
- Two to four parts. More than that belongs in columns or a detail view.
- Each part is a short phrase, sentence case, no trailing period: Net 30, Added Aug 3, Last used today.
- Numbers carry their noun and are tabular: 14 open invoices, 99.4% delivered.
- Dates are short: Sep 25, today, Mar 12. Keep the same form across rows.
- Commas and words are fine inside a part: 99.4% delivered, 1,208 in 7 days, Assigned to Aisha Bello.
- Put the most distinguishing fact first, and a status first of all.

Accessibility:
- Parts are separated only visually. A screen reader reads the line as one run of words, so write parts that still make sense back to back: Net 30, 14 open invoices, Last paid Sep 25 reads fine; 6 27d 9/18 doesn't.
- Where two parts could run together, such as two numbers, add a visually hidden comma or write the noun into each part.
- Icons inside parts are decorative and `aria-hidden="true"`; the text carries the fact.
- Keep the line in Slate Meta. Don't lighten it to Faint Slate or with opacity; 12px text needs the contrast.
- A status part is a status label, so the state is read aloud as a word, not a color.

Known gaps (follow the system, not the gap):
- Only the settings kit imports Meta, and re-exports it to settings pages. Other lists hand-roll the same `flex gap-x-3 text-xs text-muted-foreground` line.
- The app still has about 20 dot-joined strings that Meta should replace, in the contact center (callback rows, team cells, the monitor sheet, swap requests) and ticketing (view rows, report insights).
- Meta has no `data-slot` and doesn't set `tabular-nums`, so numbers in it only align if each call site adds it.
- Parts are separated for the eye only; there's no built-in separator for screen readers.

API `Meta` (extends <div>):
- `children?: ReactNode`. One element per fact.
- `className?: string`. Merged after the defaults, such as `mt-1`. Use `text-[13px]` rather than `text-13` to change the size; the merge drops `text-13`.

### Item

- Level: Molecule
- Category: Layout
- Status: Experimental
- Import: `@oration/canon/components/item`
- Exports: `Item`, `ItemGroup`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`
- Docs: /design/components/item

Item is a list row: optional media, a title and description, and actions at the right, in one flexible container you can render as a link. Use it for short lists of records inside cards and panels, such as suppliers missing a W-9 or connected channels. It is experimental and not used by the product yet, which hand-rolls the same row, so the defaults still read a little large: pass 13px titles and 12px descriptions for dense rows. Don't reach for it in a data table; grid rows are the data grid's job.

When to use:
- For a short list of records inside a card or panel: suppliers, channels, recent tickets.
- For a navigation row that opens a record or page, rendered as a `Link` through `render`.
- For a settings-style row with media, a label, a description and a switch or button at the right.
- For a single summary row with a header line and a footer line, such as a ticket preview.

When not to use:
- For rows of records with columns people sort, filter and compare. Use /design/components/data-grid instead.
- For a labelled setting in a settings page, with its own layout and description rules. Use /design/components/settings-section instead.
- For a list that people reorder by dragging. Use /design/components/sortable-list instead.
- For items in a menu. Use /design/components/dropdown-menu instead.
- For a larger, standalone block that groups one topic. Use /design/components/card instead.

Rules:
- The Thirteen-Fourteen Rule: Dense rows are 13px with 12px meta. Item's title and description default to 14px, so rows in cards pass `text-[13px]` to the title and `text-xs` to the description.
- The Tint Well Rule: Rows inside a card fill Well Gray on hover and sit flush; they don't become outlined or shadowed mini-cards. Save `outline` for a standalone row on the plane.

Anatomy:
- Container: `Item`: a wrapping flex row with 10px corners and a transparent 1px border that becomes the focus edge. 12px by 10px padding by default.
- Media: `ItemMedia`: an icon, avatar, monogram tile or image. It aligns to the top of the row when a description is present.
- Title: `ItemTitle`: one line, medium weight, truncated with `line-clamp-1`.
- Description: `ItemDescription`: up to two lines of Slate Meta, clamped. Links inside are underlined.
- Actions: `ItemActions`: buttons, switches or a chevron at the right edge, 8px apart.

States:
- Rest: Transparent (default), a hairline border (outline) or Well Gray at 50% (muted).
- Hover: Only when rendered as an anchor: the row fills Well Gray over 100ms. Rows rendered as buttons or divs don't react on their own.
- Focus visible: An indigo border and a 3px Focus Indigo ring at 50%, when the item itself is focusable (a link or a button).
- Disabled: Item has no disabled state. Disable the action inside it and say why in the description.

Behavior:
- `render` swaps the element while keeping the item's classes, so `render={<Link href />}` gives a real link with the hover fill and focus ring. Base UI merges your props with the item's.
- The row wraps: `ItemHeader` and `ItemFooter` take a full row (`basis-full`) above and below the media and content.
- Media shifts down 2px and aligns to the top when the row has a description, so an icon sits beside the title line. `variant="image"` sizes the box to 40, 32 or 24px by item size.
- A second `ItemContent` after the first stops growing (`flex-none`), for a trailing value column such as an amount.
- `ItemGroup` stacks items with 16px between them, 10px when it holds `sm` items and 8px for `xs`. Pass `gap-0` for rows that sit flush inside a card.
- At `size="xs"` inside a dropdown menu (`data-slot="dropdown-menu-content"`), the item drops its own padding and lets the menu item pad it.

Do and don't:
- Do: Set dense rows at 13px with 12px meta, like every other list in a card.
- Don't: Leave the 14px defaults in a dense list. The rows read larger than the table and nav around them.
- Do: Let rows inside a card sit flush and fill Well Gray on hover.
- Don't: Outline and shadow each row inside a card. It turns a list into a stack of nested cards.

Content:
- Titles are the record's name as people know it: Northwind Freight, Chase, ending 4417.
- Descriptions add one fact that explains why the row is here: W-9 expired Aug 31. Two invoices on hold. Keep it to one line in dense lists.
- Action labels start with a verb and fit the row: Request W-9, Open ticket. When the row itself opens something, use a chevron and no label.
- Don't join metadata with dots. Use a comma, a second line or the footer.

Accessibility:
- `ItemGroup` sets `role="list"`, but `Item` sets no role. Pass `role="listitem"` to static items. For link rows, use a `<ul>` of `<li>`s instead of `ItemGroup`, since the role would replace the link's own.
- A navigation row should be a real link: `render={<Link href />}`. Its accessible name is the whole row's text, so keep descriptions short.
- Don't make the row a link and also put buttons inside it; nested interactive elements break. Use a link row with a chevron, or a static row with actions.
- Give switches and inputs in actions a label. In a settings row, a `<label htmlFor>` around the title names the switch.
- Media is decorative when the title names the record: mark icons `aria-hidden` and leave avatars without alt text.
- Tab: Moves to the row when it is a link, then to each action inside a static row.
- Enter: Follows a link row.

Known gaps (follow the system, not the gap):
- Item isn't imported anywhere in apps/web. List rows in cards are hand-rolled, for example `flex items-center gap-2.5 rounded-lg px-2 py-2 hover:bg-muted focus-visible:ring-3 focus-visible:ring-ring/40` on a `Link` in Home, customers and agent health.
- Title and description default to 14px. Dense rows in DESIGN.md are 13px with 12px meta.
- `size="default"` and `size="sm"` produce identical classes (`gap-2.5 px-3 py-2.5`).
- The hover transition is 100ms; DESIGN.md sets hovers at 150ms. The focus ring is 50%, where the hand-rolled rows use 40%.
- Hover only applies when the item is an anchor. A row rendered as a `<button>` gets no hover fill.
- `ItemGroup` is `role="list"` but `Item` never sets `role="listitem"`, so a group of items is an invalid list unless each item passes the role.
- `ItemMedia variant="icon"` only sizes the svg. The Well Gray 32px icon tile DESIGN.md describes has to be added by hand.

API `Item` (extends Base UI `useRender` props for `<div>`):
- `variant?: "default" | "outline" | "muted"` = "default". Transparent, a hairline border, or Well Gray at 50%.
- `size?: "default" | "sm" | "xs"` = "default". Padding and gap. `default` and `sm` are both 12px by 10px today; `xs` is 10px by 8px with 12px descriptions.
- `render?: ReactElement | (props, state) => ReactElement`. Render as another element, usually `<Link href />`. Anchors get the hover fill.
- `className?: string`. Merged into the variant classes. Use `text-[13px]`, not `text-13`, to change the size.

API `ItemGroup` (extends <div>):

API `ItemMedia` (extends <div>):
- `variant?: "default" | "icon" | "image"` = "default". `icon` sizes an unsized svg to 16px. `image` makes a 40, 32 or 24px box with 6px corners that crops an `<img>`.

API `ItemContent` (extends <div>):

API `ItemTitle` (extends <div>):

API `ItemDescription` (extends <p>):

API `ItemActions` (extends <div>):

API `ItemHeader` (extends <div>):

API `ItemFooter` (extends <div>):

API `ItemSeparator` (extends Separator):

### Card

- Level: Molecule
- Category: Layout
- Status: Beta
- Import: `@oration/canon/components/card`
- Exports: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`
- Docs: /design/components/card

A card is the raised container of the ledger: Card White with 12px corners and 16px of padding, lifted off the plane by the hairline lift (`shadow-border`) rather than a border. It groups one topic on a document page, such as a Home rail widget, a report panel or a record summary. Build it with `Card`, which draws the surface (`rounded-xl bg-card shadow-border`) and leaves padding to you: `p-4` for a document card, none for a `divide-y` list or a toolbar-and-table frame. Swap the element with `render`, such as `render={<section aria-labelledby={id} />}` or a Next `Link` with an `href`. The mistake people make is nesting: a region inside a card is a 70% Well Gray tint well or a hairline split, never a second card.

When to use:
- To group one topic on a document page: a Home rail widget, a report panel, a record summary.
- To hold a short list with its own header and a quiet destination link, like Callbacks due today with All callbacks.
- As the frame around a toolbar and table on a document page, with `overflow-hidden` so rows reach the 12px corners.
- As an interactive tile that opens something, such as an agent template, lifting to the hover shadow.

When not to use:
- For a sub-region inside a card. That is a tint well. Use /design/components/well instead.
- For headline metrics. Show them as a stat strip, not a grid of big-number cards. Use /design/components/inline-stat-strip instead.
- For an option someone selects in a form. Use /design/components/choice-card instead.
- For a settings group of labelled rows and controls. Use /design/components/settings-section instead.
- For content that floats above the page, such as a menu or a preview. Use /design/components/popover instead.
- For a list or grid with nothing in it yet. Use /design/components/empty instead.

Rules:
- The Hairline-and-Lift Rule: A raised surface takes its edge and its lift from one composite shadow, `shadow-border`, never from a CSS border plus a shadow. CSS borders are for structural dividers only: table rules, header bottoms, section splits.
- The Tint Well Rule: Inside a card, a sub-region is a Well Gray tint at 70% with a 10px radius (`rounded-[10px] bg-muted/70`), never a second bordered or shadowed card.
- No nested cards: A card never sits inside a card. If the inner block needs its own edge, it is a well; if it needs its own lift, it belongs beside the card, not in it.
- No hero-metric grids: Don't tile big-number cards with tiny labels and trend chips. Metrics are stat strips, rows, tables or real charts, usually inside one card.

Anatomy:
- Surface: `rounded-xl bg-card shadow-border`: Card White, 12px corners and the hairline lift. No CSS border.
- Header: A Title (14px, weight 600) on the left and a 12px Slate Meta link or quiet action on the right, on a shared baseline (`items-baseline`).
- Content: 16px padding and 13px copy. Lists inset 8px (`px-2 pb-2`) with 8px-corner rows that fill Well Gray on hover.
- Tint well: A sub-region at `rounded-[10px] bg-muted/70`, 12px by 8 to 10px of padding, for grouped figures or a note.
- Footer: Optional. A hairline top and a Well Gray band at 50% for the card's actions, flush with the bottom corners.

States:
- Rest: Card White on the hairline lift: a 7% ink ring and two soft drops. In dark the ring is a 7% white hairline and the card steps lighter than the plane.
- Hover: Interactive cards only. The shadow deepens to `shadow-border-hover` over 150ms (`transition-shadow duration-150`). Static cards don't react.
- Focus visible: Interactive cards draw a 3px Focus Indigo ring at 40% around the whole card when their stretched link or button has keyboard focus.
- Dragging: Kanban cards and reorderable cards take the hover lift while held.
- Loading: `SkeletonCard` from Skeletons, drawn on the same surface so nothing jumps when data arrives.
- Empty: Keep the card and its header; put an Empty state inside with one sentence and the next action.

Behavior:
- Cards don't animate in when a page loads. Only the hover lift transitions, over 150ms on the house ease-out.
- Add `overflow-hidden` when a toolbar, table or image runs to the edge, so it clips to the 12px corners.
- An interactive card has one stretched target: a link or button whose `after:absolute after:inset-0` covers the card. Other controls on the card sit above it with `relative z-10`.
- In light, Card White equals the White Plane and the card separates only through the lift. In dark, the card steps up in lightness and the ring turns to a faint white hairline.
- The parts pad themselves with `--card-spacing` (16px, 12px at `size="sm"`), so use them on a `Card` without padding: `CardHeader` pads its top and sides, `CardContent` all four, and `CardFooter` is a flush band.
- `CardHeader` becomes a two-column grid when it contains a `CardAction`, with the action on the title's baseline at the top right.
- `interactive` adds the hover lift and the focus ring, both on the card itself and when a stretched `[data-overlay]` target inside it has keyboard focus.
- `resize` tweens the card's width and height when they change, with the Card resize transition from transitions.dev (`.t-resize`, 300ms on `--resize-ease`). It needs explicit sizes on both sides of the change, and turns off for reduced motion.

Do and don't:
- Do: Split a card's inside with a 70% Well Gray tint well at 10px corners.
- Don't: Put a second card with its own lift inside the first. Two edges and two shadows read as clutter.
- Do: Raise the card with `shadow-border` alone.
- Don't: Add a CSS border and a drop shadow. The border doubles the edge and the heavy shadow lifts it far above its neighbours.
- Do: Show a handful of figures as a stat strip inside one card.
- Don't: Tile big-number cards with tiny labels and trend chips. It is a dashboard cliché and hides what matters.

Content:
- Titles name the topic in sentence case, one to four words: Payment runs this week, Callbacks due today.
- The header link names its destination: All payment runs, not View all or See more.
- No eyebrow or kicker above the title. Dates, counts and owners go in a meta line below it or in the rows.
- Keep a card's description to one sentence. If it needs more, the topic is too big for one card.
- Numbers in rows and wells are tabular; amounts keep their cents: $18,420.00.

Accessibility:
- A card is a plain `<div>`. When it stands for a section, render a `<section aria-labelledby>` pointing at its heading, so it appears in the landmarks list.
- Give the heading the right level for the page outline: `h2` for a card on a document page, `h3` for a card inside a titled section.
- Don't wrap a whole card in a `<button>` or `<a>` when it contains other controls; nested interactive elements break. Use one stretched link or button and lift the rest with `relative z-10`.
- The stretched target's name is the card title, so screen reader users hear Overdue W-9 collection, button, not the whole card's text.
- The hover lift is decoration. The card must read and work the same without it, and keyboard focus draws its own ring.
- Tab: Moves to the card's stretched link or button, then to any controls on it.
- Enter: Opens or activates the card.

Known gaps (follow the system, not the gap):
- Five radio option tiles in apps/web (theme, plan, routing, autonomy and agent details) still hand-roll the surface on a `<label>`. They are form options and belong on `ChoiceCard`.
- Product list rows inside cards use 10px corners (`rounded-lg`), where DESIGN.md says 8px. These pages follow DESIGN.md.

API `Card` (extends <div>):
- `render?: ReactElement`. The element to render, such as `<section aria-labelledby={id} />`, `<ul />` or `<Link href="…" />`. Its props merge with the card's.
- `interactive?: boolean` = false. Hover lift to `shadow-border-hover` over 150ms, plus the 3px Focus Indigo ring on the card or a focused `[data-overlay]` target.
- `resize?: boolean` = false. Tweens width and height changes with the Card resize transition (`.t-resize`).
- `size?: "default" | "sm"` = "default". `--card-spacing` for the parts: 16px, or 12px at `sm`. `sm` also drops the title to 13px.
- `className?: string`. Padding, layout and anything else, merged after the surface.

API `CardHeader` (extends <div>):

API `CardTitle` (extends <h2>):
- `as?: "h2" | "h3" | "h4"` = "h2". The heading level. Use `h3` for a card inside a titled section.

API `CardDescription` (extends <p>):

API `CardAction` (extends <div>):

API `CardContent` (extends <div>):

API `CardFooter` (extends <div>):

### Section header

- Level: Molecule
- Category: Layout
- Status: Beta
- Import: `@oration/canon/components/section-header`
- Exports: `SectionHeader`
- Docs: /design/components/section-header

Section header titles a block of a page or a card: a 14px semibold heading, an optional one-line description, and one quiet action on the right. It is how agent detail sections, sequence steps and report panels open. It ships with no layout of its own, so every call site passes the flex row in `className`; forgetting it is the common mistake, and the action drops under the title.

When to use:
- To open a section of a document page: Test scenarios, Payment runs, Caller ID lookup.
- To title a card or report panel, with a one-line takeaway as the description.
- When the section has one action that belongs to it: Add scenario, Export CSV, or a destination link such as All disputes.
- For a sub-section inside a titled section, with `as="h3"`.

When not to use:
- For the page's own title and description. Use /design/components/page-title instead.
- For a settings group with labelled rows under it. Use /design/components/settings-section instead.
- For a block that shows and hides behind its heading. Use /design/components/collapsible instead.
- For the title of a dialog or sheet, which has its own title and description parts. Use /design/components/dialog instead.

Rules:
- The One Filled Button Rule: A section header's action is outline, ghost or a Slate Meta link. The filled button belongs to the view's one main action, which is rarely a section's.
- Sentence case, no eyebrows: Headings are sentence case with nothing above them: no kicker, no uppercase label, no letter-spaced caption.

Anatomy:
- Container: The outer `<div>`. It has no layout; pass `flex items-end justify-between gap-4` (or `items-start`, `items-baseline`) in `className`.
- Title: An `h2` (or `h3` with `as="h3"`) at 14px, weight 600. Pass `id` so the section can be `aria-labelledby` it.
- Description: Optional. A `<p>` in 13px Slate Meta, 2px under the title. One sentence.
- Action: Optional. One outline or ghost button, or a 12px Slate Meta link, at the right.

States:
- Title only: The heading and, if needed, an action, aligned on a shared baseline with `items-baseline`.
- With description: Align the action to the description line with `items-end`, or to the title with `items-start` when the description wraps.
- Narrow: Pass `titleClassName="min-w-0"` so a long description wraps instead of pushing the action out of the row.

Behavior:
- Section header is static: it renders a heading, a paragraph and whatever you pass as `action`. It holds no state.
- `className` goes on the outer `<div>` and `titleClassName` on the wrapper around the heading and description, so layout lives on one and truncation on the other.
- `descriptionClassName` replaces the default (`mt-0.5 text-13 text-muted-foreground`) rather than merging with it. Repeat those classes when you only want to add one, such as `text-pretty`.
- The heading's classes are fixed at `text-sm font-semibold` and can't be overridden from props.

Do and don't:
- Do: Give the header its row: `flex items-end justify-between gap-4`, so the action sits at the right.
- Don't: Render it without a layout class. The action falls under the title and the section reads as two stacked blocks.
- Do: Keep the action quiet: outline, ghost or a Slate Meta link, with the heading alone at the top.
- Don't: Put an uppercase eyebrow above the heading and a filled button beside it. Both compete with the page's real primary action.

Content:
- Titles name the contents in sentence case, one to four words: Payment runs, When the lookup fails.
- Descriptions are one sentence that says what the section is for or what changed: Down to 23 days from 31 in June.
- Action labels are verb first (Add scenario, Export CSV) or name the destination (All disputes, Open report).
- Don't repeat the title in the action: Add under Scenarios is enough context only when nothing else on the page adds.

Accessibility:
- Pass `id` and label the wrapping `<section aria-labelledby={id}>` with it, so the section is a named region. The agent detail `Section` wrapper does exactly this with `React.useId()`.
- Pick the heading level from the page outline: `h2` for sections of a page, `as="h3"` for sections inside them. Don't skip levels to get a smaller look; the size is the same at both levels.
- The description is not linked to the heading. If a control in the section needs it, point that control's `aria-describedby` at the description yourself.
- An icon-only action needs an `aria-label` and a tooltip, like any icon button.

Known gaps (follow the system, not the gap):
- The container has no default layout. All three product call sites (agent detail sections, sequence steps, report panels) pass their own `flex … justify-between gap-*` with different `items-*` values, where DESIGN.md asks for a title and link on a shared baseline.
- The heading doesn't set `text-foreground`, so it inherits whatever color its parent has.
- The heading's classes can't be changed; there is no `headingClassName`.
- Home rail cards and most panels don't use Section header at all; they hand-roll `flex items-baseline justify-between` with an `h2` at `text-sm font-semibold`.

API `SectionHeader`:
- `title: React.ReactNode`. The heading text.
- `description?: React.ReactNode`. One line under the heading, rendered in a `<p>`, so pass inline content only.
- `action?: React.ReactNode`. Rendered after the title block, inside the container.
- `id?: string`. Set on the heading, for `aria-labelledby`.
- `as?: "h2" | "h3"` = "h2". Heading level. The visual size doesn't change.
- `className?: string`. Classes for the outer `<div>`. Pass the flex row here.
- `titleClassName?: string`. Classes for the wrapper around the heading and description, usually `min-w-0`.
- `descriptionClassName?: string` = "mt-0.5 text-13 text-muted-foreground". Replaces the description's classes.

### Toolbar

- Level: Molecule
- Category: Layout
- Status: Beta
- Import: `@oration/canon/components/toolbar`
- Exports: `ToolbarRow`, `ToolbarSearch`
- Docs: /design/components/toolbar

Toolbar is the row of view controls between a list's header and its rows: view tabs on the left, then search, filter, display and layout controls, all 28px tall. `ToolbarRow` is the row itself (a hairline-ruled, wrapping flex row at least 44px tall) and `ToolbarSearch` is the compact search field that widens on focus. It's used across Contact Center, Ticketing and Settings lists. The mistake is mixing heights: a 32px default button or a filled primary in a toolbar row breaks the rhythm, and the row stops reading as quiet chrome around the data.

When to use:
- Above a grid, table, board or list, to hold the controls that change what the rows show: views, search, filters, sort, display, layout.
- As a second row under the first, holding active filter chips, so filters stay visible without crowding the controls.
- As the top row of a card that frames a table on a document page, like the team roster.
- For search that filters the rows below as people type, with `ToolbarSearch`.

When not to use:
- For the page's title, breadcrumbs and page actions. That is the app header. Use /design/templates/list-page instead.
- For actions on selected rows. Those float in the bulk action bar. Use /design/components/action-bar instead.
- For formatting controls inside an editor, which need arrow-key toolbar semantics. Use /design/components/prompt-editor instead.
- For a standalone search box outside a toolbar row. Use /design/components/search-field instead.
- For switching between two to five layouts on their own, without the rest of the row. Use /design/components/segmented-control instead.

Rules:
- Toolbar rows use 28px controls: Full-bleed tools stack the header, then toolbar rows of 28px controls: `sm` buttons, `icon-sm` icon buttons, the 28px segmented control, 28px filter chips and the 28px search. Default 32px controls stay out of the row.
- The One Filled Button Rule: Toolbar controls are ghost or outline. If the view has a primary action such as New ticket, it lives in the app header, not in the toolbar.
- The Scroll Edge Rule: When view tabs overflow the row, they scroll horizontally and fade their clipped edge over 2rem instead of wrapping onto a second line.

Anatomy:
- Row: `ToolbarRow`: a wrapping flex row, at least 44px tall, 12px by 8px padding, 8px gaps and a hairline bottom rule.
- View tabs: Saved views as 28px Body Dense pills with trailing counts in 12px Slate Meta, at the start of the row.
- Search: `ToolbarSearch`: a 28px field with a 14px search glyph, 176px wide at rest and 224px while focused.
- Controls: Filter, sort and display as ghost `sm` buttons, then a segmented control for layout, grouped with `ml-auto` at the end of the row.
- Filter chip row: An optional second `ToolbarRow` (`min-h-10 py-1.5`) that appears only while filters are active.

States:
- Search at rest: 176px wide with the hairline lift as its edge and a Slate Meta placeholder.
- Search focused: Widens to 224px over 200ms and swaps the lift for a 1px Focus Indigo ring.
- Search with a query: A clear button appears at the right. Clearing empties the field and hides the button.
- Filters active: The filter button turns ink and shows the count in indigo, and the chip row opens under the toolbar.
- Filtered to nothing: The rows area says what hid everything and offers Clear filters. The toolbar stays as it was.
- Narrow: The row wraps. Below 640px the search goes full width (`max-sm:w-full`); pages often move the control group to its own line below 768px.

Behavior:
- `ToolbarRow` is layout only: it holds no state, sets no role and does no keyboard handling. Tab moves through its controls in order.
- `ToolbarSearch` is controlled: pass `value` and `onChange`, which receives the string. It filters as people type; there is no submit and no debounce.
- The clear button calls `onChange("")`. It only renders while there is a value.
- The field is a native `type="search"` input with the browser's own cancel button hidden. Browsers that clear search fields on Escape still do; the component adds no key handling of its own.
- The width change on focus runs over 200ms on `ease-out` and isn't turned off under reduced motion.
- The filter chip row is a second `ToolbarRow`, rendered only while filters exist, so the rows below don't shift until a filter is added.

Do and don't:
- Do: Keep every control in the row at 28px: `sm` and `icon-sm` buttons, the segmented control and the search.
- Don't: Mix 32 and 36px outline buttons into the row. The heights stagger and the row reads as a form.
- Do: Keep toolbar controls ghost or outline, with the page's primary action in the header.
- Don't: Fill toolbar buttons with indigo. Two filled buttons in one row, and neither is the page's main action.

Content:
- Search placeholders say what is searched: Search tickets, Search suppliers. The placeholder is also the field's accessible name.
- View tab labels are short nouns or states: Open, Mine, Unassigned. The count follows the label, never inside parentheses.
- Control labels are single words where the icon helps: Filter, Sort, Display.
- When filters hide every row, name it and offer the way out: No tickets match these filters with Clear filters.

Accessibility:
- `ToolbarRow` has no `toolbar` role, which is right for a row of independent controls: `role="toolbar"` would promise arrow-key movement it doesn't implement.
- `ToolbarSearch` wraps the input in a `<label>` with a screen-reader copy of the placeholder, so it always has a name. Write a placeholder that works as a label.
- Announce result counts in a polite live region (`role="status"`) beside the search, as the search example does, so filtering is audible.
- View tabs that change which rows show are a `tablist` of `tab`s with `aria-selected`, controlling the rows as a `tabpanel`.
- The search clear button is named Clear search but its hit area is the 14px icon, below the 24px minimum. When it's pressed it unmounts, and keyboard focus falls back to the page.
- Icon-only controls in the row carry an `aria-label` and a tooltip with the same words.
- Tab: Moves through the row's controls from left to right.
- Escape: In the search, clears the query where the browser supports it for search fields.
- ← + →: Inside the segmented control, moves and selects the layout.

Known gaps (follow the system, not the gap):
- `ToolbarSearch` lists `text-13` before `text-muted-foreground`, and `cn` from the `cn` package reads both as colors, so the 13px size is dropped and the query renders at the inherited size, usually 14px. The examples here pass `text-[13px]`.
- The search widens by animating `width`. DESIGN.md animates only transform, opacity, filter, clip-path and disclosure height, and the transition has no `motion-reduce` guard.
- The search's focus indicator is a 1px ring. Inputs elsewhere use an indigo border plus a 3px ring at 50%.
- The clear button's hit area is 14px, below the 24px minimum, and it unmounts when pressed, dropping keyboard focus.
- `ToolbarSearch` doesn't grow to 16px below 768px, so iOS zooms the page when it's focused. Search field does; the two toolbar searches differ.
- `ToolbarSearch` accepts no input props (`id`, `name`, `onKeyDown`, `aria-controls`), so it can't be wired to a results list or a shortcut.
- View tabs, the filter menu, filter chips, sort and display menus live in `apps/web/src/components/records/toolbar`, not in `packages/canon`. Canon can't document them as components, and this page hand-rolls a minimal view tab strip.

API `ToolbarRow` (extends <div>):
- `className?: string`. Merged after the base classes. Use `flex-nowrap max-md:flex-wrap` for a row that wraps only on small screens, or `min-h-10 py-1.5` for a chip row.

API `ToolbarSearch`:
- `value: string`. The current query.
- `onChange: (value: string) => void`. Called with the new query on every keystroke and on clear.
- `placeholder?: string` = "Search". Placeholder and accessible name.
- `className?: string`. Merged onto the wrapping `<label>`. Pass `text-[13px]` for dense text and `max-sm:flex-1` to grow on narrow rows.

### Accordion

- Level: Molecule
- Category: Layout
- Status: Experimental
- Import: `@oration/canon/components/accordion`
- Exports: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
- Docs: /design/components/accordion

Accordion stacks titled sections, split by hairlines, that open one at a time or several at once. It suits reference content people scan by heading, such as the supplier FAQ an agent draws on or the checks behind a payment run. It is experimental and not used in the product yet. The common mistake is hiding short facts behind triggers: if the answer is one line, show it as a row instead.

When to use:
- For question-and-answer content people scan by heading: the supplier FAQ, knowledge snippets, help articles.
- For a short list of checks or sections where each has a paragraph of detail, such as the checks before a payment run.
- When only one section needs to be open at a time and the rest can fold away.
- For long configuration notes inside a sheet, where the headings alone give the overview.

When not to use:
- For one region that shows and hides behind its own trigger. Use /design/components/collapsible instead.
- For switching between peer views of the same object. Use /design/components/tabs instead.
- For one-line facts about a record. Show them as rows. Use /design/components/item instead.
- For a record's attribute groups in the side rail, which use collapsible sections. Use /design/templates/record-page instead.
- For steps someone completes in order. Use /design/components/stepper instead.

Rules:
- Disclosure motion: Opening and closing animate height only, over 200ms on ease-out, within the 200 to 250ms disclosure range. Nothing else in the accordion moves.
- Hairlines are structure: Items are split by `border-b` hairlines, a structural divider. An accordion inside a card stays flat; its items never become cards.

Anatomy:
- Item: `AccordionItem`: one section. Every item but the last draws a hairline bottom rule.
- Trigger: `AccordionTrigger`: a full-width button inside an `<h3>`, 14px medium, 10px vertical padding.
- Chevron: A 16px Slate Meta chevron at the right. It points down when closed and up when open.
- Panel: `AccordionContent`: the section body. Height animates open and closed; 10px of bottom padding.

States:
- Closed: The trigger alone, with a down chevron.
- Hover: The trigger's label underlines. There is no background change.
- Focus visible: An indigo border and a 3px Focus Indigo ring at 50% around the trigger.
- Open: `aria-expanded` is true, the chevron points up and the panel grows to its content height over 200ms.
- Disabled: Set `disabled` on the item or the root. The trigger dims to 50% and ignores pointer and keyboard.

Behavior:
- Single by default: opening one item closes the other. Pass `multiple` to let several stay open.
- The value is always an array of item values, even in single mode: `defaultValue={["timing"]}`. Give every item a `value`; without one Base UI generates an ID you can't control.
- Uncontrolled with `defaultValue`, or controlled with `value` and `onValueChange(value, details)`, which is how Expand all and Collapse all work.
- Closed panels unmount by default. Pass `keepMounted` to keep them in the DOM, or `hiddenUntilFound` so the browser's find-in-page can search and open them.
- The panel's height animates with the `accordion-down` and `accordion-up` keyframes against `--accordion-panel-height`, over 200ms ease-out.
- `className` on `AccordionContent` goes on the inner wrapper, not the panel, so padding and text styles apply inside the animated region.

Do and don't:
- Do: Use an accordion for answers of a sentence or more that people find by their question.
- Don't: Fold one-line facts such as a bank account or payment terms behind triggers. Show them as rows people can read at a glance.

Content:
- Write triggers as the question or topic people look for: How do I change my bank details?, Tax forms.
- Keep triggers to one line. Put status beside the label as a status label, not in the heading text.
- Open the most likely answer by default when one stands out, and leave the rest closed.
- Panel copy is reading text: full sentences in 13 or 14px, links underlined.

Accessibility:
- Each trigger is a `<button>` inside an `<h3>`, with `aria-expanded` and `aria-controls` pointing at its panel. The panel is a `region` labelled by its trigger.
- The heading level is fixed at `h3`. Place accordions where an `h3` fits the page outline, under an `h2` section.
- Base UI 1.8 follows the updated APG pattern: triggers are in the normal tab order and arrow keys don't move between them.
- The chevrons are decorative; state comes from `aria-expanded`.
- The height animation isn't removed under reduced motion; the global reduced-motion rules only cover Collapsible.
- Tab: Moves to the next trigger or into an open panel.
- Enter: Opens or closes the focused section.
- Space: Opens or closes the focused section.

Known gaps (follow the system, not the gap):
- Accordion isn't imported anywhere in apps/web. Grouped disclosure in the product (record attribute sections, task sections, the API key scopes) uses Collapsible.
- The trigger underlines on hover, a link affordance. Other disclosure triggers in the suite fill Well Gray on hover instead.
- The chevron swaps between two icons (`ChevronDownIcon` and `ChevronUpIcon`) instead of rotating, so the change doesn't animate while Collapsible triggers rotate theirs over 200ms.
- The height animation has no reduced-motion override. Collapsible snaps under reduced motion; Accordion keeps animating.
- The heading is always an `h3` and can't take a class or a different level.
- The inner wrapper carries `data-starting-style:h-0` and `data-ending-style:h-0`, but those attributes are set on the panel, not the wrapper, so the classes never match.

API `Accordion` (extends Base UI `Accordion.Root` (`<div>`)):
- `defaultValue?: any[]`. Values of the items open on first render. Uncontrolled.
- `value?: any[]`. Values of the open items. Controlled.
- `onValueChange?: (value: any[], eventDetails) => void`. Called when an item opens or closes.
- `multiple?: boolean` = false. Lets several items stay open at once.
- `disabled?: boolean` = false. Disables every item.
- `keepMounted?: boolean` = false. Keeps closed panels in the DOM.
- `hiddenUntilFound?: boolean` = false. Hides closed panels with `hidden="until-found"` so find-in-page can open them. Overrides `keepMounted`.
- `orientation?: "vertical" | "horizontal"` = "vertical". Sets `data-orientation`. The styles assume vertical.

API `AccordionItem` (extends Base UI `Accordion.Item` (`<div>`)):
- `value?: any`. Identifies the item in `value` and `defaultValue`.
- `disabled?: boolean` = false. Disables this item.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when this item opens or closes.

API `AccordionTrigger` (extends Base UI `Accordion.Trigger` (`<button>`)):
- `className?: string`. Merged onto the button. The `h3` can't be styled.

API `AccordionContent` (extends Base UI `Accordion.Panel` (`<div>`)):
- `className?: string`. Applied to the inner wrapper, which carries the padding and text styles.

### Collapsible

- Level: Molecule
- Category: Layout
- Status: Stable
- Import: `@oration/canon/components/collapsible`
- Exports: `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`
- Docs: /design/components/collapsible

Collapsible is one region that shows and hides behind its trigger, with a 200ms height animation that snaps under reduced motion. It powers the record attribute sections, the task list groups, the invite link panel and the reasoning in Thinking and Tool chip. The component is unstyled Base UI: you bring the trigger, usually a chevron that rotates, and the panel. What people get wrong is the trigger's name: More or a bare chevron says nothing about what opens.

When to use:
- For a section of a side rail or list that people fold away, like Payment details on a record or Completed in tasks.
- For advanced or rarely changed settings under a form or a settings row, such as Retry settings.
- For a card whose summary row stays visible and whose details open below it, like the invite link panel.
- For secondary detail inside a row, such as a tool call's input and output.

When not to use:
- For a stack of sections where opening one should close the others. Use /design/components/accordion instead.
- For switching between peer views. Use /design/components/tabs instead.
- For content that floats over the page and dismisses on outside click. Use /design/components/popover instead.
- For a short explanation of a term. Use /design/components/info-tip instead.
- For errors or warnings people must see. Don't fold them away. Use /design/components/alert instead.

Rules:
- Disclosure motion: The panel's height animates over 200ms on the house ease-out (`--ease-out`), inside the 200 to 250ms disclosure range. Under reduced motion it snaps open and closed with no transition.
- Chevrons rotate, they don't swap: A right chevron turns 90° to point down (or a down chevron turns 180°) over the same 200ms, keyed off `data-panel-open` on the trigger.

Anatomy:
- Root: `Collapsible`: holds the open state. Renders a `<div>`, or any element through `render`, such as a `<section>`.
- Trigger: `CollapsibleTrigger`: a `<button>` with `aria-expanded`. Put it inside a heading when it names a section, and give it a chevron.
- Panel: `CollapsibleContent`: the region that animates its height between 0 and `--collapsible-panel-height`, with `overflow: hidden`.

States:
- Closed: The panel is unmounted (or hidden with `keepMounted`) and the chevron points right.
- Hover: Up to the trigger's styling. Section triggers fill Well Gray; icon buttons use the ghost hover.
- Focus visible: Up to the trigger. Section triggers draw a 3px Focus Indigo ring at 40%; buttons bring their own.
- Open: The trigger gets `data-panel-open` and `aria-expanded="true"`; the panel gets `data-open` and grows to its content height over 200ms.
- Opening and closing: `data-starting-style` and `data-ending-style` pin the height at 0 at either end of the transition.
- Disabled: `disabled` on the root makes the trigger ignore interaction. Style it yourself; the wrapper adds no dimming.

Behavior:
- Uncontrolled with `defaultOpen` (closed by default), or controlled with `open` and `onOpenChange(open, eventDetails)`.
- The height transition comes from `globals.css`: `[data-slot="collapsible-content"]` sets `overflow: hidden`, `height: var(--collapsible-panel-height)` and `transition: height 200ms var(--ease-out)`. Under `prefers-reduced-motion: reduce` the transition is removed.
- Closed panels unmount by default. `keepMounted` keeps them in the DOM; `hiddenUntilFound` hides them with `hidden="until-found"` so find-in-page can open them.
- Style the trigger from its state with `group-data-panel-open/…:` classes, as the record attribute sections do for their chevron.
- Trigger and panel are linked with `aria-controls` automatically; you don't pass IDs.
- `render` works on every part, so a trigger can be a `Button` and a root can be a `<section>`. The trigger can also sit inside a Tooltip trigger.

Do and don't:
- Do: Name what opens: Retry settings, Payment details, with a chevron that turns.
- Don't: Label the trigger More or leave a bare chevron. People can't tell what will open until they try it.

Content:
- Trigger labels name the hidden content: Retry settings, Tax, Show quoted text.
- When the label changes with the state, say both: Show email settings and Hide email settings.
- Section triggers can carry a count after the label in Slate Meta tabular figures: Due this week 3.
- Don't hide required fields or errors inside a closed panel.

Accessibility:
- The trigger is a real `<button>` with `aria-expanded` and `aria-controls`. Base UI keeps them in sync.
- When the trigger names a section, wrap it in a heading (`<h2>` or `<h3>`) so the section appears in the page outline, as the record attribute sections do.
- Icon-only triggers need an `aria-label` that says what they show or hide, and a tooltip with the same words.
- The height animation is removed under reduced motion by `globals.css`; chevron rotations should add `motion-reduce:transition-none` too.
- Use `hiddenUntilFound` for long reference content, so find-in-page reaches text inside closed panels.
- Tab: Moves to the trigger, then into the open panel.
- Enter: Opens or closes the panel.
- Space: Opens or closes the panel.

Known gaps (follow the system, not the gap):
- The trigger ships unstyled, so each product call site writes its own. Record attribute sections, task sections and the invite link panel use three different hover, focus and chevron treatments.
- Chevron rotations at the call sites don't add `motion-reduce:transition-none`, so the icon still turns under reduced motion while the panel snaps.
- The invite link panel rotates its chevron with an inline `style` over 150ms while the panel opens over 200ms.

API `Collapsible` (extends Base UI `Collapsible.Root` (`<div>`)):
- `defaultOpen?: boolean` = false. Whether the panel starts open. Uncontrolled.
- `open?: boolean`. Whether the panel is open. Controlled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when the trigger opens or closes the panel.
- `disabled?: boolean` = false. Ignores interaction with the trigger.
- `render?: ReactElement | (props, state) => ReactElement`. Render as another element, such as `<section>`.

API `CollapsibleTrigger` (extends Base UI `Collapsible.Trigger` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render as another element, usually a `Button`.

API `CollapsibleContent` (extends Base UI `Collapsible.Panel` (`<div>`)):
- `keepMounted?: boolean` = false. Keeps the panel in the DOM while closed.
- `hiddenUntilFound?: boolean` = false. Hides the closed panel with `hidden="until-found"` so find-in-page can open it. Overrides `keepMounted`.

### Resizable panels

- Level: Molecule
- Category: Layout
- Status: Beta
- Import: `@oration/canon/components/resizable`
- Exports: `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`
- Docs: /design/components/resizable

Resizable panels split a tool into panes separated by a 1px hairline handle that people drag, or move with the arrow keys. The Contact Center workspace uses it for its queue, conversation and context panes; editors and test consoles are the other fit. It wraps react-resizable-panels 4, whose group fills its parent, so the parent must have a height. The mistake is decorating the split: the handle is a structural hairline, not a bar, and the panes are regions of one plane, not cards.

When to use:
- For a full-bleed tool with two or three panes whose balance depends on the task: the Contact Center queue, conversation and context.
- For an editor beside its preview or test console, such as a prompt next to a test call.
- For a transcript above notes or logs, split vertically.
- When a side pane should fold away completely and come back, with `collapsible`.

When not to use:
- For a fixed side panel that opens and closes over the content. Use /design/components/sheet instead.
- For the app's navigation rail. Use /design/components/sidebar instead.
- For resizing data grid columns, which have their own handle. Use /design/components/data-grid instead.
- On phones. Collapse to one pane with a back affordance instead. Use /design/foundations/responsive instead.
- For a scrolling region inside one pane. Use /design/components/scroll-area instead.

Rules:
- The Hairline-and-Lift Rule: The handle is a structural divider: a 1px `--border` hairline. Panes are regions of one surface, never separately lifted cards.
- Three panes, then collapse: Below 768px a multi-pane tool becomes one pane with a back affordance. The Contact Center workspace renders the group only on desktop and swaps panes on mobile.

Anatomy:
- Group: `ResizablePanelGroup`: a flex row or column that fills its parent (`height: 100%`, `width: 100%`, set inline by the library).
- Panel: `ResizablePanel`: a pane with a default, minimum and maximum size in percent or pixels.
- Handle: `ResizableHandle`: a 1px Hairline `role="separator"` between two panels.
- Grip: Optional with `withHandle`: a 4 by 24px Hairline pill centered on the handle, rotated for vertical groups.
- Hit area: An invisible band around the hairline: 4px from the component, widened by the library to at least 10px for a mouse and 20px for touch.

States:
- Rest: A 1px hairline. The cursor turns to a resize cursor over the hit area.
- Hover and dragging: The library sets `data-separator` to `hover` or `active`, but the handle draws no change; only the cursor shows it.
- Focus visible: A 1px Focus Indigo ring around the handle.
- Collapsed: A `collapsible` panel dragged past its minimum snaps to `collapsedSize` (0% by default) and reopens past the threshold.
- Disabled: `disabled` on a handle, panel or group stops resizing; the separator gets `aria-disabled` and a not-allowed cursor.

Behavior:
- Sizes accept numbers as pixels and strings as percentages or with units: `defaultSize="25%"`, `minSize="240px"`, `maxSize="36%"`.
- The group needs a sized parent. It sets `height: 100%` and `width: 100%` inline; inside a flex column, give it `min-h-0 flex-1` as the workspace does.
- Pointer drags resize immediately. `resizePreviewMode="separator"` on the group shows a preview line and resizes on release instead.
- Double-clicking a handle resets its panel to `defaultSize`, unless the handle has `disableDoubleClick`.
- Give panels an `id` when you persist layouts. `onLayoutChanged(layout, meta)` fires once after a drag or key press ends, with `meta.isUserInteraction`, and `defaultLayout` restores it.
- `ResizablePanel` applies `className` to a nested div inside the panel, not to the panel element itself.
- Imperative control (collapse, expand, resize) goes through `panelRef` and `groupRef`.

Do and don't:
- Do: Split panes with the plain 1px hairline, and let the panes sit on one surface.
- Don't: Gap the panes into separate cards and paint the handle as a thick indigo bar. It reads as three widgets, and indigo is not a divider color.

Content:
- Panes don't need a visible label when their contents are obvious, but each should start with a heading or header row that names it: Queue, Inspector.
- If a pane can collapse, say how to reopen it the first time it's hidden.

Accessibility:
- Each handle is a focusable `role="separator"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-controls` and an `aria-orientation` perpendicular to the group.
- The separator has no name. When a split matters to the task, label it with `aria-label` (for example Resize queue).
- The focus ring is 1px, thinner than the 3px focus ring elsewhere. It sits on a 1px line, so check it against both panes' backgrounds.
- Everything a drag does is also on the keyboard: arrows resize by 5%, Home and End jump to the limits and Enter collapses or expands a collapsible panel.
- Pane content should reflow at narrow widths; set `minSize` so no pane becomes unreadable.
- ← + →: In a horizontal group, shrinks or grows the panel before the handle by 5%.
- ↑ + ↓: In a vertical group, shrinks or grows the panel above the handle by 5%.
- Home: Shrinks the panel before the handle to its minimum.
- End: Grows the panel before the handle to its maximum.
- Enter: Collapses or expands the panel before the handle, if it is collapsible.
- F6: Moves focus to the next handle in the group; Shift+F6 goes back.

Known gaps (follow the system, not the gap):
- The handle has no hover or active style. DESIGN.md's grid column handle shows a 1px indigo rule on hover; here only the cursor changes, although the library exposes `data-separator="hover"` and `"active"` to style.
- The focus ring is `ring-1`, where focus indicators elsewhere are 3px at 40 to 50%.
- `aria-[orientation=vertical]:flex-col` on the group never matches: the group has no `aria-orientation`. The library sets `flex-direction` inline, so vertical groups still stack.
- The separator has no accessible name by default.
- `useDefaultLayout` and the ref hooks from react-resizable-panels aren't re-exported from `packages/canon`, so persisting a layout means importing the library directly.
- Only the Contact Center workspace imports it today.

API `ResizablePanelGroup` (extends react-resizable-panels `Group` (`<div>`)):
- `orientation?: "horizontal" | "vertical"` = "horizontal". Side by side, or stacked.
- `defaultLayout?: { [panelId: string]: number }`. Starting sizes by panel id, in percent. Restores a saved layout.
- `onLayoutChange?: (layout: Layout) => void`. Called on every change, including each pointer move.
- `onLayoutChanged?: (layout: Layout, meta: LayoutChangedMeta) => void`. Called once a resize ends. Use it to persist the layout.
- `resizePreviewMode?: "panel" | "separator"` = "panel". Resize live, or show a preview line until release.
- `resizeTargetMinimumSize?: { coarse: number; fine: number }` = { coarse: 20, fine: 10 }. Minimum hit target for handles and panel edges, in pixels.
- `disabled?: boolean`. Turns off resizing for the whole group.
- `disableCursor?: boolean`. Stops the library from setting resize cursors.
- `groupRef?: Ref<GroupImperativeHandle | null>`. `getLayout()` and `setLayout(layout)`.

API `ResizablePanel` (extends react-resizable-panels `Panel` (`<div>`)):
- `id?: string | number`. Identifies the panel in layouts. Falls back to `useId`.
- `defaultSize?: number | string`. Starting size. Numbers are pixels, strings are percent unless they carry a unit.
- `minSize?: number | string` = "0%". Smallest size a drag or key press can reach.
- `maxSize?: number | string` = "100%". Largest size.
- `collapsible?: boolean`. Lets the panel snap to `collapsedSize` when dragged below `minSize`.
- `collapsedSize?: number | string` = "0%". Size when collapsed.
- `collapsedThreshold?: number | string`. How far past the minimum a drag must go to collapse or expand.
- `groupResizeBehavior?: "preserve-relative-size" | "preserve-pixel-size"` = "preserve-relative-size". What the panel keeps when the group itself resizes.
- `onResize?: (size: { asPercentage: number; inPixels: number }, id, prevSize) => void`. Called when this panel's size changes.
- `panelRef?: Ref<PanelImperativeHandle | null>`. `collapse()`, `expand()`, `getSize()`, `isCollapsed()` and `resize(size)`.
- `disabled?: boolean`. Stops this panel from resizing, directly or indirectly.

API `ResizableHandle` (extends react-resizable-panels `Separator` (`<div role="separator">`)):
- `withHandle?: boolean`. Adds the centered grip pill.
- `disabled?: boolean`. Stops this handle from resizing its panels.
- `disableDoubleClick?: boolean`. Turns off reset-on-double-click.
- `className?: string`. Merged after the base classes. The workspace passes `bg-transparent` where the pane already draws its own border.

### Code block

- Level: Molecule
- Category: Content
- Status: Stable
- Import: `@oration/canon/components/code-block`
- Exports: `CodeBlock`, `InlineCode`
- Docs: /design/components/code-block

Code block shows a snippet or payload people copy or read exactly: 12px Geist Mono on Row Mist, under a 36px title bar with a copy button. `InlineCode` is its inline sibling for a key, ID or variable inside a sentence. Both exist for The Machine Mono Rule: mono is only for strings a machine produced or will parse. The mistake runs the other way too, putting amounts, counts or labels in `InlineCode` because they look technical.

When to use:
- For a request people run, such as a curl command in the API quick start.
- For a request preamble people read line by line: a method, URL and headers.
- For a value they paste somewhere else in full, such as a generated URL.
- Use `InlineCode` for a machine string inside a sentence: `vendor_id`, `{{vendor_id}}`, `YOUR_PUBLIC_KEY`, a slug to type.

When not to use:
- For a JSON payload people inspect: a webhook body, an API response, an audit log event, a tool's input and output. It needs folding, search and path copy. Use /design/components/json-viewer instead.
- For the same snippet in several languages. Use /design/components/code-snippet-tabs instead.
- For one secret or ID on a line with a copy button. Use /design/components/copy-row instead.
- For a before-and-after of text or fields. Use /design/components/diff instead.
- For a template variable people insert into a prompt. Use /design/components/variable-chip instead.
- For JSON people edit. Use an editor or a structured builder. Use /design/components/json-schema-builder instead.
- For keyboard shortcuts. Use /design/components/kbd instead.

Rules:
- The Machine Mono Rule: Geist Mono is only for strings a machine produced or will parse: record and run IDs, API keys, tokens, codes, DNS records, template variables, timecodes. Figures, labels, keyboard keys and headings stay in Geist Sans.
- The Tabular Figures Rule: Amounts and counts beside code stay in Geist Sans with tabular figures. `$58,902.14` is a figure, not code.

Anatomy:
- Surface: Row Mist (`bg-surface`) with 10px corners and the hairline lift.
- Title: 12px medium Slate Meta in a 36px bar with a hairline bottom. Defaults to Code.
- Copy button: A 24px ghost Copy button named Copy {title}. The icon swaps to a green check for 1.6s after copying.
- Code: `<pre><code>` in 12px Geist Mono at a 20px line height, 12px padding, scrolling sideways when a line is long.

States:
- Rest: Title, copy button and code. No syntax colors.
- Copied: The copy icon becomes a Ledger Green check and the button's name becomes Copied for 1.6s.
- Overflowing: Long lines scroll horizontally inside the block; the block never wraps or grows past its container.
- Highlighted placeholder: An `InlineCode` placeholder people must replace can take `bg-warning/15`, as the widget install instructions do.

Behavior:
- The copy button writes the exact `code` string to the clipboard, including line breaks, and swallows clipboard errors silently.
- Whitespace is preserved: pass the code already indented. For JSON, pass the value to JSON viewer instead of `JSON.stringify` output.
- There is no maximum height. Long payloads grow the block; wrap it in a scroll area or a sheet when that matters.
- `InlineCode` sizes itself at 0.85em of the surrounding text, so it scales with the sentence it sits in.

Do and don't:
- Do: Title every block with what it is or does: Test the lookup, Request body.
- Don't: Leave the default title. Code says nothing, and the copy button is named Copy code on every block on the page.
- Do: Put IDs in `InlineCode` and keep amounts and counts in Geist Sans with tabular figures.
- Don't: Wrap amounts and counts in `InlineCode`. It breaks The Machine Mono Rule and makes figures look like identifiers.

Content:
- Titles are short and sentence case: Create a supplier, Request body, Widget URL.
- Use real, runnable examples with Cedarline's data, and environment variables for secrets: `$ORATION_API_KEY`, never a live key.
- Placeholders people must replace are upper snake case (`YOUR_PUBLIC_KEY`) and called out in the sentence around the block.
- Keep the sentence outside the block: explain what the code does above it, not in comments inside it.

Accessibility:
- The copy button is named after the title (Copy Create a supplier), so give every block a distinct title when several share a page.
- After copying, the button's name changes to Copied; there is no live announcement, so pair important copies with a toast.
- The `<pre>` scrolls horizontally with the pointer or trackpad, but it isn't focusable, so keyboard users can't scroll a clipped line. Keep lines short where you can.
- `InlineCode` is a `<code>` element and is read as plain text. Don't rely on the mono face alone to mark something people must type; say it in words too.
- Tab: Moves to the copy button.
- Enter: Copies the code.

Known gaps (follow the system, not the gap):
- `CodeBlock` draws the hairline lift. Placed inside a card it becomes a raised surface inside a raised surface, which The Tint Well Rule rules out; there is no flat variant.
- There's no `language` prop or syntax highlighting, while Code snippet tabs records a language per snippet. Canon's own docs highlight code; product code blocks don't.
- There's no `maxHeight` or wrapping option, so long audit log payloads grow the sheet they sit in.
- `title` doubles as the copy button's name, so a block without a title copies as Copy code. There's no separate `copyLabel`.
- `CodeBlock` accepts no other props (no `id`, no `aria-*`), so a block can't be referenced by `aria-describedby`.

API `CodeBlock`:
- `code: string`. The exact text to show and copy.
- `title?: string` = "Code". Shown in the bar and used to name the copy button.
- `className?: string`. Merged onto the outer container, for width and margins.

API `InlineCode` (extends <code>):
- `className?: string`. Merged after the base classes, for example `bg-warning/15` on a placeholder.

### JSON viewer

- Level: Molecule
- Category: Content
- Status: Beta
- Import: `@oration/canon/components/json-viewer`
- Exports: `JsonViewer`, `JsonViewerChange`, `JsonViewerEditOptions`
- Docs: /design/components/json-viewer

JSON viewer shows a payload people inspect as a collapsible tree: quoted keys, braces and commas, so it reads and copies like real JSON, with values colored by type. Every row copies its value or its JSONPath (`$.data.analysis.payment.method`), the toolbar folds or opens everything, and search finds keys, values and paths, then filters the tree down to the matches. Pass the value itself, never `JSON.stringify` output: the viewer needs the structure to fold, search and copy paths. With `editable`, every key and value edits where it stands, in the same type and type size, so a person adjusting a mock response never leaves the document they're reading.

When to use:
- For a payload people inspect: a webhook request body, an API response, a tool call's input and output, an audit log event.
- For structured output people check field by field, such as post-call analysis or a mapped caller lookup.
- For a response body that may or may not be JSON. Pass the string; text that isn't JSON renders as written.
- Inside a card use `variant="well"`; inside another well, such as Tool chip, use `variant="bare"`.
- With `editable`, for JSON people adjust in place: a tool's mock response, test values for a call, a sample webhook body. Pass `baseline` and pair it with a save bar.

When not to use:
- For a request people run, such as a curl command, or a URL and headers. Use /design/components/code-block instead.
- For defining fields, their types, descriptions and whether they're required. That's a schema, not a document. Use /design/components/json-schema-builder instead.
- For a handful of labeled fields people read rather than inspect. Lay them out as a description list. Use /design/components/settings-section instead.
- For a before-and-after of fields. Use /design/components/diff instead.

Rules:
- The Machine Mono Rule: Keys and values are Geist Mono because a machine wrote them. Counts in collapsed summaries, the header, search and every control stay in Geist Sans with tabular figures.
- The Tint Well Rule: The default viewer lifts like Code block. Inside a card it becomes a 70% Well Gray well with `variant="well"`, never a raised block inside a raised card.
- Syntax inks: Strings are Tag Green ink, numbers Tag Amber ink, booleans Tag Violet ink and null Slate Meta, the same inks Canon's code samples use. Keys stay Graphite Ink and punctuation Slate Meta, so the data carries the color and the labels don't.
- The Quiet Indigo Rule: Indigo appears only where the system spends it: the focused row, the current search match and its marks, the ring around an open editor and the unsaved-changes dot. Matches never turn amber or yellow, and an editable viewer never adds a filled button of its own; Save belongs to the page.

Anatomy:
- Title: 12px medium Slate Meta in a 36px bar with a hairline bottom. Name what the payload is: Request body, Response 200, analysis.json.
- Summary: The root's size in 12px tabular figures: 5 keys, 240 items, or Empty.
- Toolbar: 24px ghost icon buttons with tooltips: search (from 10 values up), expand all and collapse all (when anything nests) and copy the whole document. Expand all and collapse all disable when they would do nothing.
- Chevron and guides: A 12px chevron that turns 90° as a branch opens, in a 16px column. Each level indents 16px and draws a hairline guide under its parent's chevron.
- Key and value: 12px Geist Mono at a 20px line. Long strings wrap at the row's indent; past 280 characters they clip with Show all 1,240 characters.
- Collapsed summary: A folded branch reads `{ 3 keys }` or `[ 2 items ]`, the count in a 4px-corner ink chip. Clicking it, the key or the chevron opens the branch.
- Inline editor: Editable only. A field in the same 12px mono, color and line as the text it replaces, on White Plane with a 1px indigo ring and a soft 3px halo drawn as a shadow, so rows never shift. String quotes stay outside it.
- Type chip: Editable only. A 20px Slate Meta chip after the value naming its type, String or Number, with a menu of all six. New fields and nulls read Detect from value until you pick one.
- Unsaved dot: With `baseline`, a 5px indigo dot in the gutter beside each field that differs from it, and beside a folded branch with a change inside.
- Add key: Editable only. A quiet Slate Meta row that closes the document: a plus and Add key (or Add item for an array).

States:
- Rest: Payloads of up to 80 values open fully; larger ones open two levels. `defaultExpandDepth` overrides both.
- Row hover: The row takes a 4% ink tint and shows Copy path and Copy value at its right end, over a short fade so long values slide under them. Their tooltips show the path and the P and C keys.
- Row focus: Keyboard focus fills the row with a 6% indigo tint and a 30% inset indigo ring, and keeps its actions showing.
- Copied: The row's copy icon becomes a Ledger Green check for 1.6s and a polite live region announces what was copied.
- Searching: A 28px search field opens under the header with the match count, previous and next, and Show only matches. Matching text is marked in a 15% indigo tint; the current match's row takes the 6% row tint and its marks deepen to 30%.
- Filtered: With Show only matches on (the default), the tree keeps matches, their ancestors for context and everything inside a matching branch.
- No matches: With the filter on, the body says No keys or values match “vndr”. and offers Clear search. With it off, the count reads No matches and the tree stays whole.
- Long array: Branches past 100 children end in Show 100 more of 140. Searching lifts the limit so every match can show.
- Text: A string that isn't a JSON document renders as wrapped mono text with only the copy button, as a plain-text error body would. It stays read-only with `editable`.
- Editable hover: Keys and values take a 7% ink box under the pointer with a text cursor; booleans a pointer. The row's actions become Add field below, Delete and a More actions menu.
- Editing: The value or key turns into the inline editor with its text selected. The row's comma and actions step aside until it closes.
- Invalid: The ring and halo turn Signal Red and the reason sits after the field in 12px red Geist Sans: Enter a number, like 12480, “status” already exists. The field stays open.
- New field: A row with an indigo plus in the chevron column, an empty key field (objects only) and a value field, at the spot it will land.
- Unsaved: Changed fields carry the indigo dot until `baseline` catches up, usually on Save.
- Deleted: The field leaves at once, focus moves to its neighbor, and a toast offers Undo.

Behavior:
- Paths are JSONPath: `$.vendor.id`, `$.lines[3].amount`, and `$["first name"]` for keys that aren't identifiers. It's the notation caller ID response mappings already use.
- Copy value writes a string without its quotes, a number or boolean as written, and an object or array as two-space JSON. The header button copies the whole document.
- Alt-click a chevron, key or summary to open or close the whole branch beneath it.
- Search is case-insensitive and matches keys, values and paths. A query with a dot, a bracket or a leading `$` also matches by path, so `payment.method` finds `$.data.analysis.payment.method`.
- Branches that hold a match open while you search, without changing what you had open. Closing search keeps the current match's branch open and moves focus to it.
- A string that starts with `{` or `[` is parsed as JSON; any other string renders as text. Dates serialize through `toJSON`, `undefined` and functions drop as `JSON.stringify` would, and a circular reference shows as `[Circular]`.
- The tree is `translate="no"`, so browser translation never rewrites keys.
- The viewer sets `aria-live="off"` on itself, so folding inside a live region (a test result, a run log) isn't read out row by row.
- Editing keeps a value's type: an ID typed as `2290` into a string stays the string `"2290"`. A number field accepts `12,480` and saves `12480`. Change the type from the chip or the row's Change type menu.
- New fields and nulls detect their type as you type: `true` is a boolean, `12480` a number, a pasted `{…}` or `[…]` an object or array, `"…"` a string, and anything else text. A leading zero (`0042`) stays text, so codes keep their zeros. Empty is null.
- Clicking a boolean flips it. Renaming a key keeps its position. Changing a value to an empty object or array opens a new field inside it.
- Enter saves, Escape cancels and Tab saves and moves to the next key or value. Clicking away saves too, unless the text is invalid; then the field closes unchanged and the reason is announced.
- Changing a filled object or array to another type replaces its children, so a toast says how many and offers Undo.
- Every edit calls `onChange(value, change)` with the whole new document and `{ kind, path }`. Pass the value back to control it, or don't and the viewer keeps its own copy. A new `value` from outside replaces the document and clears undo.
- ⌘Z and ⇧⌘Z undo and redo up to 100 steps while focus is in the viewer, outside a field.
- Fields edited during a filtered search stay visible until the query changes, even when they no longer match.

Do and don't:
- Do: Pass the value and let the viewer fold, color and copy paths.
- Don't: Pass `JSON.stringify(value, null, 2)` to Code block. People lose folding, search, types and paths, and long payloads grow the sheet.
- Do: Use `variant="well"` inside a card, so the viewer reads as part of it.
- Don't: Drop the default raised viewer into a card. It becomes a card inside a card.

Content:
- Title the viewer with what the payload is: Request body, Response 200, Event JSON, a file name such as analysis.json, or a content type when that is what people check.
- Give each viewer on a page a distinct title. It names the copy button (Copy request body) and the search field.
- Keep status and timing outside the viewer, in a status label beside its title: 200 OK in 212 ms.
- Show sample data from Cedarline's world, and secrets as environment variables or masked values, never a live key.
- Editing errors name the fix, not the rule: Enter a number, like 12480, Enter a key, “status” already exists.

Accessibility:
- The tree is one tab stop with a roving focus (`role="tree"`, `treeitem` rows with level, position and expanded state). Each row's name is its key and value without punctuation, such as amount: 20625 or payment, object, 3 keys.
- A visually hidden hint, linked by `aria-describedby`, explains the arrow keys and the C and P shortcuts.
- Row copy buttons are pointer shortcuts and stay out of the tab order; C and P do the same from the keyboard. Copies are announced in a polite live region.
- The search field is labeled after the title, and the match count is announced politely as Match 2 of 5.
- Closing search returns focus to the current match, or to the search button when there was none.
- Rows fade in over 150ms only after the first render, and not at all with reduced motion; the chevron turn stops too.
- Editable rows add unsaved change to their name when they differ from `baseline`. Editors are labeled Value of amount, Key status, New key and New value, and an error is linked with `aria-describedby`.
- Saves, renames, additions, deletions, moves and undo are announced politely. Every row action is in the More actions menu, which Shift+F10 opens, so nothing depends on hover.
- Tab: Moves into the tree at the last focused row.
- ↓ + ↑: Moves to the next or previous row.
- →: Opens a closed branch, or moves to its first child.
- ←: Closes an open branch, or moves to its parent.
- Alt + →: Opens the whole branch.
- Home + End: Moves to the first or last row.
- Enter: Opens or closes a branch, shows a clipped string in full, or shows the next 100 items.
- C: Copies the row's value. ⌘C does too when nothing is selected.
- P: Copies the row's JSONPath.
- /: Opens search. ⌘F does too while focus is inside the viewer.
- Enter: In search, moves to the next match; Shift+Enter moves back.
- Esc: In search, clears the query, then closes search.
- Enter: Editable: edits the row's value, or flips a boolean.
- F2: Editable: renames the row's key.
- Enter: In a field, saves. Shift+Enter adds a line to a string; ⌘Enter saves and starts a field below.
- Tab: In a field, saves and moves to the next key or value; Shift+Tab moves back.
- Esc: In a field, cancels and returns to the row.
- ⌘ + Enter: Editable: adds a field below the row.
- ⇧ + ⌘ + Enter: Editable: adds a field inside an object or array.
- Delete: Editable: deletes the row, with Undo.
- ⌘ + D: Editable: duplicates the row.
- Alt + ↑: Editable: moves the row up; Alt+↓ moves it down.
- ⌘ + Z: Editable: undoes; ⇧⌘Z redoes.
- Shift + F10: Editable: opens the row's More actions menu.

Known gaps (follow the system, not the gap):
- Rows aren't virtualized. Branches reveal 100 children at a time, but Expand all on a very large document still renders every row.
- There's no raw text view; select across rows or use the header copy button for the exact JSON.
- Array items show no index. The index is in the row's path tooltip and its accessible name.
- Rows don't drag to reorder; use Move up and Move down or Alt+↑ and Alt+↓.
- Editing doesn't check the document against a schema. Use `editable={{ keys: false, structure: false }}` when the shape is fixed.

API `JsonViewer`:
- `value: unknown`. The data to show. A string that starts with `{` or `[` is parsed; any other string renders as text.
- `title?: string` = "JSON". Shown in the header; names the copy button and the search field.
- `variant?: "surface" | "well" | "bare"` = "surface". `surface` lifts like Code block, for sheets and pages. `well` is a flat 70% Well Gray region for inside cards. `bare` has no fill or header rule, for a section inside another well.
- `defaultExpandDepth?: number`. Levels open on mount; 0 shows only the top-level keys. Defaults to everything for up to 80 values and 2 beyond that.
- `maxHeight?: number | string`. Caps the tree's height; it scrolls inside the viewer past that.
- `editable?: boolean | { keys?: boolean; structure?: boolean; types?: boolean }` = false. Turns on inline editing. `true` allows everything. An object turns parts off: `keys` (rename), `structure` (add, delete, duplicate, move) and `types` (the type chip and Change type), each true unless set false.
- `onChange?: (value: unknown, change: JsonViewerChange) => void`. Called with the whole new document after every edit, undo and redo.
- `baseline?: unknown`. The saved document. Fields that differ from it carry the unsaved-changes dot.
- `className?: string`. Merged onto the outer container, for width and margins.

### Code snippet tabs

- Level: Molecule
- Category: Content
- Status: Stable
- Import: `@oration/canon/components/code-snippet-tabs`
- Exports: `CodeSnippetTabs`
- Docs: /design/components/code-snippet-tabs

Code snippet tabs show one example in several languages or platforms, one tab each, with a copy button for the visible snippet and optional setup instructions above. It is how Oration hands over the web-call widget embed (HTML, React, iOS) and API calls (cURL, Node, Python) in Settings and the agent widget config. It looks like Code block with a line tab strip in the title bar. The mistake is using it for one snippet, which adds a tab strip with nothing to switch.

When to use:
- For install or embed code in several platforms: the web-call widget as HTML, React and iOS.
- For the same API call in several languages: cURL, Node, Python.
- When setup needs one line of instructions above the code, such as which key to paste.
- For a multi-step guide where each step's snippet follows one language choice, with a shared controlled `value`.

When not to use:
- For a single snippet. Use a titled code block. Use /design/components/code-block instead.
- For one key or URL on a line. Use /design/components/copy-row instead.
- For switching between whole panels of content. Use /design/components/tabs instead.
- For a payload people read rather than copy and run. Use /design/components/code-block instead.

Rules:
- The Machine Mono Rule: Code and the strings inside instructions (`ORATION_API_KEY`, `YOUR_PUBLIC_KEY`) are Geist Mono. Tab labels are language names in Geist Sans: cURL, Node, iOS.
- The Scroll Edge Rule: When the tab strip overflows, it scrolls sideways and fades its clipped side over 2rem through `useOverflowFade`, instead of wrapping.

Anatomy:
- Instructions: Optional 13px Slate Meta line above the block. `code` inside it renders in Geist Mono and ink.
- Tab list: A line tab strip in the 36px title bar, 12px medium labels, scrolling with an edge fade when it overflows.
- Active tab: Ink label with a 2px ink underline sitting on the bar's bottom hairline.
- Copy button: A 24px ghost Copy button for the visible snippet, named Copy {label} snippet.
- Code panel: 12px Geist Mono on Row Mist with 12px padding, scrolling sideways on long lines.

States:
- Tab rest: Slate Meta label, no underline.
- Tab hover: The label turns ink over 150ms.
- Tab focus visible: Ink label and an inset 2px Focus Indigo ring at 50%.
- Tab active: Ink label and the 2px underline, which fades in over 150ms.
- Panel focus visible: The code panel is focusable and draws an inset 2px ring at 50%.
- Copied: The copy icon swaps to a green check and the button reads Copied for 1.6s.
- Empty: With no snippets the component renders nothing.

Behavior:
- Uncontrolled by default, starting on `defaultValue` or the first snippet. Pass `value` and `onValueChange` to control it, for example to share one language choice across several blocks.
- If the stored tab no longer exists in `snippets`, it falls back to the first snippet.
- The copy button always copies the visible snippet's `code`, exactly as written.
- Built on Base UI Tabs: arrow keys move focus along the strip and wrap at the ends; Enter or Space selects. Inactive panels unmount.
- `language` is written to the `<code>` element as `data-language`. Nothing highlights it today.
- Tab switches don't animate beyond the underline's 150ms fade.

Do and don't:
- Do: Use tabs when there are at least two languages or platforms to choose between.
- Don't: Wrap one snippet in tabs. The strip has nothing to switch and looks like a missing option.

Content:
- Tab labels are the language or platform's own name: cURL, Node, Python, HTML, React, iOS.
- Instructions are one sentence of setup, with the thing to replace in code: Set `ORATION_API_KEY` to a key from Settings, API keys.
- Order tabs by how many people need them, most common first. For the widget that's HTML.
- Use environment variables or clear placeholders for secrets in every language, never a real key.
- Give the tab list a `label` that names the example (Widget embed code), not the default Code examples.

Accessibility:
- The strip is a Base UI `tablist` of `tab`s with `aria-selected`, and each panel is a `tabpanel`. Name the list with `label`.
- The copy button's name includes the language (Copy Python snippet), so screen reader users know which version they copied.
- The focus ring on tabs and panels is 2px and inset, drawn inside the title bar, so it isn't clipped by `overflow-hidden`.
- The panel takes focus, but the scrolling `<pre>` inside it doesn't, so arrow keys can't scroll a clipped line. Keep lines short.
- Instructions are plain text above the block; they aren't linked to the panel. If they matter to the snippet, repeat them in the surrounding copy.
- Tab: Moves to the selected tab, then the copy button, then the panel.
- ← + →: Moves focus between tabs, wrapping at the ends.
- Enter + Space: Selects the focused tab.

Known gaps (follow the system, not the gap):
- `language` is stored as `data-language` but nothing highlights it, so every language renders as plain mono.
- The Channels widget setup passes a single HTML snippet, which renders a one-tab strip.
- The Channels widget setup doesn't pass `label` either, so its tab list is named Code examples.
- The web-call widget embed is written three ways across Settings: a `<script data-key>` tag on the Channels page, a `window.Oration` config on Public keys and an `<oration-widget>` element in the agent's widget config.
- Like Code block, it draws the hairline lift and has no flat variant for use inside a card.

API `CodeSnippetTabs`:
- `snippets: { id: string; label: string; language: string; code: string }[]`. One entry per tab, in order.
- `instructions?: React.ReactNode`. Setup notes above the block.
- `value?: string`. The selected snippet `id`. Controlled.
- `defaultValue?: string`. The first selected `id`. Defaults to the first snippet.
- `onValueChange?: (id: string) => void`. Called when a tab is selected.
- `label?: string` = "Code examples". Accessible name for the tab list.
- `className?: string`. Merged onto the outer column, for width.

### QR code

- Level: Molecule
- Category: Content
- Status: Stable
- Import: `@oration/canon/components/qr-code`
- Exports: `QRCode`
- Docs: /design/components/qr-code

QR code renders a scannable code for a URL, phone number or setup secret on a white tile, with an optional PNG download. Oration uses it to share an agent's call page and to test the WhatsApp channel from a phone. The modules stay black on white in both themes, because many scanners fail on inverted codes. What people forget is the name: the default accessible label is just QR code, so always say what it opens.

When to use:
- To move a link from screen to phone: an agent's public call page, a WhatsApp chat, a supplier portal sign-in.
- For a code people will print, such as on supplier onboarding packets or remittance notices, with `downloadName`.
- To add an account to an authenticator app during two-step setup, beside the typed setup key.
- Beside the same link as text with a copy button, never instead of it.

When not to use:
- As the only way to reach a link. Show the URL with a copy button too. Use /design/components/copy-row instead.
- For a decorative identity mark. Use /design/components/identicon instead.
- For a code people read and type, such as a join code. Use /design/components/input-otp instead.

Rules:
- Black on white, always: The tile stays white and the modules black in dark mode too. Don't invert, tint or recolor a code; scanners expect dark modules on a light ground.
- The Machine Mono Rule: The link or secret shown beside a code is a machine string, so it's Geist Mono. The caption explaining it is Geist Sans.

Anatomy:
- Tile: A white tile with 12px corners, 12px of padding and a 10% ink outline (white at 10% in dark), so it reads on any surface.
- Code: An SVG at `size` pixels with `role="img"` and your `label` as its name.
- Download: Optional with `downloadName`: an outline `sm` button that saves a 1024px PNG.

States:
- Default: The tile and code, at 160px unless `size` says otherwise.
- With download: The tile, then a 12px gap and the Download PNG button, centered under it.
- Dark theme: Unchanged: a white tile with black modules. Only the tile's outline turns to white at 10%.

Behavior:
- The code updates whenever `value` changes; there's no loading state.
- The visible code is an SVG, so it stays sharp at any size and zoom.
- With `downloadName`, a hidden 1024px canvas renders the same value with a four-module quiet zone. The button saves it as `{downloadName}.png`, adding the extension if you left it off.
- `level` sets error correction: L recovers about 7% of a damaged code, M about 15% (the default), Q about 25% and H about 30%. Higher levels mean more, smaller modules at the same size.
- The on-screen tile's 12px padding is the quiet zone. Keep other content from crowding the tile's edge.

Do and don't:
- Do: Name the code for what it opens: QR code to call the Cedarline supplier line.
- Don't: Leave the default label. Screen reader users hear QR code, image and learn nothing.
- Do: Keep the white tile and black modules in dark mode.
- Don't: Invert the code to match a dark theme. Many phone scanners won't read light modules on a dark ground.

Content:
- Put one sentence beside the code that says what scanning does: Scan with your phone to open a chat with Cedarline on WhatsApp.
- Show the same link or key as text, in Geist Mono, with a copy button.
- Name downloads for what they are: `cedarline-whatsapp`, `where-is-my-payment-qr`.
- Keep the default button label, Download PNG, unless the format changes.

Accessibility:
- The SVG is `role="img"` with `aria-label` from `label`. Name the destination: QR code for Cedarline on WhatsApp.
- A code is unusable without a camera. Always offer the same link or secret as selectable text beside it.
- The hidden download canvas is `aria-hidden` and `display: none`, so it's never announced.
- The download button's icon is decorative; the label names the action.
- Tab: Moves to the download button, if there is one.
- Enter: Downloads the PNG.

Known gaps (follow the system, not the gap):
- The tile draws its edge with a CSS `outline` at 10% ink rather than the hairline lift. That's deliberate so the tile stays white in dark, but it's a different edge from every other raised surface.
- The on-screen code has no margin of its own; its quiet zone is the tile's 12px padding, two to three modules for a typical link at the default size, where the QR spec asks for four. The downloaded PNG has the full four.
- The default `label` is QR code. It would be safer as a required prop.
- There's no feedback after a download; the browser's own download UI is the only confirmation.

API `QRCode`:
- `value: string`. What the code encodes: a URL, `tel:` number or `otpauth://` URI.
- `size?: number` = 160. Width and height of the code in pixels, before the tile's padding.
- `label?: string` = "QR code". Accessible name of the code image.
- `downloadName?: string`. File name for the PNG. Setting it shows the download button.
- `downloadLabel?: string` = "Download PNG". The download button's label.
- `level?: "L" | "M" | "Q" | "H"` = "M". Error correction level.
- `className?: string`. Merged onto the outer column.

### Video facade

- Level: Molecule
- Category: Content
- Status: Beta
- Import: `@oration/canon/components/video-facade`
- Exports: `VideoFacade`, `VideoRef`
- Docs: /design/components/video-facade

Video facade is a help video's poster: the YouTube thumbnail, a play disc and the duration, which swaps to the privacy-enhanced player only when someone presses play. It keeps education cheap, so Get started, Info tips and Page intros can offer a video without loading a player on every page. The videos are stand-ins until Oration's own exist. The mistake is a vague title: the title is the button's accessible name and the iframe's, so it must say what the video teaches.

When to use:
- For a short help video beside the thing it explains: Build your first voice agent on Get started.
- Inside an Info tip, for jargon that's faster to show than tell, such as Warm transfer.
- In a dialog opened from Watch the 3-minute overview, with `autoLoad` since the click already happened.
- For a short list of help videos on an overview or help page.

When not to use:
- For a page-level introduction with a video link. The banner handles dismissal and the dialog. Use /design/components/page-intro instead.
- For a quick explanation of a term. Start with text; add the video inside it. Use /design/components/info-tip instead.
- For call recordings or voicemail, which need a waveform and scrubbing. Use /design/components/waveform instead.
- For images or illustrations that don't play. Use /design/components/illustration instead.

Rules:
- No autoplay without a click: The player loads and plays only after someone presses play, or with `autoLoad` inside a dialog they opened to watch it. Never autoload on page load.
- The Tabular Figures Rule: The duration badge is set in tabular figures, and the same duration is spoken in words for screen readers: 3 minutes 12 seconds.

Anatomy:
- Frame: A 16:9 box with 12px corners on Well Gray, with a 10% ink outline (white at 10% in dark) so light thumbnails keep an edge.
- Thumbnail: The video's `hqdefault` poster from YouTube, lazy-loaded, covering the frame.
- Play disc: A 44px White Plane circle with a filled 18px play glyph and a soft shadow.
- Duration: A 20px badge at the bottom right: white 12px tabular figures on black at 75%.

States:
- Poster: Thumbnail, play disc and duration. The whole frame is one button.
- Hover: The play disc grows to 1.04 over 150ms on ease-out. No change under reduced motion.
- Pressed: The disc scales to 0.96 while held.
- Focus visible: The global 2px Focus Indigo outline applies, offset 2px outside the button, but the frame's `overflow-hidden` clips it, so no ring shows today. See Known gaps.
- Playing: The button is replaced by a `youtube-nocookie.com` iframe that autoplays, and focus moves into it.
- Loading: Before the thumbnail arrives the frame shows Well Gray with the play disc and duration already in place.

Behavior:
- Nothing from the player loads until the button is pressed. The thumbnail itself is an `<img>` from `i.ytimg.com`, loaded lazily.
- Pressing play renders the iframe with `autoplay=1&rel=0` and moves focus into it, so keyboard users land in the player they asked for.
- `autoLoad` renders the iframe straight away and doesn't move focus. Use it only where a click already asked for the video, such as a video dialog.
- The frame fills its container's width at 16:9. Constrain it with `max-w-*` or the parent, and round it to the container's radius with `className` (for example `rounded-lg` inside a card with 8px padding).
- `spokenDuration("3:12")` returns 3 minutes 12 seconds for the button's name; `durationMinutes("3:12")` returns `3`, at least 1, for labels like Watch the 3-minute overview.

Do and don't:
- Do: Title the video with what it teaches and show that title beside the poster.
- Don't: Use a generic title such as Video. The play button is announced as Play video: Video, and the poster says nothing on its own.

Content:
- Titles are sentence case and start with what you'll be able to do: Build your first voice agent, Set up the web-call widget.
- Durations are clock time: `3:12`, `1:04:30`. Keep help videos under about five minutes.
- A caption under the poster says why to watch now, in one line: Worth a watch before you test Where is my payment.
- Links that open a video say its length: Watch the 3-minute overview.

Accessibility:
- The poster is one `<button>` named Play video: {title}, {spoken duration}. The thumbnail has empty alt text and the disc and badge are `aria-hidden`.
- The iframe is titled with `video.title`, so screen readers announce the player by name.
- Focus moves into the player after pressing play, but not with `autoLoad`.
- The disc's scale is turned off under reduced motion. YouTube's own player controls captions and autoplay once it loads.
- The global focus outline sits 2px outside the button and the frame's `overflow-hidden` clips it, so keyboard users get no visible focus on the poster until the component draws an inset ring.
- Tab: Moves to the poster button.
- Enter + Space: Loads the player and starts the video.

Known gaps (follow the system, not the gap):
- The poster button's focus outline is drawn 2px outside it by the global rule, and the frame's `overflow-hidden` clips it. Keyboard focus on the poster draws no visible ring.
- The thumbnail loads from `i.ytimg.com` as soon as the poster scrolls into view, so a request reaches Google before anyone presses play. Only the player uses the privacy-enhanced domain.
- The videos are public YouTube explainers standing in for Oration's own. Get started still titles its stand-in with the original video's topic, A primer on how agents learn at 18:40.
- The frame's edge is a CSS outline at 10% ink rather than the hairline lift.

API `VideoFacade`:
- `video: { youtubeId: string; title: string; duration: string }`. The video. `title` names the button and the iframe; `duration` is clock time such as `"3:12"`.
- `autoLoad?: boolean` = false. Render the player immediately. Only where a click already asked for the video.
- `className?: string`. Merged onto the frame, usually for radius or max width.

API `VideoRef`:

API `spokenDuration`:

API `durationMinutes`:

### Attachment

- Level: Molecule
- Category: Content
- Status: Experimental
- Import: `@oration/canon/components/attachment`
- Exports: `Attachment`, `AttachmentGroup`, `AttachmentMedia`, `AttachmentTitle`, `AttachmentActions`
- Docs: /design/components/attachment

Attachment is a file chip: a media tile, the file name, one line of detail and optional actions, with states for idle, uploading, processing, error and done. It's meant for files on a reply, a ticket or a message, laid out in a scrolling `AttachmentGroup`. It is experimental: the Contact Center composer and threads still hand-roll smaller chips. The mistake is a vague error; the description line is where the chip says what went wrong and what to do.

When to use:
- For files attached to a reply before it's sent, with upload progress and a remove action.
- For files on a sent message, ticket or conversation that people open, through `AttachmentTrigger`.
- For a document a flow is checking, such as a W-9 being matched, in the `processing` state.
- For a row of document thumbnails that scrolls sideways, with `orientation="vertical"`.

When not to use:
- For the drop target people drag files onto. Use /design/components/dropzone instead.
- For a value on a record, such as a tier or stage. Use /design/components/tag instead.
- For an active filter. Use /design/components/filter-chip instead.
- For retrieved knowledge sources in an AI answer. Use /design/components/source-cards instead.
- For a row in a list of documents with several columns. Use /design/components/table instead.

Rules:
- The Label-Beside-Color Rule: An error chip turns its border and media red, but the description always says what failed: File is over 10 MB, not just a red tint or Error.
- The Machine Mono Rule: File names stay in Geist Sans. They are names people read, not strings a machine will parse.

Anatomy:
- Container: `Attachment`: a Card White chip with 12px corners and a hairline border (dashed when idle, red at 30% on error).
- Media: `AttachmentMedia`: a 40px Well Gray tile (32px at `sm`, 28px at `xs`) holding a file icon, a spinner or an image.
- Title: `AttachmentTitle`: the file name in medium weight, truncated. It shimmers while uploading or processing.
- Description: `AttachmentDescription`: size, progress or the error, in 12px Slate Meta (red at 80% on error).
- Actions: `AttachmentActions` with `AttachmentAction` ghost 24px icon buttons, such as Retry and Remove.

States:
- Idle: A dashed border: a slot waiting for a file, such as Add a W-9.
- Uploading: The title shimmers, image media dims to 60%, and the description carries progress.
- Processing: Same treatment as uploading, for work after the upload such as a virus scan or TIN check.
- Error: Border at 30% red, a red-tinted media tile and a red description that says what failed.
- Done: The resting chip at full opacity.
- Hover: With an `AttachmentTrigger`, the chip fills Well Gray at 50%.
- Focus visible: Whenever anything inside has focus, the chip draws a 1px Focus Indigo ring at 50%.

Behavior:
- `state` only changes the look and sets `data-state`; you drive it from your upload code.
- `AttachmentTrigger` is an invisible button covering the chip (`absolute inset-0 z-10`). Actions sit above it at `z-20`, so remove and retry stay clickable.
- `AttachmentGroup` lays chips in one row that scrolls sideways with snap points and fades its clipped edges with `scroll-fade-x`.
- Vertical chips are 96px wide (120px with text) and float their actions over the top-right of the media.
- Image media dims to 60% until the attachment is `done` or `idle`.
- The title's shimmer runs for as long as the state is uploading or processing.

Do and don't:
- Do: Say what failed and how to fix it in the description, with an alert icon in the media.
- Don't: Show a red chip that only says Error. People can't tell whether to retry, shrink the file or pick another.

Content:
- Titles are the file name as uploaded, including the extension: bank-letter-northwind.pdf.
- Descriptions are one short fact: size (212 KB), progress (Uploading, 62%), the work in progress (Checking the TIN) or the error (File is over 10 MB).
- Error text says what to do when it isn't obvious: Upload failed. Try again.
- Name actions with the file: Remove w9-halcyon.pdf, Retry w9-halcyon.pdf.
- Idle slots say what belongs there: Add a W-9, with the accepted type and size as the description.

Accessibility:
- Icon-only actions need an `aria-label` that names the file and a tooltip. `AttachmentAction` is a Button and takes both.
- `AttachmentTrigger` has no text of its own; give it an `aria-label` such as Open bank-letter.pdf.
- State is visual only. Announce upload progress and failures in a polite live region, and include the state in the description text.
- The spinner inside media has `role="status"` and the name Loading; the description should still say what's loading.
- The shimmer isn't stopped under reduced motion.
- The group scrolls sideways, and chips are focusable only through their triggers and actions. Keep the most important files first.
- Tab: Moves to each chip's trigger, then its actions.
- Enter: Opens the file or runs the focused action.

Known gaps (follow the system, not the gap):
- Attachment isn't imported anywhere in apps/web. The Contact Center composer hand-rolls 24px `bg-muted` chips and the threads 28px `bg-muted/70` chips, both with a paperclip and no states.
- The chip is a Card White surface with a CSS border. By The Hairline-and-Lift Rule a raised chip takes its edge from `shadow-border`, and inside a message or card it would be a tint well instead.
- The focus indicator is `focus-within:ring-1 ring-ring/50`, a 1px ring where Canon uses 3px.
- The title's `shimmer` isn't stopped under reduced motion; `globals.css` only stops `text-shimmer` and `skeleton-shimmer`.
- `AttachmentGroup` uses `scrollbar-none`, which isn't a utility in this Tailwind setup, so the group shows the thin global scrollbar.
- The registry's export list omits `AttachmentContent`, `AttachmentDescription`, `AttachmentAction` and `AttachmentTrigger`.

API `AttachmentMedia` (extends <div>):
- `variant?: "icon" | "image"` = "icon". `image` crops an `<img>` to a square and dims it until done.

API `AttachmentContent` (extends <div>):

API `AttachmentTitle` (extends <span>):

API `AttachmentDescription` (extends <span>):

API `AttachmentActions` (extends <div>):

API `AttachmentAction` (extends Button):
- `variant?: Button variant` = "ghost". Any Button variant.
- `size?: Button size` = "icon-xs". Any Button size.

API `AttachmentTrigger` (extends Base UI `useRender` props for `<button>`):
- `render?: ReactElement | (props, state) => ReactElement`. Render as another element, such as a link to the file.

API `AttachmentGroup` (extends <div>):

### Bubble

- Level: Molecule
- Category: Content
- Status: Experimental
- Import: `@oration/canon/components/bubble`
- Exports: `Bubble`, `BubbleContent`, `BubbleGroup`, `BubbleReactions`
- Docs: /design/components/bubble

Bubble is one chat message's body: a rounded fill that sits left for the other party and right for your side, grouped with its neighbours and optionally carrying reactions. It's for human conversations on chat, SMS, WhatsApp and the web widget, usually inside a Message. It is experimental and the Contact Center thread still hand-rolls its bubbles. The mistake is the default variant: it fills the bubble with Quiet Indigo, which The Quiet Indigo Rule saves for the primary action, selection and focus, so pick `muted` and `outline` for conversations.

When to use:
- For messages in a chat-style channel: web widget chat, SMS, WhatsApp, social DMs.
- For a run of consecutive messages from one sender, inside a `BubbleGroup`.
- For quick replies people tap in the widget, with `BubbleContent` rendered as a button.
- For a message that failed to send, in the `destructive` tint with a retry.

When not to use:
- For email, where each message needs sender, recipients and quoted text. Use /design/components/message instead.
- For an AI assistant's turn in the Copilot or Knowledge base. Use /design/components/ai-message instead.
- For internal notes between agents. Those are tint wells in the thread, not bubbles. Use /design/components/well instead.
- For a call transcript. Use /design/components/live-transcript instead.

Rules:
- The Quiet Indigo Rule: Indigo is for the view's primary action, selection, focus and labelled live state. Conversation bubbles are `muted` for the other party and `outline` for your side; the indigo `default` variant stays out of the thread.
- The Label-Beside-Color Rule: Side and fill aren't enough to say who spoke. Every group carries the sender's name as text, and a failed bubble says Not delivered beside its red tint.

Anatomy:
- Group: `BubbleGroup`: a column of consecutive bubbles from one sender, 8px apart.
- Bubble: `Bubble`: the wrapper that sets the variant and alignment, up to 80% of the thread's width.
- Content: `BubbleContent`: the rounded fill, 12px corners and 12px by 8px padding, 14px text at a relaxed line height.
- Reactions: `BubbleReactions`: an optional Well Gray pill that overlaps the bubble's top or bottom edge, ringed in Card White.

States:
- Rest: The variant's fill. Content wraps and never overflows the bubble.
- Hover: Only when `BubbleContent` renders a button or link: the fill steps darker (for `outline`, to Well Gray).
- Focus visible: Button or link content gets an indigo border and a 3px Focus Indigo ring at 50%.
- Failed: The `destructive` variant: a 10% Signal Red tint with red text, and a Not delivered line with Retry beneath.
- Sent, delivered, read: Not drawn by Bubble. Put it in a meta line under the group, as text with an icon.

Behavior:
- `align="end"` pushes a bubble to the right. Inside a Message with `align="end"`, bubbles follow automatically.
- Bubbles are `w-fit` up to 80% of their container; the `ghost` variant drops the fill and padding and runs full width.
- `BubbleContent` takes `render`, so a bubble can be a `<button>` (quick replies) or `<a>`. Only then does it get hover and focus styles.
- `BubbleReactions` is absolutely positioned: give the bubble bottom margin (`mb-4`) so the pill doesn't overlap the next one. Buttons inside it drop its padding.
- Bubbles don't animate by themselves. The product thread fades new messages up 8px from 0.98 on `spring.moderate`.

Do and don't:
- Do: Draw the other party in `muted` and your side in `outline`, so the thread stays calm and indigo stays for actions.
- Don't: Use the default indigo fill for outbound messages. A thread of indigo bubbles outshouts the reply button.

Content:
- Write messages as you'd say them to a supplier: short sentences, the invoice number and amount when they matter.
- Quick replies are the supplier's words, in first person: Where is my payment?, Update my bank details.
- Sender names and timestamps go outside the bubble, in 12px and 11px Slate Meta.
- Reactions use icons with a count, not emoji; the suite doesn't put emoji in UI.

Accessibility:
- Bubbles are plain `<div>`s. Wrap the conversation in `role="log"` with a name so new messages are announced in order.
- Give every group a visible or `sr-only` sender name. Screen readers don't see which side a bubble sits on.
- Quick reply bubbles are real buttons through `render`, with the reply text as their name.
- Reaction buttons need `aria-pressed` and a name that says the reaction and the action: React with thumbs up.
- A failed bubble's state must be in text (Not delivered) next to it, not only in the red tint.
- Tab: Moves to bubbles rendered as buttons or links, and to reaction buttons.
- Enter: Sends a quick reply or toggles a reaction.

Known gaps (follow the system, not the gap):
- The `default` variant is a solid Quiet Indigo fill, which The Quiet Indigo Rule doesn't allow for message content. `tinted` also derives from `--primary`.
- Bubble isn't imported anywhere in apps/web. The Contact Center chat thread hand-rolls bubbles with `rounded-2xl` and a tighter corner on the sender's side, `bg-muted` for the supplier and Card White with `shadow-border` for the agent.
- The `outline` variant draws a CSS border on a light fill, while the product's outbound bubble uses the hairline lift.
- There's no tail or grouped-corner treatment, and no built-in sender, time or delivery status.
- The hover on interactive `default` bubbles is `bg-primary/80`, a lighter fill, where primary buttons darken by mixing 9% black.

API `BubbleContent` (extends Base UI `useRender` props for `<div>`):
- `render?: ReactElement | (props, state) => ReactElement`. Render as a `<button>` or `<a>` to make the bubble interactive.

API `BubbleGroup` (extends <div>):

API `BubbleReactions` (extends <div>):
- `side?: "top" | "bottom"` = "bottom". Which edge it overlaps.
- `align?: "start" | "end"` = "end". Which corner it sits near, 12px in.

### Message

- Level: Molecule
- Category: Content
- Status: Experimental
- Import: `@oration/canon/components/message`
- Exports: `Message`, `MessageAvatar`, `MessageContent`, `MessageHeader`, `MessageFooter`, `MessageGroup`
- Docs: /design/components/message

Message lays out one turn of a human conversation: an avatar, a header with the sender, the content (usually one or more Bubbles) and a footer with the time or delivery state, mirrored for your own side with `align="end"`. It's for Contact Center and ticket threads across chat, SMS, WhatsApp and email, and is distinct from the AI message used by the Copilot. It is experimental; the product's threads still hand-roll this layout. The thing people get wrong is identity: alignment tells sighted people who spoke, but the header must say it in words.

When to use:
- For a turn in a chat-style thread: web widget chat, SMS, WhatsApp, social DMs, with Bubbles inside.
- For an email in a ticket or conversation, with a `ghost` Bubble so the body runs full width.
- For a message that carries files, with Attachments inside the content column.
- For several consecutive messages from one sender, under one header and footer.

When not to use:
- For an AI assistant's turn, with streaming, actions and branches. Use /design/components/ai-message instead.
- For the scrolling container that keeps the latest message in view. Use /design/components/message-scroller instead.
- For internal notes between agents. Use a tint well so they never read as sent. Use /design/components/well instead.
- For a live call transcript. Use /design/components/live-transcript instead.
- For an activity entry such as Priya assigned this ticket. Use /design/components/timeline instead.

Rules:
- The Label-Beside-Color Rule: Side and fill never carry identity or state alone. The header names the sender and the footer says Delivered, Read or Not delivered in words.
- The Quiet Indigo Rule: Messages are `muted` for the other party and `outline` for your side. Indigo stays for the reply button and the viewer's own markers, such as an @mention of you.

Anatomy:
- Message: `Message`: a row with 8px between avatar and content, reversed for `align="end"`.
- Avatar: `MessageAvatar`: a round slot at least 32px wide, aligned to the bottom so it sits beside the last bubble.
- Header: `MessageHeader`: the sender's name in 12px medium Slate Meta, inset 12px to line up with bubble text.
- Content: `MessageContent`: a column of bubbles, attachments and anything else, 10px apart.
- Footer: `MessageFooter`: the time and delivery state in 12px Slate Meta, right-aligned on your side.

States:
- Inbound: `align="start"`: avatar left, content left, `muted` bubbles.
- Outbound: `align="end"`: the row reverses, content and footer align right, `outline` bubbles.
- Grouped: Several bubbles share one header and footer. Tighten the content gap with `gap-1`.
- Email: A `ghost` bubble drops the padding, and the header and footer lose their 12px inset to match.
- Failed: A `destructive` bubble and a footer that says Not delivered with Retry.

Behavior:
- `align="end"` sets `data-align="end"`: the row reverses and every direct child of the content column aligns right, including Bubbles.
- The avatar aligns to the bottom of the row. When the message has a footer, it shifts up 32px to sit beside the last bubble rather than the footer.
- Headers and footers inset 12px to line up with bubble text, and drop the inset when the message contains a `ghost` bubble.
- Message is layout only: no state, no roles, no motion. The product thread animates new messages in on `spring.moderate`.

Do and don't:
- Do: Show internal notes as a tint well with a note icon and Internal note, so they can't be mistaken for a reply.
- Don't: Render a note as an outbound message. It reads as sent to the supplier.

Content:
- Headers are the sender's display name: Halcyon Supply, Jordan Lee. Add the email address only on email.
- Footers are the time and delivery state, as words: 9:43 AM, Read, Not delivered.
- Times are in the viewer's time zone and tabular figures. Older messages add the date: Sep 26, 4:12 PM.
- Don't join header parts with dots; use gaps or a comma.

Accessibility:
- Message renders plain `<div>`s. Wrap the thread in `role="log"` with a name, and consider an `<article>` per email.
- Keep the sender's name in the header on every group, visible or `sr-only`. Alignment and color aren't announced.
- Avatars are decorative next to a named header; don't give them alt text that repeats the name.
- Delivery icons need their word beside them (Read, Delivered), not only a check mark.
- Controls inside messages, such as Show quoted text, need `aria-expanded` when they reveal content.

Known gaps (follow the system, not the gap):
- Message isn't imported anywhere in apps/web. The Contact Center chat and email threads hand-roll their own layout.
- The avatar's upward shift is a fixed 32px (`-translate-y-8`) that assumes a one-line footer and the default 10px content gap. A wrapping footer or a tighter gap, as in consecutive messages, moves the avatar off the last bubble, and a top-aligned avatar (`self-start`, as in the email example) is pushed above the message unless you also pass `group-has-data-[slot=message-footer]/message:translate-y-0`.
- `MessageHeader` and `MessageFooter` merge classes with `cn` from the `cn` package, so `text-13` passed to them reads as a color. Use `text-[13px]`.
- The email thread in the product draws each email as its own card; Message has no email layout beyond a `ghost` bubble.

API `Message` (extends <div>):
- `align?: "start" | "end"` = "start". Start for the other party, end for your side.

API `MessageAvatar` (extends <div>):

API `MessageContent` (extends <div>):

API `MessageHeader` (extends <div>):

API `MessageFooter` (extends <div>):

API `MessageGroup` (extends <div>):

### Key-value editor

- Level: Molecule
- Category: Editors
- Status: Stable
- Import: `@oration/canon/components/key-value-editor`
- Exports: `KeyValueEditor`, `KeyValuePair`
- Docs: /design/components/key-value-editor

Key-value editor edits a list of named values in rows: headers on a lookup webhook, variables passed to the widget, fields on an assist card. Keys are set in Geist Mono, a value can be marked secret so it is masked until revealed, and a key used twice is flagged in place. It is fully controlled, and the array is yours: keep `secret` alongside each key and value when you save, and drop rows with an empty key before sending them anywhere.

When to use:
- For HTTP headers on a webhook or an API request, with `allowSecret` for tokens.
- For variables and metadata passed to an agent, a widget or a flow step.
- For a short list of label and template pairs, such as fields shown on an assist card.
- When rows are added and removed often and their order is kept.

When not to use:
- For a list of single values, such as allowed domains. Use /design/components/tag-input instead.
- For one read-only secret or ID that people copy. Use /design/components/copy-row instead.
- For typed, nested structures with required fields and descriptions. Use /design/components/json-schema-builder instead.
- For a fixed set of settings with known names. Give each its own labelled field. Use /design/components/field instead.

Rules:
- The Machine Mono Rule: Keys are machine strings, so they are always Geist Mono. Values are mono only when masked as secrets; plain values such as a tenant name stay in Geist Sans.
- Secrets stay masked: Tokens and keys are masked by default and revealed one row at a time. Revealing is local to the viewer and never changes what is saved.

Anatomy:
- Column headers: 12px Slate Meta labels from `keyLabel` and `valueLabel`, shown from 640px up.
- Key: A 32px Input in Geist Mono, two fifths of the row.
- Value: An Input group, three fifths of the row. A secret value is masked and gets an eye button to reveal it.
- Row actions: 32px ghost icon buttons with tooltips: the lock that marks a value secret (with `allowSecret`) and the X that removes the row.
- Key error: 13px Signal Red text under the row, linked to the key input.
- Add button: A small outline button with a plus, and a 3/6 count when `max` is set.

States:
- Empty: `emptyText` in 13px Slate Meta above the add button.
- Rest: Rows of key and value inputs at rest.
- Focus visible: Each input takes its own indigo border and 3px ring.
- Invalid key: A duplicate key, or one `validateKey` rejects, gets a red border and ring and a message under the row.
- Secret, masked: The value shows as dots in Geist Mono; the lock button is pressed, with a Menu Hover fill.
- Secret, revealed: The eye button shows the value for this viewer only.
- Full: At `max`, the add button is disabled and the count reads 6/6.
- Disabled: Every input and button is disabled.

Behavior:
- Add row appends an empty pair and moves focus to its key.
- Removing a row moves focus to the key that takes its place, or the one above when it was last.
- The lock button toggles `secret` on the row through `onChange` and masks the value again.
- The eye button reveals or hides one masked value. Reveal state is local and resets when the row is re-masked.
- Keys are compared trimmed; every row with a repeated key shows This key is used more than once. `validateKey` runs after the duplicate check; return a message or `null`.
- Below 640px the column headers hide and each row wraps: the key on its own line, then the value and actions.
- Nothing is filtered for you: empty keys and values are kept in the array until you drop them.

Do and don't:
- Do: Mark tokens and signing secrets as secret so they are masked on screen and in screenshots.
- Don't: Leave an `Authorization` header in plain text for anyone looking over a shoulder.
- Do: Validate key format with `validateKey` and say the rule: Use lowercase snake_case.
- Don't: Accept any key and let the webhook or template fail later on `Vendor ID`.

Content:
- Name the columns for what they hold: Header and Value, Variable and Value, Label and Value.
- Placeholders are real examples: `Authorization` and Bearer …, `vendor_id` and `{{portal.vendor_id}}`.
- The add button names the thing: Add header, Add variable, Add field.
- `emptyText` says what happens with no rows: No headers. Authentication headers are added for you.

Accessibility:
- Every input is named on its own: Header, row 2 for a key and Value for Authorization for its value, so the hidden column headers aren't needed.
- Key errors are linked to their input with `aria-describedby` and mark it `aria-invalid`.
- The lock is a toggle button with `aria-pressed`, named Mask as secret or Stop masking value; the remove button is named for its row.
- Adding and removing rows moves focus to a key input, so keyboard users never land on the page body mid-edit, except after removing the last row.
- Action buttons are 32px, above the 24px minimum.
- Tab: Moves through each row: key, value, reveal, lock, remove, then the add button.
- Enter: Activates the focused button. It doesn't add a row from an input.
- Space: Toggles the lock or reveal button.

Known gaps (follow the system, not the gap):
- The eye button in a secret row has no tooltip, while the lock and remove buttons beside it do.
- Masked values are `type="password"` inputs, so browsers and password managers may offer to fill or save them despite `autoComplete="off"`.
- Removing the only row drops focus to the page.
- Key errors aren't announced when they appear, only linked to the input; values are never validated.

API `KeyValueEditor`:
- `value: KeyValuePair[]`. The rows.
- `onChange: (value: KeyValuePair[]) => void`. Called with the next rows on every edit, add, remove and mask.
- `keyLabel?: string` = "Key". Key column header and input name.
- `valueLabel?: string` = "Value". Value column header and input name.
- `keyPlaceholder?: string` = "key". Key placeholder.
- `valuePlaceholder?: string` = "Value". Value placeholder.
- `addLabel?: string` = "Add row". The add button's label.
- `emptyText?: ReactNode` = "Nothing added yet.". Shown when there are no rows.
- `allowSecret?: boolean` = false. Adds the lock button that masks a value.
- `validateKey?: (key: string) => string | null`. Return a message to flag a key, or `null` when it's fine.
- `max?: number`. The most rows allowed. Shows a count.
- `disabled?: boolean`. Disables every input and button.
- `className?: string`. On the root.

### Tool chip

- Level: Molecule
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/tool-chip`
- Exports: `ToolChip`
- Docs: /design/components/tool-chip

Tool chip shows one tool call inside a transcript or an assistant turn: its status, an optional plain-words summary, the tool's machine name in Geist Mono and how long it took. When there is an input, output or error, the chip is a disclosure that opens a tint well of copyable payloads. It lets people audit what an agent actually did (lookup_invoice, get_payment_status) without reading JSON by default. The common mistake is leading with the payload: keep chips closed and let the summary and status carry the story.

When to use:
- Under an agent's turn in a call transcript, one chip per tool call, in the order they ran.
- In a Copilot answer, where tool calls appear one at a time as they run and flip to done.
- When someone debugging an agent needs the exact arguments and result of a call.
- When a failed call needs its error message next to the turn that triggered it.

When not to use:
- For a plan of steps that tick through queued, running and done. Use /design/components/task-list instead.
- For the model's reasoning between tool calls. Use /design/components/thinking instead.
- For an action a person has to approve before it runs. Use /design/components/approval-card instead.
- For a long code sample or a response body worth reading in full. Use /design/components/code-block instead.
- For editing a tool's parameters. Use /design/components/json-schema-builder instead.
- For a background job's status in a table row. Use /design/components/status-label instead.

Rules:
- The Machine Mono Rule: The tool name and every payload are Geist Mono, because a machine wrote them. The summary label, the duration and the section titles stay in Geist Sans.
- The Tint Well Rule: The chip and its payload panel are 70% Well Gray with 10px corners. They sit inside a message or card without becoming a second bordered card.
- The Label-Beside-Color Rule: Each status has its own icon shape (dashed circle, spinner, check, alert), not only a color, and a screen-reader label: Queued, Running, Done, Failed.

Anatomy:
- Status icon: 14px: a dashed circle for queued, a spinner for running, a green check for done, a red alert for failed.
- Label: Optional plain-words summary in 13px ink: Found payment PMT-58213. It shimmers while running.
- Tool name: The registered name in 12px Geist Mono. Slate Meta when a label leads, ink when it stands alone.
- Duration: Tabular figures after it finishes: 540 ms, 1.34 s.
- Chevron: Only when there is a payload. Turns 180° while open.
- Payload well: Input, output and error sections, split by hairlines. Input and output are bare JSON viewers with a 240px scroll cap: fold, search, and copy any value or its path. The error is red 12px mono text.
- Copy button: One per section, named Copy input, Copy output or Copy error. Rows inside the input and output copy their own value or path.

States:
- Queued: A Faint Slate dashed circle. `status="pending"`.
- Running: A spinning loader in Slate Meta, the label (or the name) shimmering, no duration yet.
- Done: A Ledger Green check and the duration.
- Failed: A Signal Red alert and the duration. Pass `error` to show the message. `status="error"`.
- Hover: An expandable chip deepens from Well Gray at 70% to 100% over 150ms.
- Focus visible: A 3px Focus Indigo ring at 40% around the chip.
- Open: The chip keeps the deeper fill, the chevron turns and the payload well slides open.
- Not expandable: With no input, output or error it renders as a plain row with no chevron and no hover.
- Reduced motion: The spinner and shimmer stop and the panel opens without animating height.

Behavior:
- It is a Base UI Collapsible: the chip is the trigger button, and it sets `aria-expanded` and toggles the panel with Enter or Space.
- `defaultOpen` sets the initial state only; after that the person controls it. There is no controlled `open` prop.
- The panel's height animates over 200ms on the house ease-out through the shared collapsible styles, and snaps under reduced motion.
- Objects and arrays open as a JSON viewer tree, fully expanded up to 80 values. A string that holds a JSON document is parsed into the tree; any other string renders as written.
- Duration shows only once the status is done or failed. Under a second it reads in ms; under ten seconds with two decimals (1.34 s); beyond that with one.
- The chip is at most the width of its container and truncates the label and name, so a long name never breaks the row.

Do and don't:
- Do: Write the label as the outcome in plain words and let the mono name say which tool: Found payment PMT-58213, then lookup_payment_status.
- Don't: Repeat the tool name in the label or narrate the call: Called lookup_payment_status tool successfully.
- Do: Keep chips closed so the transcript reads as a conversation. Open the one that failed.
- Don't: Open every chip by default. The turn turns into a wall of JSON and the words get lost.

Content:
- `name` is the tool's registered name, exactly: `lookup_invoice`, `get_payment_status`, `resend_remittance`.
- `label` is optional. When you add it, write the result, not the action: Found payment PMT-58213, Sent remittance to Northwind Freight.
- If the label shows while running, write it so it works before the result exists, or change it when the call finishes: Looking up INV-20931 then Found invoice INV-20931.
- `error` is the message a developer would want, in plain words: ERP timeout after 2000 ms, not Error: undefined.

Accessibility:
- The chip is a `<button>` named by its label, tool name and status, such as Found payment PMT-58213 lookup_payment_status, Done.
- Status icons are `aria-hidden`; a visually hidden word carries the status.
- Status changes aren't announced. If a sequence of calls matters to a screen reader user, announce progress in a polite live region nearby.
- The spinner and label shimmer stop under reduced motion; the status word still changes.
- Copy buttons are icon buttons with names and tooltips. Payloads scroll inside a 240px box and keep their text selectable.
- Tab: Moves to an expandable chip, then into its copy buttons when open.
- Enter: Opens or closes the payload.
- Space: Opens or closes the payload.

Known gaps (follow the system, not the gap):
- The product never shows the queued state: Copilot chips appear only once they start running, and transcripts only have done calls.
- Transcript mock data always marks tool calls as successful, so the failed chip and its error section never render in the app today.
- There is no controlled `open`, so the app can't open a chip whose call fails after it mounted. Only `defaultOpen` applies, at mount.
- Status is shown by icon and color, with the word only for screen readers. A sighted user reads Failed from a red icon.
- `formatDuration` shares its name with the duration picker's `formatDuration`, which takes different arguments.

API `ToolChip` (extends Nothing. Only the props below are read.):
- `name: string`. The tool's machine name, e.g. `lookup_invoice`.
- `label?: string`. Plain-words summary shown before the name.
- `status: "pending" | "running" | "done" | "error"`. Queued, running, done or failed.
- `input?: unknown`. Arguments. Strings as written, anything else as JSON.
- `output?: unknown`. Result. Strings as written, anything else as JSON.
- `error?: string`. Error message, shown in red.
- `duration?: number`. Milliseconds. Shown once done or failed.
- `defaultOpen?: boolean` = false. Opens the payload on mount.
- `className?: string`. Merged onto the root.

API `formatDuration`:
- `ms: number`. Milliseconds.
- `returns?: string`. 540 ms, 1.34 s or 12.4 s.

### Thinking

- Level: Molecule
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/thinking`
- Exports: `Thinking`, `ThinkingStep`
- Docs: /design/components/thinking

Thinking is a one-line, collapsible reasoning trace. While the model works it reads Thinking… 4s with a small pixel grid and the latest step beside it; when it finishes it settles to Thought for 6s. Opening it shows every step on a thin rail, each with an optional one-line detail. It exists so people can check how an answer was reached without the reasoning competing with the answer. The common mistake is opening it by default: the trace stays folded above the answer, and the answer leads.

When to use:
- At the top of a Copilot answer, before tool calls and the streamed text.
- Above a retrieval answer, such as a knowledge base test, to show how the passages were found.
- When the steps are worth auditing later: which calls were read, which rules were checked.
- When the wait is long enough that the latest step reassures people something is happening.

When not to use:
- For a wait with nothing to show but a label and a timer. Use /design/components/ai-loader instead.
- For a plan the person will watch execute, where steps can fail or be skipped. Use /design/components/task-list instead.
- For tool calls with arguments and results. Use /design/components/tool-chip instead.
- For the answer itself. Use /design/components/streaming-text instead.
- For a proposed change that needs a decision. Use /design/components/approval-card instead.

Rules:
- The answer leads: Reasoning is folded by default and sits above the answer as one quiet 13px line. It opens only when someone asks, so AI help arrives without noise.
- Shimmer only while working: The shimmer runs on Thinking… and on the current step, and stops as soon as the trace is done. Finished steps are plain text.

Anatomy:
- Pixel grid: The small 3×3 grid from AI loader at 80% opacity. It ripples while running and rests when done.
- Summary: Thinking… (shimmering) or Thought for, in medium weight, then the elapsed time in regular tabular figures.
- Chevron: Present when there are steps. Turns 90° when open.
- Latest step: While running and folded, the newest step trails the summary in Slate Meta and truncates.
- Rail: A 1px hairline on the left of the open list, aligned under the grid.
- Step: 13px text. The current step shimmers in medium weight while running; the rest are ink at 80%.
- Detail: Optional 12px Slate Meta line under a step.

States:
- Running, folded: Grid rippling, Thinking… shimmering, seconds ticking, the latest step beside it.
- Running, open: Steps listed on the rail. New steps rise 4px and fade in on `spring.moderate`; the last one shimmers.
- Done, folded: Thought for 6s. The grid rests and the counter stops at the finishing time.
- Done, open: Every step in plain text, details below.
- Hover: The summary turns from Slate Meta to ink over 150ms.
- Focus visible: A 3px Focus Indigo ring at 40% around the summary.
- No steps: With an empty `steps` array it is a plain line, not a button, with no chevron.
- Reduced motion: The grid holds still, shimmer stops, steps appear without rising and the list opens without animating height.

Behavior:
- It is a Base UI Collapsible. The summary is the trigger, with `aria-expanded`; Enter and Space toggle it.
- Uncontrolled by default (`defaultOpen`). Pass `open` and `onOpenChange` to control it, for example from a preference.
- The counter comes from `useElapsed`: whole seconds since `startedAt`, or since mount. It ticks while running and freezes when `status` turns `done`.
- `elapsed` overrides the counter. Use it for traces that finished before this render, such as a turn loaded from history.
- A done trace never reads Thought for 0s; the minimum is one second.
- Steps already on screen at mount don't animate; only steps added later rise in.
- The open list animates its height over 200ms through the shared collapsible styles.

Do and don't:
- Do: Keep the trace folded above the answer, so the answer is the first thing people read.
- Don't: Open the trace by default. The steps push the answer below the fold and read as noise.
- Do: Write each step as a specific action with the object and, where it helps, a number: Reading 31 failed calls from last week.
- Don't: Write filler steps such as Analyzing, Processing data or Thinking deeply. They say nothing a loader doesn't.

Content:
- Write steps as an -ing verb plus the object, without an ellipsis: Reading the ticket and 3 earlier messages, Checking the payment in the ERP.
- When a trace loads already finished, write its steps in the past tense: Embedded the question, Kept 3 passages above 0.5.
- Use `detail` for the one fact the step turned up: 31 calls ended in a repeat loop, 12 were transferred after a date question.
- Three to five steps is enough. Merge steps that differ only in wording.
- The summary words (Thinking…, Thought for) are fixed by the component.

Accessibility:
- The summary is a `<button>` with `aria-expanded`. Its name includes the elapsed time and, while folded, the latest step.
- A separate visually hidden `role="status"` says Thinking while running and Thought for 6 seconds when done, so the finish is announced once.
- The ticking seconds and new steps are not announced one by one, which keeps screen readers quiet while it works.
- Under reduced motion nothing moves; the words carry the state.
- Tab: Moves to the summary when there are steps.
- Enter: Opens or closes the steps.
- Space: Opens or closes the steps.

Known gaps (follow the system, not the gap):
- `elapsed` isn't rounded. The knowledge base panel passes 2.2 and the summary reads Thought for 2.2s.
- There is no stopped or failed status. When someone stops a Copilot turn mid-thought, the trace reads Thought for 3s as if it had finished.
- The knowledge base panel swaps a running trace (open, present tense) for a new done one (folded, past tense), so the open state is lost at the switch. One instance with changing steps would keep it.
- The summary words can't be changed, so a trace for retrieval still says Thinking… rather than Searching….
- `open` and `onOpenChange` aren't used anywhere in the product yet.

API `Thinking` (extends Nothing. Only the props below are read.):
- `steps: ThinkingStep[]`. Steps in order. The last one is current while running.
- `status: "running" | "done"`. Running ticks and shimmers; done settles to Thought for.
- `startedAt?: number`. Epoch ms the reasoning began. Defaults to mount.
- `elapsed?: number`. Seconds. Overrides the live counter, for traces that finished earlier.
- `defaultOpen?: boolean` = false. Initial open state when uncontrolled.
- `open?: boolean`. Controlled open state.
- `onOpenChange?: (open: boolean) => void`. Called when the person toggles it.
- `className?: string`. Merged onto the root.

### Task list

- Level: Molecule
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/task-list`
- Exports: `TaskList`, `TaskRow`
- Docs: /design/components/task-list

Task list shows a plan as rows that tick from not started to in progress to done, with skipped and failed for plans that don't go to script. Each row has a status icon on a thin rail, a label and an optional detail, and a titled list counts 2 of 4 as it goes. It is how an agent shows what it is about to do and then does it, in front of the person who approved it. The common mistake is using it for reasoning or for tool calls: a task list is a plan with outcomes, so every row should be something the person would recognize as a step of the job.

When to use:
- Under an approval, to say what will happen when someone approves: What happens when you approve.
- While an approved plan runs, advancing one row at a time until everything is done.
- While a generated artifact is built in a few visible stages, such as a report layout.
- For a campaign or batch with a few named phases that can fail on their own, such as an overdue W-9 collection.

When not to use:
- For the model's reasoning before it answers. Use /design/components/thinking instead.
- For individual tool calls with arguments and results. Use /design/components/tool-chip instead.
- For a single task with a known percentage done. Use /design/components/progress instead.
- For the stage a record is in, such as a pipeline or onboarding stage. Use /design/components/stepper instead.
- For a checklist a person ticks by hand. Use /design/components/checkbox instead.

Rules:
- The Ink Fill Rule: A finished row is a filled Ink 80 circle with a check, not a green one. Progress isn't a verdict, so only a failure turns a row's icon semantic (a 12% Signal Red tint).
- The Label-Beside-Color Rule: Every status has its own shape: dashed circle, spinner, filled check, dash, exclamation. Each row also carries a hidden status word for screen readers.
- The Tabular Figures Rule: The 2 of 4 count in the title row is set in tabular figures so it doesn't shift as it changes.

Anatomy:
- Title: Optional 13px medium heading, rendered as an `h3`.
- Count: 12px Slate Meta done of total at the right, when both `title` and `tasks` are set. Skipped rows count as done.
- Status icon: 16px: a dashed ring for not started, a spinning arc for in progress, a filled ink check for done, a dashed-through ring for skipped, a red exclamation for failed.
- Rail: A 1px hairline from each icon down to the next row, hidden after the last row.
- Label: 13px. Medium weight with the shimmer while in progress, Slate Meta once done, struck through when skipped.
- Detail: Optional 12px Slate Meta line under the label. Signal Red on a failed row.

States:
- Not started: A dashed Firm Hairline ring. `status="pending"`.
- In progress: A spinning arc and a shimmering medium-weight label. `status="running"`.
- Done: A filled Ink 80 check and a Slate Meta label. The circle scales in and the check draws itself, but only when the row turns done on screen; rows that load done render still.
- Skipped: A ring with a dash and a struck-through Slate Meta label. Counts toward done.
- Failed: A 12% red disc with a red exclamation; the detail turns red. Doesn't count toward done. `status="error"`.
- Reduced motion: The spinner and shimmer stop. The check still appears, without the scale.

Behavior:
- `TaskList` is presentational. Status comes from you: advance rows on a timer for a simulation, or from real job events.
- Pass `tasks` to render rows plus the count and a status announcement, or compose `TaskRow` children for labels with markup. Children get neither the count nor the announcement.
- A row remembers its status at mount. If it mounts done, the check renders still; if it turns done later, the circle scales in on `spring.moderate` and the check path draws on `spring.slow`.
- The rail is drawn per row, so rows can be added or removed without redrawing a single long line.
- The spinner uses `animate-spin` with `motion-reduce:animate-none`.

Do and don't:
- Do: List the three to five steps a person would recognize as the job: accept partial invoice numbers, re-run the suite, publish to 20%.
- Don't: List every micro-action. Eight rows of Open ERP and Click search bury the one step that matters.
- Do: When a step fails, say why in its detail and mark the steps that depend on it as skipped.
- Don't: Leave the next row spinning after a failure, or fail with no detail. People can't tell whether anything is still happening.

Content:
- Write each row as the action, verb first, in sentence case: Email the W-9 request to 48 suppliers, Publish version 14 to 20% of calls.
- Keep the label the same as the row changes status. The icon says whether it is done; don't rewrite the label into the past tense.
- Use `detail` for size or outcome: 24 cases, about 3 minutes, 7 of 12 called.
- On a failure, the detail says what went wrong and what happens next: 3 suppliers have no phone number on file. They'll get a second email instead.
- Title the list for what it is about to do: What happens when you approve, Overdue W-9 collection.

Accessibility:
- The list is an `<ol>`, so screen readers announce the number of steps and each position.
- Each row carries a visually hidden status word: Not started, In progress, Done, Skipped or Failed.
- With `tasks`, a hidden `role="status"` announces 2 of 4 steps done as the count changes. Composed children don't get this; add your own status region if progress matters.
- Icons are `aria-hidden`. The spinner and shimmer stop under reduced motion.
- The title renders as an `h3`. Check it fits the heading outline where you place the list.

Known gaps (follow the system, not the gap):
- The product only uses not started, in progress and done. Skipped and failed exist but nothing renders them, so an approved Copilot plan has no way to show a failed step.
- Composed `TaskRow` children get no count and no status announcement.
- The title is always an `h3`, which can skip a level inside a panel whose section heading is an `h3` too.
- A failed row keeps its label in ink; only the icon and detail turn red.

API `TaskList` (extends Nothing. Only the props below are read.):
- `tasks?: TaskItem[]`. `{ id, label, status, detail? }[]`. Renders rows, the count and the status announcement.
- `title?: string`. Heading above the rows. With `tasks`, the count sits beside it.
- `children?: React.ReactNode`. `TaskRow` elements, rendered after any `tasks` rows.
- `className?: string`. Merged onto the root.

API `TaskRow` (extends Nothing):
- `label: React.ReactNode`. The step. Can hold markup.
- `status: "pending" | "running" | "done" | "skipped" | "error"`. Not started, in progress, done, skipped or failed.
- `detail?: React.ReactNode`. Line under the label.
- `className?: string`. Merged onto the `<li>`.

### Source cards

- Level: Molecule
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/source-cards`
- Exports: `SourceCards`, `SourceCard`, `Citation`, `SourcesProvider`
- Docs: /design/components/source-cards

Source cards show the context an answer was built from: knowledge base passages, supplier and payment records, call transcripts and web pages. Each card is a tint well with a number, the source's kind and origin, an optional match score, a title and a two-line snippet. Inline `Citation` markers in the text carry the same numbers, and hovering either side highlights the other. The mistake to avoid is sources with no markers: the point is that each claim in the answer points at the card that supports it.

When to use:
- Under an AI answer or summary, in a scrolling row, with `[n]` markers in the text.
- In an assist or retrieval panel, as a list, when the sources are the result (From the knowledge base).
- In a wider panel as a grid when there are many sources to compare.
- As a single `SourceCard` when one piece of context is pinned beside a draft.
- Through `StreamingText`'s `citations` prop, which mounts the provider, markers and cards for you.

When not to use:
- For files a person attached to a message. Use /design/components/attachment instead.
- For a summary that streams in with its sources. Pass `citations` and let it compose the cards. Use /design/components/streaming-text instead.
- To preview a record behind an ordinary link. Use /design/components/hover-card instead.
- For search results a person browses and opens, with actions per row. Use /design/components/item instead.
- For a generated insight with a metric and chart. Use /design/components/insight-card instead.

Rules:
- The Tint Well Rule: A source card is a 70% Well Gray region with 10px corners, not a bordered or shadowed card. It can sit inside a message, a panel or a card without nesting cards.
- The Tabular Figures Rule: Citation numbers, card numbers and match scores are tabular, so a row of 1 2 3 markers and 92% scores line up.

Anatomy:
- Citation: An 11px number in a 16px Well Gray chip, raised a third of a line. Hover or focus previews the source and highlights its card.
- Number: The card's position, in a white chip with a hairline lift, matching the citation.
- Kind icon: 14px: a document, a globe for web pages, a database for records, audio lines for call transcripts.
- Origin: `meta` in 12px Slate Meta, such as Payments playbook or Call on Sep 24. Falls back to the kind's name.
- Score: Optional retrieval match at the right, 92%, announced as 92% match.
- Title: 13px medium, one line.
- Snippet: 12px Slate Meta, two lines.

States:
- Rest: Well Gray at 70%.
- Linked: While its citation or the card itself is hovered or focused: Well Gray at 100% with a 1px Firm Hairline inset.
- Hover: Cards with an `href` deepen to Well Gray at 100% over 150ms.
- Focus visible: Linked cards get a 3px Focus Indigo ring at 40%.
- Citation open: The marker turns ink on a 10% ink fill and a 288px preview opens above it after 250ms.
- Missing source: A `Citation` with no matching source renders as a plain `[n]` superscript, not a control.
- Overflow: The row layout scrolls sideways with snap points and fades the clipped edge.

Behavior:
- `SourcesProvider` shares the list and the active source. `Citation` reads `sources[index − 1]` from it; `SourceCards` mounts its own provider if there isn't one.
- Hovering or focusing a citation or a card sets it active, which highlights its partner. Leaving clears it.
- Citation previews are Base UI preview cards: they open 250ms after hover or focus, close 120ms after leaving and close on Escape.
- A source with `href` renders as a link. `url` sources open in a new tab with `rel="noreferrer"` and say so to screen readers; other kinds open in place.
- Row layout: 224px cards in a horizontal scroller with snap and a 2rem fade on the clipped edge. Grid: columns of at least 12rem. List: a stack with 6px gaps.
- Titles clamp to one line and snippets to two; the preview shows up to four lines.

Do and don't:
- Do: Set `meta` to where the source came from, so cards are told apart at a glance: Payments playbook, ERP payment, Call on Sep 24.
- Don't: Leave every card on its kind label. Three cards that all say Document make people open each one.
- Do: Put a citation marker after each claim, matching the card that supports it.
- Don't: List sources under an answer with no markers in the text. Nobody can tell which card backs which claim.

Content:
- `title` is the source's own name, as the source writes it: Tracing an ACH the supplier hasn't received, Payment PMT-58177.
- `snippet` is the passage that supports the answer, quoted as written. For calls, quote the speaker in curly quotes.
- `meta` names the origin in two or three words: Payments playbook, Supplier record, Call on Sep 24.
- Keep the default heading Sources under answers. In a panel where the sources are the result, name them: From the knowledge base. Pass `title={null}` when a surrounding heading already says it.
- Only show `score` where people compare retrieval quality, such as a knowledge base test.

Accessibility:
- Citations are named Source 2: Payment PMT-58177, not just 2. Without an `href` they are buttons that only preview; with one they are links.
- The citation's hit area extends 4px past the chip on every side.
- The preview opens on keyboard focus as well as hover, and Escape closes it.
- The card list is a `<section>` labelled by its heading (or Sources when `title` is null), with an `<ol>` so the numbers are announced.
- The score is announced with the word match. External links announce (opens in a new tab).
- Kind icons are decorative; the origin text beside them says what the source is.
- Tab: Moves to each citation, then to each linked card.
- Enter: Follows a citation or card that has an `href`.
- Esc: Closes an open citation preview.

Known gaps (follow the system, not the gap):
- `SourceCard` on its own isn't used in the product, and `SourceCards` directly only in the contact center assist panel and Copilot answers. Everything else goes through `StreamingText`.
- A citation without an `href` is a `<button>` that does nothing when pressed; it only previews on hover and focus.
- No product data uses the `url` kind yet.
- `useSources` is exported but missing from the registry's export list.

API `SourceCards` (extends Nothing. Only the props below are read.):
- `sources: Source[]`. `{ id, title, snippet, kind, href?, score?, meta? }`. `kind` is `"doc" | "url" | "record" | "transcript"`; `score` is 0 to 1.
- `layout?: "row" | "grid" | "list"` = "row". Row scrolls sideways under a message, grid fills a panel, list stacks.
- `title?: string | null` = "Sources". Heading with the count. `null` hides it.
- `className?: string`. Merged onto the section.

API `SourceCard` (extends Nothing):
- `source: Source`. The source to show.
- `index?: number`. Shows the number chip.
- `className?: string`. Merged onto the card.

API `Citation` (extends Nothing):
- `index: number`. 1-based position in the provider's sources.
- `source?: Source`. Pass the source directly when there is no provider.
- `className?: string`. Merged onto the marker.

API `SourcesProvider`:
- `sources: Source[]`. The list citations index into.
- `children: React.ReactNode`. Text with citations, and the cards.

API `useSources`:

### Streaming text

- Level: Molecule
- Category: AI
- Status: Stable
- Import: `@oration/canon/components/ai/streaming-text`
- Exports: `StreamingText`, `StreamCaret`
- Docs: /design/components/streaming-text

Streaming text renders model output as it arrives: words appear with a soft caret, simple markdown formats as it goes, `[n]` markers become citations that point at source cards, and follow-up chips appear once it finishes. It is the AI summary block on every page that summarizes something, such as a ticket, a call or a supplier. The common mistake is streaming text that already exists. Stream when an answer is new or regenerated; when someone comes back to it, show it as plain text.

When to use:
- For the AI summary on a detail page: a ticket, a call, a supplier, a handoff.
- For an answer in a retrieval test or an assist panel, with its sources.
- When someone presses Regenerate: remount it and the new text streams in.
- With `followUps` when there are two or three obvious next questions.
- As the model for your own stream: `StreamCaret` with `SimpleMarkdown` and `useSimulatedStream`.

When not to use:
- To fill a form field with a draft the person will edit. Use /design/components/ai-generate-button instead.
- For a conversation with messages, actions and branches. Use /design/components/ai-message instead.
- For a proposed edit to text that already exists. Use /design/components/diff instead.
- For the wait before any text exists. Use /design/components/ai-loader instead.
- For a long prompt someone writes and edits. Use /design/components/prompt-editor instead.
- For a summary that was already read. Render it without streaming, as the handoff summary does after its first view.

Rules:
- AI everywhere, without noise: Pages that summarize something get one AI summary block, built on streaming text with its sources. It sits in its own section with a Summary heading and a regenerate action, and doesn't restream on every visit.
- The One Filled Button Rule: Follow-ups are outline chips at 28px. They are suggestions, never the view's filled action.
- The Thirteen-Fourteen Rule: Summaries are reading text at 14px. In dense panels, such as a knowledge base test, pass `className="text-13"`.

Anatomy:
- Text: Simple markdown at 14px with relaxed leading: paragraphs, `#` headings as bold lines, bullet and numbered lists, bold and `code`.
- Citation: Each `[n]` becomes a marker for `citations[n − 1]`, with a hover preview.
- Caret: A 2px rounded bar in ink at 55%, blinking on a 1.1s cycle at the end of the last block while text streams.
- Sources: Source cards for `citations`, in a row by default.
- Follow-ups: Outline 28px chips with a corner-arrow icon. They rise in one after another once the text is done.

States:
- Waiting: `start={false}` renders nothing and holds the stream until it flips to true.
- Streaming: Whole words appear at `speed` characters per second with the caret at the end. `aria-busy` is set. Half-typed markers such as `**` or `[2` are hidden until they close.
- Done: The caret goes, `onDone` fires once, and follow-ups rise in 40ms apart on `spring.moderate`.
- Regenerating: Change the `key` to remount; the new text streams from the start.
- Text grows: If `text` changes by appending, the reveal continues from where it was instead of starting over, so it can follow a real stream.
- Reduced motion: The whole text renders at once, with no caret, and follow-ups show immediately.

Behavior:
- Built on `useSimulatedStream`: one `requestAnimationFrame` loop reveals text up to the next word boundary, so it reads like tokens, not letters. The default speed is 40 characters per second; the product uses 110 to 420.
- `[n]` markers map to `citations[n − 1]`. With citations it mounts a `SourcesProvider`, so hovering a marker highlights its card.
- Source cards render as soon as streaming starts, while `showSources` is true. Set it to false to place them yourself.
- `onDone` fires once per run and text, including immediately under reduced motion.
- It has no stop or skip control. For those, compose `useSimulatedStream`, `SimpleMarkdown` and `StreamCaret` yourself.
- Follow-up chips call `onFollowUp` with their text. The product sends them to Copilot and confirms with a toast.

Do and don't:
- Do: Offer two or three follow-ups that are specific to this summary: Draft a follow-up email to Halcyon.
- Don't: Offer generic follow-ups such as Tell me more, Explain or Continue. They are noise under every answer.
- Do: Keep a summary to two to four sentences, with the next step in bold at the end.
- Don't: Stream a long paragraph that restates the ticket. The point of the summary is that nobody has to read the thread.

Content:
- Lead with who and what: Halcyon's AR team called about invoice INV-20931. Then the facts, with amounts and dates.
- Bold one or two facts that decide the next step, not whole sentences.
- End with Next step: and one action when there is one.
- Put `[n]` right after the claim it supports, before the period: took the discount [1].
- Follow-ups are what the person would type next, verb first, under about 40 characters: What's still open?, Draft a follow-up email.
- Label the block Summary with its source in Slate Meta: from the linked call and thread.

Accessibility:
- While streaming, the text has `aria-busy`, and it is not a live region, so screen readers aren't read every word. They read the finished text when they reach it.
- The caret is `aria-hidden`.
- Follow-ups are real buttons in a group named Suggested follow-ups.
- Under reduced motion the full text appears at once.
- Citations are named Source 1: Payment PMT-58213, and their previews open on focus.
- Regenerate is an icon button with the name Regenerate summary and a tooltip.

Known gaps (follow the system, not the gap):
- Source cards appear as soon as streaming starts, before the markers that point at them. Copilot answers compose the parts by hand to show the cards only once the text is complete.
- `SimpleMarkdown` has no blockquotes, links, italics or tables. Copilot's draft-reply answer quotes the reply with `>` lines, which render as a literal `>`.
- Headings render as bold paragraphs, not heading elements, so they don't appear in a screen reader's heading list.
- There is no stop or skip control, although `useSimulatedStream` has `skip()` and `restart()`. Regenerating means remounting with a new `key`.
- The caret's blink isn't in the global reduced-motion rule. It only disappears because reduced motion renders the text at once.
- The default speed of 40 characters per second is slower than every product call site.

API `StreamingText` (extends Nothing. Only the props below are read.):
- `text: string`. The full text, in simple markdown.
- `speed?: number` = 40. Characters per second, revealed a word at a time.
- `citations?: Source[]`. Sources for `[n]` markers, 1-based. Mounts a provider and source cards.
- `followUps?: string[]`. Chips shown when the stream finishes.
- `onFollowUp?: (text: string) => void`. Called with a chip's text.
- `start?: boolean` = true. False holds the stream with nothing rendered.
- `onDone?: () => void`. Called once when the text is complete.
- `showSources?: boolean` = true. Renders source cards for `citations` under the text.
- `sourcesLayout?: "row" | "grid" | "list"` = "row". Layout of those source cards.
- `className?: string`. Merged onto the root, e.g. `text-13`.

API `StreamCaret` (extends Nothing):
- `className?: string`. Merged onto the caret.

### Diff

- Level: Molecule
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/diff`
- Exports: `InlineDiff`, `DiffTable`, `diffWords`
- Docs: /design/components/diff

Diff shows a proposed change before anyone accepts it. `InlineDiff` compares two versions of a text word by word: removed words are struck through on a red tint, added words sit on a green tint, and the rest reads normally. `DiffTable` lists field changes with the old value struck through beside the new one, as a table or stacked for narrow panels. `diffWords` is the algorithm underneath. The thing people get wrong is diffing whole paragraphs that were rewritten: when almost every word changed, show the new text and offer the old one, because a diff of everything is unreadable.

When to use:
- For an AI rewrite of a prompt, a macro or a description, before someone applies it.
- When comparing two versions of a prompt, such as a draft against the live version.
- In an approval card, as a stacked `DiffTable`, for the fields an action will change.
- On a page, as a `DiffTable`, for a batch of record changes such as a supplier's new bank and remit-to details.
- With `diffWords` when you need counts or your own rendering, such as 11 words added in a version list.

When not to use:
- For a single changed select value on a record. Show the old tag struck through, an arrow and the new tag. Use /design/components/tag instead.
- For a change that needs Approve, Edit and Skip. Use /design/components/approval-card instead.
- For an AI rewrite inside the long-form editor, which shows its own inline diff to accept or reject. Use /design/components/prompt-editor instead.
- For the history of changes over time. Use /design/components/timeline instead.
- For code or JSON, where a line diff reads better than a word diff. Canon has no line diff yet.

Rules:
- Destructive is a tint: Removed words are a 10% Signal Red tint with red text and a strikethrough (20% in dark), never a solid red block. Added words are a 15% Ledger Green tint with ink text.
- The Label-Beside-Color Rule: Color is never the only cue. Removed text is struck through, and both removed and added parts carry hidden removed: and added: markers because `<del>` and `<ins>` are rarely announced.
- The Tint Well Rule: Inside a card, put an inline diff in a 70% Well Gray well with 10px corners, as Copilot and the version compare dialog do.

Anatomy:
- Unchanged text: Renders as is, in the surrounding type.
- Removed: A `<del>` with a 10% red tint, red text, a 50% red strikethrough and 3px corners that wrap across lines.
- Added: An `<ins>` with a 15% green tint, ink text and no underline.
- Field: The field name in 12px Slate Meta (stacked) or a 13px row header (table).
- Before: The old value in Slate Meta, struck through. An empty value shows a Faint Slate dash, announced as Empty.
- Arrow: 14px, Faint Slate, between the values in the stacked layout.
- After: The new value in ink.

States:
- Unchanged: No marks. Identical texts render as plain text.
- Removed: Struck through on the red tint.
- Added: On the green tint.
- Replaced: A removed run followed by an added run, so the new words read right after the old.
- New field: `before` left out: a dash in the before column, then the value.
- Too long to compare: Past 250,000 word pairs, `diffWords` stops comparing and shows the whole old text removed and the whole new text added.

Behavior:
- `diffWords` splits both texts on whitespace, keeping the whitespace as tokens, and walks a longest-common-subsequence table. Runs of the same kind merge into one part.
- Whitespace-only removals are dropped and whitespace-only additions render as plain spaces, so spacing changes don't draw empty marks.
- Punctuation belongs to its word: changing weekly. to weekly, marks the whole word.
- `InlineDiff` memoizes the diff on `before` and `after`. It is a span, so it flows inside a paragraph.
- Neither component has `"use client"`, so both render on the server.
- `DiffTable` values are `ReactNode`, so a tag, a mono ID or a formatted amount works on either side.

Do and don't:
- Do: Diff small, targeted edits so the change jumps out: two words replaced, one clause added.
- Don't: Diff a full rewrite. When nearly every word changes, the red and green bands make it harder to read than either version.
- Do: Use the stacked table in narrow panels, with before and after on one line per field.
- Don't: Squeeze the three-column table into a 20rem panel, where every value wraps onto several lines.

Content:
- Title a proposed text change for what it is: Proposed prompt change, Rewritten description.
- In a `DiffTable`, write field names as they appear on the record: Remit-to email, Payment method.
- Mask sensitive values on both sides the same way: Account ending 4821 → Account ending 0937.
- For counts from `diffWords`, write them in words people use: 2 edits, 11 words added, 6 removed.
- Give the table a `caption` that names the change, such as Changes to Northwind Freight. It is read to screen readers.

Accessibility:
- Removed and added parts carry visually hidden removed: and added: prefixes, so screen readers hear the change, not a run-on sentence.
- Before and after values in `DiffTable` carry hidden Before: and After: prefixes; an empty before reads Empty.
- The table layout is a real `<table>` with a hidden caption, column headers and row headers. The stacked layout is a `<dl>` named by `caption`.
- Text stays at text contrast: removed text is Signal Red on its tint and added text is ink.

Known gaps (follow the system, not the gap):
- `diffWords` isn't called anywhere in the app, and `DiffTable` is only used inside Approval card. `caption` is never set, so every table reads Proposed changes.
- It is word-level only. Punctuation attaches to words, and there is no character or line mode for IDs, code or JSON.
- Past 250,000 word pairs (roughly two 500-word texts) the diff gives up and shows everything removed and added.
- Added words have no non-color cue for sighted users; only removed words are struck through. In grayscale an addition reads as highlighted, not as added.

API `InlineDiff` (extends Nothing. Only the props below are read.):
- `before: string`. The current text.
- `after: string`. The proposed text.
- `className?: string`. Merged onto the span.

API `DiffTable` (extends Nothing):
- `rows: DiffRow[]`. `{ field: ReactNode; before?: ReactNode; after: ReactNode }[]`.
- `layout?: "table" | "stacked"` = "table". Three columns for a page, or one line per field for narrow panels.
- `caption?: string` = "Proposed changes". Screen reader caption for the table, or name of the list.
- `className?: string`. Merged onto the table or list.

API `diffWords`:
- `before: string`. The current text.
- `after: string`. The proposed text.
- `returns?: DiffPart[]`. `{ type: "same" | "removed" | "added"; text: string }[]`, with whitespace kept.

### Model picker

- Level: Molecule
- Category: AI
- Status: Experimental
- Import: `@oration/canon/components/ai/model-picker`
- Exports: `ModelPicker`
- Docs: /design/components/model-picker

Model picker is the small ghost button in a prompt toolbar that shows the current model and opens a menu of models, each with a one-line description. It lets someone switch the model behind a single prompt, such as a Copilot question, without leaving the composer. It is deliberately quiet: 24px, Slate Meta, no border. The common mistake is using it to configure an agent. An agent's LLM, speech-to-text and text-to-speech choices belong to Provider model picker, with speed and cost beside each option.

When to use:
- In a prompt bar's toolbar, beside attach and dictation, before the send button.
- In the header of a test panel where someone compares answers from different models.
- When there are two to six models and each can be summed up in a few words.

When not to use:
- To choose the models an agent runs on, with providers, speed and cost. Use /design/components/provider-model-picker instead.
- For a model setting in a settings row that saves with the page. Use /design/components/select-field instead.
- To pick a voice and preview it. Use /design/components/voice-picker instead.
- For a long list of models that needs search. Use /design/components/combobox instead.

Rules:
- The One Filled Button Rule: In a composer, Send is the one filled button. The model picker is an extra-small ghost button that only fills Well Gray on hover or while its menu is open.
- The Quiet Indigo Rule: The selected model is marked with an ink check, not an indigo fill. Menu highlight is Menu Hover.

Anatomy:
- Trigger: An extra-small (24px) ghost button with 8px corners in Slate Meta, up to 10rem wide. It turns ink on hover.
- Current model: The selected model's label, truncated to fit.
- Chevron: A 12px chevron at the end.
- Group label: Model, in 12px medium Slate Meta.
- Model: A radio item: the label in 14px, highlighted in Menu Hover.
- Description: Optional 12px Slate Meta line under the label.
- Check: Marks the selected model at the right.

States:
- Rest: Slate Meta text on no fill.
- Hover: Ink text on Well Gray, over 150ms.
- Focus visible: An indigo border and a 3px Focus Indigo ring at 40%.
- Open: The trigger keeps the hover fill while the 16rem menu is open. The menu opens over 160ms from a 0.97 scale and closes in 110ms.
- Highlighted: The item under the pointer or keyboard fills Menu Hover.
- Selected: A check at the right of the current model.
- Unknown value: If `value` matches no model, the first model shows and is checked.

Behavior:
- Built on the Base UI menu through Dropdown menu: click, Enter, Space or the arrow keys open it, and focus moves into the list.
- The items are a radio group. Choosing one calls `onValueChange` with the model's `id` and closes the menu; focus returns to the trigger.
- It is controlled: pass `value` and update it in `onValueChange`. Prompt bar keeps its own copy when you don't pass `model`.
- `side` defaults to `top`, because the prompt bar sits at the bottom of a panel. Use `bottom` in a header.
- The menu portals to the body, so it isn't clipped by the composer.

Do and don't:
- Do: Label models with the names people know and say what each is good for: GPT-4.1, OpenAI, best for drafting.
- Don't: Use raw API identifiers such as gpt-4.1-2025-04-14 as labels. They truncate in the trigger and mean nothing to most people.
- Do: Keep the picker as the quiet ghost trigger in the toolbar, so Send stays the one strong action.
- Don't: Restyle it as an outlined select at full control height. It competes with Send and makes model choice look like a required field.

Content:
- Labels are the model's public name in its own casing: GPT-4.1, Gemini 2.5 Pro, Mistral Large.
- Descriptions name the provider and one strength, separated by a comma: Google, long context, Mistral, lowest cost.
- Offer Auto first when the product can choose per step, described as Picks a model per step.
- Keep the list to about six. Past that, the choice belongs in settings.

Accessibility:
- The trigger's name is Model: GPT-4.1, so it says what it controls, not only the value.
- Menu items are `menuitemradio` with `aria-checked`, so the current model is announced.
- Focus moves into the menu on open and returns to the trigger on close.
- The trigger is 24px tall, the minimum hit size. On touch-first surfaces use the prompt bar at `md`.
- Enter: Opens the menu. Space and ↓ also open it.
- ↓: Moves to the next model. ↑ moves to the previous one.
- Home: Moves to the first model. End moves to the last.
- Enter: Selects the highlighted model and closes the menu.
- Esc: Closes the menu without changing the model.
- A–Z: Jumps to the next model starting with that letter.

Known gaps (follow the system, not the gap):
- Only Prompt bar uses it. No other screen imports it.
- The trigger's name always starts with Model:, and there is no prop to change it. With no models it reads Model: None and opens an empty menu; Prompt bar hides it in that case.
- Descriptions pack the provider and a strength into one string. There are no fields for provider, speed or cost as Provider model picker has.
- Long labels truncate at 10rem with no tooltip for the full name.

API `ModelPicker` (extends Nothing. Only the props below are read.):
- `models: PromptModel[]`. `{ id: string; label: string; description?: string }[]`.
- `value: string | undefined`. The selected model's `id`. Falls back to the first model.
- `onValueChange: (id: string) => void`. Called with the chosen model's `id`.
- `side?: "top" | "bottom"` = "top". Which side of the trigger the menu opens on.
- `className?: string`. Merged onto the trigger button.

## Organisms

### Cascader

- Import: `@oration/canon/components/cascader`
- A select whose options form a tree: drill into a level, search it and commit a value at any depth.

### Filters

- Import: `@oration/canon/components/filters`
- A stepped filter builder: pick an attribute, a condition and a value as chips, or nest groups in the advanced builder.

### Dialog

- Level: Organism
- Category: Overlays
- Status: Stable
- Import: `@oration/canon/components/dialog`
- Exports: `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`
- Docs: /design/components/dialog

Dialog is the modal surface for a focused task the page has to wait for: edit payment terms, schedule a run, review what's about to go out. It is built from parts (a header, a body you compose, and a Well Gray footer band over a hairline) so it fits anything from one field to a scrolling review. Confirmations, short record forms and multi-page flows have ready-made versions built on it; reach for those first. The common mistake is using a dialog for work that needs the page behind it: record details and long edits belong in a sheet.

When to use:
- For a short, self-contained task with its own Save: Edit payment terms, Schedule payment run, Edit remit-to email.
- To review something before it happens, such as the invoices in a payment run, with the footer as the commit point.
- For a read-only detail that doesn't deserve a page, such as a remittance summary, closed with Close.
- When you need a layout the ready-made dialogs can't express: a split footer, a scrolling body, a stepper in the header.

When not to use:
- To confirm a delete or another consequential action. Use /design/components/confirm-dialog instead.
- For a create or edit form with a submit and a cancel and nothing else. Use /design/components/form-dialog instead.
- For record details or a long edit that should keep the list in view. Use /design/components/sheet instead.
- For a few controls tied to one button that apply as you change them. Use /design/components/popover instead.
- For three or more pages read in order, such as what's new. Use /design/components/stacked-dialog instead.
- For a success message after an action. Confirm with a toast instead. Use /design/components/toast instead.

Rules:
- The One Filled Button Rule: While a dialog is open it is the view, so its footer holds the one filled button: the action the dialog exists for, last in the row. Cancel is outline; a secondary destructive action is the red tint on the left.
- The Hairline-and-Lift Rule: The surface takes its edge from the dialog shadow and a 1px ink ring at 10%, never a CSS border. The only CSS border is the hairline structural divider on top of the footer band.

Anatomy:
- Scrim: `DialogOverlay`, a black scrim at 25% (55% in dark) that fades in over 200ms. Clicking it closes the dialog.
- Surface: `DialogContent`: Popover White, 12px corners, 16px padding and 16px gaps, the dialog shadow and a 1px ring. 24rem wide from 640px, and the viewport minus 2rem below.
- Close button: A 28px ghost icon button 8px from the top right, named Close for screen readers. Hide it with `showCloseButton={false}` when the footer already closes.
- Header: `DialogHeader` stacks `DialogTitle` (Title Large: 16px, weight 500) and `DialogDescription` (14px Slate Meta) 8px apart. They label and describe the dialog.
- Body: Whatever the task needs: fields, a tint well of totals, a list. Compose it directly inside the content; there is no body part.
- Footer band: `DialogFooter` bleeds to the edges with `-mx-4 -mb-4`, fills Well Gray at 50% over a hairline and right-aligns its buttons from 640px. Below that it stacks them with the primary on top.

States:
- Closed: Nothing is rendered. The trigger shows `aria-expanded="false"` when it is a `DialogTrigger`.
- Opening: The surface fades in from a 0.96 scale over 200ms on the house ease-out while the scrim fades in over 200ms.
- Open: Focus is inside and trapped, the page behind is inert and its scroll is locked. The trigger carries `data-popup-open`.
- Nested: A dialog opened from inside another gets `data-nested`, and the parent gets `data-nested-dialog-open`. The nested scrim doesn't draw, and the parent keeps its size and position, so the two surfaces overlap; prefer replacing the first dialog over stacking a second.
- Closing: Fades out toward a 0.98 scale in 140ms, faster than it opened, then unmounts.
- Reduced motion: The scale is zeroed by the global reduced-motion rule; only the fades remain.

Behavior:
- Built on Base UI Dialog. `DialogTrigger` opens it; Esc, a click on the scrim, the close button or any `DialogClose` closes it. `disablePointerDismissal` keeps the scrim from closing it.
- Opening moves focus to the first focusable element inside, and closing returns it to whatever was focused before, usually the trigger. Change either with `initialFocus` and `finalFocus` on `DialogContent`.
- Uncontrolled by default. Control it with `open` and `onOpenChange` when a form submit, a menu item or a row action opens or closes it; the product's dialogs are almost all controlled.
- Put a `<form>` directly inside `DialogContent` with `className="grid gap-4"` and the footer inside the form, so Enter submits and the band still reaches the edges.
- Width is a class on the content: the default is 24rem, and the product uses `sm:max-w-md` (28rem) most, then `sm:max-w-lg`, `sm:max-w-xl` and `sm:max-w-2xl` for tables and comparisons.
- For a long body, make the content a flex column with `p-0 gap-0 overflow-hidden` and a `max-h`, pad the header, give the body `min-h-0 flex-1 overflow-y-auto overscroll-contain`, and reset the footer's bleed with `m-0`.
- Timings come from globals.css, keyed on `data-slot="dialog-content"`: 200ms in from 0.96 and 140ms out toward 0.98. Add `data-no-motion` to the content to open it with no animation, as the command menu does.

Do and don't:
- Do: Give the footer one filled button for the action the dialog exists for, last in the row, with Cancel beside it in outline.
- Don't: Fill both buttons. Cancel competes with the commit and people hit the wrong one.
- Do: Title the dialog with the task or the question, and repeat its verb on the button: Approve payment run? confirms with Approve run.
- Don't: Ask Are you sure? and answer with OK. Nobody can tell what happens without reading the body.
- Do: Keep a dialog to one task that fits on one screen, and move record details or long edits to a sheet.
- Don't: Put tabs, a sidebar and a second dialog inside a dialog. It has become a page that can't be linked to.

Content:
- Titles are sentence case with no trailing period: a verb and object for tasks (Edit payment terms), a question for decisions (Approve payment run?).
- The description says what the change applies to or what happens next in one sentence: Applies to new invoices from Northwind Freight.
- The primary button repeats the title's verb: Save terms, Schedule run, Send invite. Use Cancel to back out of a change and Close when nothing changed.
- Name amounts, counts and dates in the body, with tabular figures, so the decision is made on real numbers.
- Confirm the result with a toast after the dialog closes, not with a second dialog.

Accessibility:
- The trigger gets `aria-haspopup="dialog"` and `aria-expanded`. The popup is `role="dialog"`, labelled by `DialogTitle` and described by `DialogDescription`. Every dialog needs a title; hide it with `sr-only` if the design has none.
- Focus moves in on open, is trapped while open and returns to the trigger on close. When opened from a menu item, it returns to the menu's trigger.
- The page behind is inert, so screen readers can't wander out of the dialog.
- The close button's name is Close. It is icon-only, so it counts toward the 24px hit area rule at 28px.
- `DialogTitle` renders an `h2`. Inside a page whose outline already uses `h2`, that is still correct because the dialog is its own context.
- Under reduced motion the scale is removed and only opacity animates.
- Enter: Opens the dialog from its trigger, and submits the form inside.
- Tab: Moves through the controls inside, wrapping at the ends.
- Shift + Tab: Moves backwards, wrapping to the last control.
- Esc: Closes the dialog and returns focus to the trigger.

Known gaps (follow the system, not the gap):
- DESIGN.md sets 24rem as the default width, and that is the component's default, but the product passes `sm:max-w-md` (28rem) in 25 dialogs and the default in only 2. 28rem is the de facto default.
- The footer's `-mx-4 -mb-4` bleed assumes the 16px padding. Any `p-0` layout must reset it with `m-0`, or the band overflows the surface.
- The component's own classes still say `duration-100`, `zoom-in-95` and `zoom-out-95`. globals.css overrides them through `data-slot`, so a hand-rolled surface that copies the classes without the slot animates at 100ms from 0.95.
- The close button is icon-only with no tooltip, unlike every other icon-only button in the suite.

API `Dialog` (extends Base UI `Dialog.Root`):
- `open?: boolean`. Controls whether it is open.
- `defaultOpen?: boolean` = false. Whether it starts open when uncontrolled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when it opens or closes. `eventDetails.reason` says why, such as `escape-key` or `outside-press`.
- `onOpenChangeComplete?: (open: boolean) => void`. Called after the open or close animation ends.
- `modal?: boolean | "trap-focus"` = true. `true` traps focus, locks scroll and blocks outside clicks. `"trap-focus"` only traps focus. Leave it on.
- `disablePointerDismissal?: boolean` = false. Keeps a click on the scrim from closing it.
- `actionsRef?: RefObject<{ close: () => void; unmount: () => void }>`. Imperative close and unmount.

API `DialogTrigger` (extends Base UI `Dialog.Trigger` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render your own button, such as `<Button type="button" variant="outline" />`.
- `nativeButton?: boolean` = true. Set `false` when `render` isn't a `<button>`.

API `DialogContent` (extends Base UI `Dialog.Popup`):
- `showCloseButton?: boolean` = true. Draws the close button in the top right.
- `initialFocus?: boolean | RefObject<HTMLElement> | (openType) => HTMLElement | boolean | null | void`. Where focus goes on open. Defaults to the first focusable element.
- `finalFocus?: boolean | RefObject<HTMLElement> | (closeType) => HTMLElement | boolean | null | void`. Where focus goes on close. Defaults to the trigger.
- `className?: string`. Merged after the defaults. Widths such as `sm:max-w-md`, and `p-0 gap-0` for custom layouts.

API `DialogHeader` (extends `<div>`):

API `DialogTitle` (extends Base UI `Dialog.Title` (`<h2>`)):

API `DialogDescription` (extends Base UI `Dialog.Description` (`<p>`)):

API `DialogFooter` (extends `<div>`):
- `showCloseButton?: boolean` = false. Appends an outline Close button that closes the dialog.

API `DialogClose` (extends Base UI `Dialog.Close` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Usually `<Button type="button" variant="outline" />`.

API `DialogOverlay` (extends Base UI `Dialog.Backdrop`):

API `DialogPortal` (extends Base UI `Dialog.Portal`):
- `container?: HTMLElement | RefObject<HTMLElement>`. Where to portal to. Defaults to the body.

### Alert dialog

- Level: Organism
- Category: Overlays
- Status: Experimental
- Import: `@oration/canon/components/alert-dialog`
- Exports: `AlertDialog`, `AlertDialogContent`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogAction`, `AlertDialogCancel`
- Docs: /design/components/alert-dialog

Alert dialog interrupts to ask for a decision before anything else can happen. It is the primitive under Confirm dialog: a surface with the `alertdialog` role, a centered or left-aligned header, an optional media tile and the same Well Gray footer band as Dialog. It can't be dismissed by clicking the scrim, only by answering or pressing Esc. Nothing in the product imports it directly, and that's the point: reach for Confirm dialog first, and build from these parts only when the decision has a shape Confirm dialog can't express, such as three answers.

When to use:
- For a decision with more than two answers, such as Keep editing, Discard and Save and close when leaving an unsaved remittance email.
- When the decision needs a media tile or body content that the ready-made confirmation doesn't lay out, such as an icon beside the title.
- To build a new ready-made confirmation component for `packages/canon`, the way Confirm dialog is built.

When not to use:
- For a delete, remove, rotate or turn-off with a Cancel and one action. The ready-made version handles focus, pending state and typed confirmation. Use /design/components/confirm-dialog instead.
- For a task with fields and a Save. Alert dialogs ask, they don't edit. Use /design/components/dialog instead.
- To tell someone an action worked. Nothing is being decided. Use /design/components/toast instead.
- For a warning that can wait on the page, such as an expiring W-9. Use /design/components/alert instead.

Rules:
- The One Filled Button Rule: The footer holds at most one filled button, the answer the dialog exists to offer. When the answer destroys something, it is the red tint and there is no filled button at all.
- The Hairline-and-Lift Rule: The surface takes its edge from the dialog shadow and a 1px ink ring at 10%. The one CSS border is the hairline over the footer band.

Anatomy:
- Scrim: `AlertDialogOverlay`, black at 25% (55% in dark), fading in over 200ms. Clicking it does nothing.
- Surface: `AlertDialogContent`: Popover White, 12px corners, 16px padding, the dialog shadow and ring. 20rem wide below 640px; from 640px, 24rem at `size="default"` and still 20rem at `size="sm"`.
- Media: `AlertDialogMedia`, an optional 40px Well Gray tile with a 24px icon. At the default size from 640px it sits to the left of the title and description; otherwise it stacks above them.
- Header: `AlertDialogHeader` with `AlertDialogTitle` (16px, weight 500) and `AlertDialogDescription` (14px Slate Meta, balanced). Centered on small screens and at `sm`, left-aligned at the default size from 640px.
- Footer band: `AlertDialogFooter`: Well Gray at 50% over a hairline, bleeding to the edges. Buttons stack below 640px and right-align above it; at `size="sm"` they split the width in two equal columns.
- Answers: `AlertDialogCancel` (outline, closes) and one or more `AlertDialogAction` buttons, which don't close on their own.

States:
- Closed: Nothing is rendered.
- Opening: Fades in from a 0.96 scale over 200ms on the house ease-out while the scrim fades in.
- Open: Focus is trapped inside, the page is inert and its scroll locked. Clicks on the scrim are ignored.
- Closing: Fades toward a 0.98 scale in 140ms, then unmounts.
- Small: `size="sm"` keeps the 20rem width at every breakpoint, centers the header and splits the footer into two equal buttons.
- Reduced motion: Scale is zeroed; only the fades remain.

Behavior:
- Built on Base UI Alert Dialog. It is always modal: focus is trapped, the page behind is inert, and a click outside doesn't close it. Esc and `AlertDialogCancel` do.
- `AlertDialogAction` is a plain Button with a `data-slot`. It does not close the dialog, so control `open` and set it to `false` in the action's handler once the work is done.
- `AlertDialogCancel` is a Base UI Close rendered as an outline Button. Pass `variant` and `size` to change it.
- Opening moves focus to the first focusable element, which is the Cancel button when the footer lists it first. That's the safe default for a decision; move it with `initialFocus` on `AlertDialogContent`.
- Closing returns focus to the trigger, or to whatever was focused before it opened.
- Timings come from globals.css, keyed on `data-slot="alert-dialog-content"`: 200ms in from 0.96 and 140ms out toward 0.98, the same as Dialog.

Do and don't:
- Do: Use an alert dialog when the next step depends on the answer, and offer answers that name what happens: Keep editing, Discard, Save and close.
- Don't: Use one to announce a result with a single OK. Nothing is being decided, so it is an interruption with no purpose; confirm with a toast.
- Do: Keep the destructive answer in the red tint and make Cancel the first focus.
- Don't: Fill the destructive answer in indigo so it looks like the safe default.

Content:
- Title the dialog with the question, naming the object: Leave without saving?, Pause autopay for Halcyon?
- The description says what happens to what, in one or two sentences. Name counts, amounts and dates.
- Each answer is a verb phrase that makes sense read alone. Avoid Yes, No and OK.
- Use Cancel or Keep editing for the answer that changes nothing, so people can back out without reading the rest.

Accessibility:
- The popup has `role="alertdialog"`, labelled by `AlertDialogTitle` and described by `AlertDialogDescription`. Always render both, so the question is announced with its context.
- Focus moves in on open, is trapped while open and returns to the trigger on close.
- Icons inside `AlertDialogMedia` are decorative; mark them `aria-hidden="true"`.
- Because the scrim doesn't dismiss it, people who can't see the scrim aren't surprised by a close they didn't intend.
- Under reduced motion only opacity animates.
- Tab: Moves between the answers, wrapping at the ends.
- Enter: Activates the focused answer.
- Esc: Closes the dialog, the same as Cancel.

Known gaps (follow the system, not the gap):
- No file in `apps/web` imports it. Every confirmation goes through Confirm dialog, which is why this page is marked experimental.
- The surface has no `max-w-[calc(100%-2rem)]`, unlike Dialog. Both sizes are 20rem below 640px, so on a 320px viewport the surface touches the screen edges.
- The media tile uses 8px corners (`rounded-md`). DESIGN.md gives icon tiles standard 10px corners.
- The component's own classes still say `duration-100`, `zoom-in-95` and `zoom-out-95`; globals.css overrides them through `data-slot`.
- `AlertDialogAction` doesn't close the dialog, while `AlertDialogCancel` does. The names don't say so, and it is easy to ship an action that leaves the dialog open.

API `AlertDialog` (extends Base UI `AlertDialog.Root`):
- `open?: boolean`. Controls whether it is open. Control it whenever an action should close it.
- `defaultOpen?: boolean` = false. Whether it starts open when uncontrolled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when Esc, Cancel or a trigger changes it.
- `onOpenChangeComplete?: (open: boolean) => void`. Called after the open or close animation ends.
- `actionsRef?: RefObject<{ close: () => void; unmount: () => void }>`. Imperative close and unmount.

API `AlertDialogTrigger` (extends Base UI `AlertDialog.Trigger` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render your own button, such as `<Button type="button" variant="outline" />`.

API `AlertDialogContent` (extends Base UI `AlertDialog.Popup`):
- `size?: "default" | "sm"` = "default". `sm` stays 20rem wide, centers the header and splits the footer into two equal buttons.
- `initialFocus?: boolean | RefObject<HTMLElement> | (openType) => HTMLElement | boolean | null | void`. Where focus goes on open. Defaults to the first focusable element.
- `finalFocus?: boolean | RefObject<HTMLElement> | (closeType) => HTMLElement | boolean | null | void`. Where focus goes on close. Defaults to the trigger.
- `className?: string`. Merged after the defaults.

API `AlertDialogHeader` (extends `<div>`):

API `AlertDialogMedia` (extends `<div>`):

API `AlertDialogTitle` (extends Base UI `AlertDialog.Title` (`<h2>`)):

API `AlertDialogDescription` (extends Base UI `AlertDialog.Description` (`<p>`)):

API `AlertDialogFooter` (extends `<div>`):

API `AlertDialogOverlay` (extends Base UI `AlertDialog.Backdrop`):

API `AlertDialogPortal` (extends Base UI `AlertDialog.Portal`):

### Confirm dialog

- Level: Organism
- Category: Overlays
- Status: Stable
- Import: `@oration/canon/components/confirm-dialog`
- Exports: `ConfirmDialog`, `usePendingItem`
- Docs: /design/components/confirm-dialog

Confirm dialog is the one confirmation the suite uses before a consequential action: delete a supplier, remove an API key, rotate a secret, turn off the last live key. You pass the question, the consequence and a confirm label, and it handles the rest: Cancel takes first focus, destructive actions get the red tint, a returned promise shows a spinner and holds the dialog open, and `confirmText` adds a typed-name check for losses that can't be undone. The common mistake is a vague confirm label. The button repeats the consequence (Delete supplier, Remove key), never OK or Yes.

When to use:
- Before a delete or remove that can't be undone: Delete Northwind Freight?, Remove key?
- Before an action with a real consequence that isn't a delete, such as rotating a key or turning off autopay, with `destructive={false}`.
- With `confirmText` when the loss is large and permanent, such as deleting a payment run with its invoices, so the name has to be typed.
- When confirming calls the server: return the promise from `onConfirm` and the dialog waits with a spinner.
- From a table or list row, with `usePendingItem` holding the row while the dialog animates closed.

When not to use:
- For an action that can be undone. Do it, then offer Undo in a toast. Use /design/components/toast instead.
- For a decision with three answers, or a layout the props can't express. Use /design/components/alert-dialog instead.
- For a single high-stakes button in place, where a dialog would break the flow. Use /design/components/hold-button instead.
- For a form with fields and a Save. Use /design/components/form-dialog instead.

Rules:
- Destructive is a tint: The confirm button of a destructive confirmation is the 10% Signal Red tint with red text, never a solid red fill. The words carry the weight.
- The One Filled Button Rule: A non-destructive confirmation has one filled indigo button, the confirm. A destructive one has none: Cancel is outline and the confirm is the red tint.

Anatomy:
- Title: The question, naming the object: Delete Northwind Freight? Rendered by `AlertDialogTitle`.
- Description: What happens and to what, in one or two sentences of Slate Meta.
- Body: Optional `children` between the header and the footer, such as a grace-period select when rotating a key.
- Typed check: With `confirmText`: a 13px Slate Meta label with the name in inline code, and an input with autocomplete, capitalization and spellcheck off.
- Cancel: An outline `AlertDialogCancel`, first in the DOM and first to take focus. Labelled by `cancelLabel`.
- Confirm: The red tint by default, the filled indigo button with `destructive={false}`. Shows a 14px spinner before its label while pending.

States:
- Closed: Nothing is rendered. With `usePendingItem`, the last item is kept so the title doesn't change while the dialog animates out.
- Open: Focus is on Cancel, or on the typed input when `confirmText` is set. The typed value and pending state reset every time it opens.
- Waiting for the name: With `confirmText`, the confirm button is disabled until the trimmed input matches exactly, including case.
- Disabled: `confirmDisabled` disables the confirm button for any other reason, such as a body field that isn't filled in.
- Pending: When `onConfirm` returns a promise: a spinner before the label, both buttons disabled, and Esc ignored until it settles.
- Closing: Closes when `onConfirm` returns, or when its promise resolves. A rejected promise leaves it open.

Behavior:
- Controlled only: `open` and `onOpenChange` are required. The trigger lives outside, usually a menu item, a row action or a destructive button in a settings section.
- Built on Alert dialog, so the scrim doesn't close it. Esc and Cancel do, except while pending.
- Confirming calls `onConfirm`. A plain return closes the dialog right away. A returned promise keeps it open with the spinner, then closes on resolve. On reject it stays open and the error propagates, so catch it and show a toast yourself.
- With `confirmText`, the input sits in a form, so Enter confirms once the name matches. The comparison trims whitespace and is case-sensitive. The surface widens to 28rem.
- `usePendingItem<T>()` returns `{ item, open, show, setOpen, close }`. Call `show(row)` from the trigger, read `item` in the title, and pass `open` and `setOpen` to the dialog. `item` survives the close so the title never flashes to a fallback.
- Timings are Alert dialog's: 200ms in from 0.96, 140ms out toward 0.98.

Do and don't:
- Do: Repeat the consequence on the button: a dialog titled Delete Northwind Freight? confirms with Delete supplier.
- Don't: Answer with OK or Yes. People confirm without reading, and the button says nothing about what goes away.
- Do: Save the typed check for permanent, large losses: a payment run with its invoices, a production key.
- Don't: Ask for a typed name to skip one invoice. When every confirmation is typed, people learn to type without thinking.
- Do: Say what happens next in the description, with the numbers: Widgets on cedarline.io stop loading.
- Don't: Write This action cannot be undone. and nothing else. It warns without saying what's at stake.

Content:
- Title: a question with the object's name and a question mark. Remove Halcyon's bank account?, not Are you sure?
- Description: the consequence in one or two sentences. Name what stops working and what's kept. Offer the gentler alternative if there is one: To pause it instead, turn it off.
- Confirm label: the verb and object from the title. Delete supplier, Remove key, Rotate key.
- Cancel label: keep Cancel unless backing out has a clearer name, such as Keep key.
- The typed label defaults to Type {name} to confirm. Replace it with `confirmTextLabel` only to say where the name comes from.
- After it succeeds, confirm with a toast that names the object: Northwind Freight deleted.

Accessibility:
- The surface is `role="alertdialog"`, named by the title and described by the description, so the question and its consequence are announced together.
- Initial focus lands on Cancel, so a stray Enter backs out. With `confirmText`, it lands on the input instead.
- The typed input is labelled by its visible label through `htmlFor`.
- While pending, the confirm label stays in place and the spinner is hidden from assistive tech. Nothing announces the wait; follow up with a toast when it settles.
- Focus returns to the element that opened it. When the trigger was a row that's now deleted, move focus somewhere sensible, such as the table.
- Tab: Moves between the input, Cancel and the confirm button, wrapping.
- Enter: Activates the focused button. In the typed input, confirms once the name matches.
- Esc: Cancels, unless a confirmation is pending.

Known gaps (follow the system, not the gap):
- A rejected `onConfirm` promise isn't caught. The dialog stays open with no message and the rejection surfaces as an unhandled error, so every async caller has to catch and toast.
- Pending isn't announced: there is no `aria-busy` and the spinner is hidden. Screen reader users hear nothing until the dialog closes.
- The typed check is case-sensitive with no hint. Typing halcyon for Halcyon keeps the button disabled without saying why.
- Some callers, such as `confirm-delete-dialog.tsx`, call `onOpenChange(false)` inside `onConfirm`, which the component already does.

API `ConfirmDialog`:
- `open: boolean`. Whether it is open.
- `onOpenChange: (open: boolean) => void`. Called on Cancel, Esc and after a confirm. Ignored while pending.
- `title: React.ReactNode`. The question, naming the object.
- `description: React.ReactNode`. What happens and to what.
- `confirmLabel: React.ReactNode`. The confirm button's label. Repeat the consequence.
- `cancelLabel?: React.ReactNode` = "Cancel". The cancel button's label.
- `onConfirm: () => unknown`. Runs on confirm. Return a promise to keep the dialog open with a spinner until it settles.
- `destructive?: boolean` = true. The red tint. Set `false` for a consequential action that doesn't destroy anything.
- `confirmDisabled?: boolean`. Disables the confirm button.
- `confirmText?: string`. The exact text to type before confirming. Widens the surface to 28rem.
- `confirmTextLabel?: React.ReactNode`. Replaces the Type {confirmText} to confirm label.
- `children?: React.ReactNode`. Body content between the header and the footer.
- `className?: string`. Merged onto `AlertDialogContent`.

API `usePendingItem`:

### Form dialog

- Level: Organism
- Category: Overlays
- Status: Beta
- Import: `@oration/canon/components/form-dialog`
- Exports: `FormDialog`
- Docs: /design/components/form-dialog

Form dialog is the ready-made dialog for creating or editing one record with a few fields: New supplier, Add W-9 contact, Edit payment terms. It supplies the header, a `<form>` with a Field group spaced 16px apart, and a footer band with Cancel and a filled submit, so every create dialog in the suite looks and submits the same way. You bring the fields and the `onSubmit`. What people get wrong: it doesn't validate, show errors or track pending state for you. Prevent the default, validate in `onSubmit`, mark the fields invalid, and close it yourself.

When to use:
- To create a record from a list or a record header: New supplier, New invoice, Add contact.
- To edit two to six fields of one record where the page behind doesn't need to stay visible.
- When a quick-create from a combobox or a menu item needs a short form, such as adding a cost center without leaving the invoice.

When not to use:
- For a long edit, or details people compare with the list behind. Keep the list in view. Use /design/components/sheet instead.
- For a form that is the page, such as supplier settings. Save it in place. Use /design/components/save-bar instead.
- For a yes or no with no fields. Use /design/components/confirm-dialog instead.
- For a layout the props can't express: a scrolling list, a stepper, a split body. Use /design/components/dialog instead.
- For setup that spans several pages, such as connecting a bank. Use /design/components/stacked-dialog instead.

Rules:
- The One Filled Button Rule: The submit is the dialog's one filled button, last in the footer. Cancel is outline. A delete in an edit dialog goes on the left in the red tint, through the `footer` prop.
- Every field has a label: Each control inside is a `Field` with a visible `FieldLabel`, or an `sr-only` one when a group heading already names it. Placeholders are examples, never labels.

Anatomy:
- Header: `DialogTitle` names the record (New supplier) and the optional description says what happens to it. Sits outside the form.
- Fields: Your `children`, inside a `FieldGroup` with 16px between fields. Pair short fields in a two-column grid.
- Footer band: The Dialog footer band, inside the form, 20px below the last field. Replace it wholesale with `footer`.
- Cancel: An outline button that calls `onOpenChange(false)`. Labelled by `cancelLabel`.
- Submit: `type="submit"`, filled, labelled by `submitLabel`. Disable it with `submitDisabled` only while a submit is in flight.
- Close button: The Dialog close button in the top right. Always shown; there is no prop to hide it.

States:
- Open: Focus goes to the first focusable element, usually the first field. Put `autoFocus` on it to be explicit.
- Invalid: After a failed submit, the fields you mark with `data-invalid` on `Field` and `aria-invalid` on the control draw the red border and ring, with a `FieldError` below.
- Submitting: Not built in. Pass `submitDisabled` or a custom `footer` with a Pending button while the request runs.
- Closed: The fields unmount. Reset your form state when it opens, not when it closes, so the closing animation doesn't show empty fields.

Behavior:
- Controlled only: `open` and `onOpenChange` are required. Esc, the scrim, the close button and Cancel all call `onOpenChange(false)`.
- `onSubmit` receives the native form event. Call `event.preventDefault()`, validate, and on success close the dialog and confirm with a toast.
- The form has `noValidate`, so the browser's own bubbles never appear. Validate in `onSubmit` and show messages with `FieldError`.
- Enter in any single-line input submits the form. The default Cancel is `type="button"`, so it never submits.
- `footer` replaces the default footer and renders inside the form, so a `type="submit"` button in it still submits.
- Width defaults to 28rem through `contentClassName="sm:max-w-md"`. Pass `sm:max-w-lg` for two columns of fields.
- Motion is Dialog's: 200ms in from 0.96, 140ms out toward 0.98.

Do and don't:
- Do: Label the submit with the verb and the object: Add supplier, Save terms.
- Don't: Leave it as Submit or OK, or leave `submitLabel` out and ship an empty button.
- Do: Keep the submit enabled and explain what's missing when it's pressed, next to the field.
- Don't: Disable the submit until the form is valid. Nobody can tell why it won't press.
- Do: Ask only for what's needed to create the record. Everything else is edited on the record after.
- Don't: Put twelve fields and a tab strip in a form dialog. That's a sheet or a page.

Content:
- Title: New supplier for create, Edit payment terms for edit. Sentence case, no period.
- Description: one sentence on what happens after, such as We email a W-9 request to the remit-to address. Leave it out rather than restating the title.
- Labels are nouns: Legal name, Remit-to email, Terms. Mark optional fields with (optional) rather than marking required ones.
- Errors say what to do: Enter a legal name., That email is missing an @.
- Submit repeats the title's verb and object; Cancel stays Cancel.

Accessibility:
- It is a Dialog: `role="dialog"`, labelled by the title and described by the description.
- Every control needs a label through `FieldLabel htmlFor`. For a Select trigger without an input, give it an `aria-label` too.
- Mark invalid controls with `aria-invalid` and render the message in `FieldError`, which has `role="alert"`, so it's announced on submit.
- Move focus to the first invalid field after a failed submit.
- Focus returns to the trigger when it closes.
- Tab: Moves through the fields and buttons.
- Enter: Submits the form from any single-line input.
- Esc: Closes without saving.

Known gaps (follow the system, not the gap):
- The registry describes it as handling submit, pending and errors. It handles none of them: there is no pending state, no error slot and no validation, and the form doesn't prevent its default.
- `submitLabel` has no default, so leaving it out renders an empty filled button.
- The close button can't be hidden; the component doesn't forward `showCloseButton`.
- `contentClassName` replaces the default rather than merging with it, so passing `p-0` alone drops the 28rem width.
- Only five files in the product use it, while 32 files compose `DialogContent` around a `<form>` by hand, most with the same header, field group and footer.

API `FormDialog`:
- `open: boolean`. Whether it is open.
- `onOpenChange: (open: boolean) => void`. Called by Esc, the scrim, the close button and Cancel.
- `title: React.ReactNode`. Names the record or the task.
- `description?: React.ReactNode`. One sentence under the title. Omitted when empty.
- `onSubmit: React.FormEventHandler<HTMLFormElement>`. Runs on submit. Prevent the default, validate and close it yourself.
- `children: React.ReactNode`. The fields, rendered in a `FieldGroup` with `gap-4`.
- `submitLabel?: React.ReactNode`. The submit button's label. There is no default.
- `submitDisabled?: boolean`. Disables the submit button.
- `cancelLabel?: React.ReactNode` = "Cancel". The cancel button's label.
- `contentClassName?: string` = "sm:max-w-md". Classes for `DialogContent`. Replaces the default width, so include one.
- `footer?: React.ReactNode`. Replaces the default footer. Render a `DialogFooter` with your own buttons.

### Stacked dialog

- Level: Organism
- Category: Overlays
- Status: Beta
- Import: `@oration/canon/components/stacked-dialog`
- Exports: `StackedDialog`, `StackedDialogPage`
- Docs: /design/components/stacked-dialog

Stacked dialog shows three to six pages that are read or completed in order, as a pile of cards with a control bar below. Next slides the front card away and the one behind rises; Previous brings it back. The product uses it for What's new and for adding an identity provider. The control bar never moves, so focus stays on Next while the pages change. It is not a wizard for long forms: each page should fit on one card and stand on its own.

When to use:
- For a short sequence people page through: what's new, a feature tour, the steps of connecting a bank feed.
- For setup with three or four steps where each step is one decision, ending in Activate or Connect.
- When people should be able to go back a page without losing what they entered.

When not to use:
- For one task on one screen, even a long one. Use /design/components/dialog instead.
- For showing progress through stages on the page itself, such as an invoice moving from received to paid. Use /design/components/stepper instead.
- For a single form with a submit. Use /design/components/form-dialog instead.
- For a collapsed pile of cards on a page, such as the what's new cards in the sidebar. Use /design/components/card-stack instead.
- For slides people browse in any order. Use /design/components/carousel instead.

Rules:
- The One Filled Button Rule: Next (or Done) is the only filled button, in the control bar. Extra `actions` beside it are ghost buttons, and pages don't add filled buttons of their own.
- Exits are faster than enters: The leaving card fades in 160ms while the arriving card settles on a 240ms spring, so the stack never waits on the card going away.

Anatomy:
- Back cards: Up to two decorative cards peek 10px each above the front one, at 95% and 90% scale and 75% and 50% opacity. They show how many pages are left.
- Page: The front card: Popover White, 16px corners, the dialog shadow and ring. It has no padding; your `content` pads itself.
- Close button: A 28px ghost icon button over the top right of the page. Leave room for it in your content.
- Previous: A 28px ghost icon button named Previous. On the first page it dims with `aria-disabled` instead of `disabled`, so it keeps focus.
- Progress: Dots (16px for the current page, ink at 35% behind it and 15% ahead) and an n of m count that is announced when it changes.
- Actions: Optional `actions`, such as Mark all as read, before Next.
- Next: A small filled button labelled `nextLabel`, becoming `doneLabel` on the last page. It takes focus when the dialog opens.

States:
- Opening: Fades in from a 0.96 scale over 200ms at `defaultIndex`, with the scrim. Focus lands on Next.
- Paging forward: The front card leaves to the left, rotating 3 degrees as it fades in 160ms. The next card rises from 12px above at a 0.95 scale on a 240ms spring.
- Paging back: The previous card returns from the left and the current one sinks back into the pile.
- First page: Previous dims to 40% and does nothing when pressed.
- Last page: Next reads `doneLabel` and closes the dialog. No back cards remain.
- Reduced motion: With the app's `MotionConfig reducedMotion="user"`, the slides and scales drop out and pages cross-fade. The dots stop animating their width.

Behavior:
- Controlled open state: `open` and `onOpenChange` are required. Esc, the scrim, the close button and Done all close it.
- The page index is uncontrolled by default and resets to `defaultIndex` each time it opens. Pass `index` and `onIndexChange` to control it, for example to gate a step or to act on close depending on where people are.
- The right and left arrow keys page, unless focus is in an input, textarea, select or editable region.
- Done calls `onOpenChange(false)`. To act on completion, check the index in `onOpenChange`, as the identity provider flow does before activating.
- `title` and `description` name and describe the dialog for assistive tech only. Give each page a visible heading and pass the same words as its `label`.
- Built on Base UI Dialog with the dialog `data-slot`s, so it shares Dialog's 200ms entrance and 140ms exit. Paging uses Motion: the arriving card on the slow spring (240ms, slight bounce), the leaving card on a 160ms ease-out tween.

Do and don't:
- Do: Keep it to three to six pages, each one short enough to read without scrolling.
- Don't: Stack twelve pages. The dots stop meaning anything, and people close it halfway.
- Do: Give every page a visible heading and pass it as `label`, so the page is announced by name.
- Don't: Rely on the dots and 3 of 5 to tell people where they are.
- Do: Put extra actions in `actions` as ghost buttons beside Next.
- Don't: Put a filled button inside a page. It competes with Next and moves as the cards change.

Content:
- `title` names the whole sequence: What's new, Connect a bank account.
- Page headings are short and specific: Choose your bank, Faster remittance matching.
- Keep `nextLabel` as Next. Make `doneLabel` the outcome: Connect bank, Activate, or Done for something only read.
- Actions are short ghost labels: Mark all as read, Skip tour.

Accessibility:
- The popup is a Base UI dialog named by the hidden `title` and described by the hidden `description`.
- Each page is a `<section>` with `aria-roledescription="page"` and an `aria-label` from `label`, falling back to n of m.
- The n of m count is `aria-live="polite"`, so paging is announced. The dots are hidden from assistive tech.
- Focus starts on Next and stays there while pages change, because the control bar doesn't move. Previous uses `aria-disabled` on the first page so focus isn't dropped.
- The back cards are `aria-hidden` and ignore pointer events.
- →: Next page.
- ←: Previous page.
- Enter: Activates the focused button, usually Next.
- Tab: Moves through the page and the control bar.
- Esc: Closes the dialog.

Known gaps (follow the system, not the gap):
- Pages use 16px corners (`rounded-2xl`). DESIGN.md gives dialogs and cards 12px container corners, and 16px isn't in the ramp.
- The arriving card uses the slow spring with a 0.12 bounce. DESIGN.md's motion grammar is ease-out everywhere, and other springs in the suite have no bounce.
- Previous is icon-only with no tooltip.
- The close button sits over the page content with no reserved space, so every page has to pad its top right by hand.
- The dialog title is always hidden. There is no visible heading for the sequence as a whole.

API `StackedDialog`:
- `open: boolean`. Whether it is open.
- `onOpenChange: (open: boolean) => void`. Called by Esc, the scrim, the close button and Done.
- `pages: StackedDialogPage[]`. The pages, in order.
- `index?: number`. Controlled page index.
- `defaultIndex?: number` = 0. The page shown each time it opens, when uncontrolled.
- `onIndexChange?: (index: number) => void`. Called when Next, Previous or an arrow key pages.
- `title: string`. The dialog's accessible name. Not shown.
- `description?: string`. The dialog's accessible description. Not shown.
- `actions?: React.ReactNode`. Extra controls in the control bar, before Next.
- `nextLabel?: string` = "Next". Next button label.
- `doneLabel?: string` = "Done". Next button label on the last page.
- `className?: string`. Merged onto the popup, which holds the stack and the bar.

API `StackedDialogPage`:
- `id: string`. Stable key, used to animate the right card.
- `label?: string`. Accessible name for the page, usually its heading.
- `content: React.ReactNode`. The page body. Pad it yourself (the product uses 20px).

### Sheet

- Level: Organism
- Category: Overlays
- Status: Stable
- Import: `@oration/canon/components/sheet`
- Exports: `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetTitle`, `SheetDescription`, `SheetFooter`
- Docs: /design/components/sheet

Sheet is a panel that slides in from an edge of the screen, usually the right, for record details and longer edits that belong beside the list they came from: an invoice opened from the payables table, a supplier's bank details, a queue's routing. It is modal, like a dialog, but its shape says "this is about the row you clicked" and it has room for a scrolling body. It is the most used overlay in the product. The common mistake is letting the whole panel scroll, so the Save button scrolls away: pin the header and footer and scroll only the body.

When to use:
- To show a record's details from a table row or card without leaving the list: an invoice, a supplier, a payment run.
- For an edit with more fields than a dialog holds, such as a supplier's remit-to and banking details.
- For logs, histories and timelines that scroll, such as the activity on a remittance.
- On phones, for navigation that would be a sidebar on desktop, from the left.

When not to use:
- For a short task the page waits on, such as editing payment terms. Use /design/components/dialog instead.
- For confirming a delete or another consequential action. Use /design/components/confirm-dialog instead.
- For a touch-first panel people expect to swipe away. Use /design/components/drawer instead.
- For a few controls tied to one button that apply as you change them. Use /design/components/popover instead.
- For details that should stay open while people keep working in the list. Use a resizable split view instead. Use /design/components/resizable instead.

Rules:
- The One Filled Button Rule: The footer holds the sheet's one filled button, last in the row. Links out, such as Open supplier, are ghost buttons on the left.
- The Scroll Edge Rule: The header and footer stay put and the body scrolls between them, with hairlines marking where the scroll area starts and ends.

Anatomy:
- Scrim: Black at 25% (55% in dark), fading over 200ms. Clicking it closes the sheet.
- Panel: `SheetContent`: Popover White, the dialog shadow and a hairline on the inner edge. From the left or right it is full height, 75% wide on phones and 24rem from 640px; from the top or bottom it is full width and as tall as its content.
- Close button: A 28px ghost icon button 12px from the top right, named Close.
- Header: `SheetHeader`, 16px padding, with `SheetTitle` (16px, weight 500) and `SheetDescription` (14px Slate Meta) 2px apart. The product adds `border-b` when the body scrolls.
- Body: Your content. For long bodies, `min-h-0 flex-1 overflow-y-auto p-4` so it scrolls between the header and footer.
- Footer: `SheetFooter`, pushed to the bottom with `mt-auto`, 16px padding, stacked by default. The product passes `flex-row justify-end border-t border-border`.

States:
- Closed: Nothing is rendered.
- Opening: Slides 2.5rem in from its edge while fading in, over 320ms on the drawer curve, cubic-bezier(0.32, 0.72, 0, 1). The scrim fades in over 200ms.
- Open: Focus is inside and trapped, the page is inert and its scroll locked.
- Closing: Slides 2.5rem back toward its edge and fades in 200ms, faster than it came in.
- Reduced motion: Only opacity transitions. The sheet fades in and out in place.

Behavior:
- Built on Base UI Dialog, so it behaves like one: `SheetTrigger` opens it; Esc, the scrim, the close button and any `SheetClose` close it.
- Opening moves focus to the first focusable element inside. Closing returns focus to the trigger, or to whatever had focus before.
- Opened from a table row, it is controlled: keep the selected record in state and pass `open={record !== null}`. Keep the record until the close animation finishes, so the panel doesn't empty as it leaves.
- The panel is a flex column with 16px gaps. For a pinned header and footer, pass `gap-0`, give the header `border-b`, the body `min-h-0 flex-1 overflow-y-auto p-4` and the footer `border-t`.
- Width is a class: the product passes `w-full` with `sm:max-w-md` (28rem) or `sm:max-w-lg` (32rem) most. Top and bottom sheets take their height from their content.
- Timings come from globals.css, keyed on `data-slot="sheet-content"`: 320ms in on the drawer curve and 200ms out. Under reduced motion only opacity transitions.

Do and don't:
- Do: Pin the header and footer and scroll only the body, so the title and Save are always in view.
- Don't: Let the whole panel scroll. The title and Save scroll away and people hunt for them.
- Do: Open details from the row they belong to, and keep the list visible behind the scrim.
- Don't: Use a sheet for a yes or no question. It's a lot of surface for one sentence; use a confirmation.
- Do: Put the one filled button in the footer, right-aligned, with Cancel beside it.
- Don't: Put Save in the header next to the close button. It's easy to hit the wrong one.

Content:
- The title is the record's name (INV-20931, Northwind Freight) or the task (Edit banking details).
- The description adds the one fact that places the record: Due Friday, Oct 2, in payment run PR-0412.
- Section headings inside are 13px medium, sentence case: Payment history, Remit-to.
- Footer buttons follow Button: Save changes, Cancel, and Close when nothing can change.

Accessibility:
- The panel is `role="dialog"`, labelled by `SheetTitle` and described by `SheetDescription`. Every sheet needs a title; hide it with `sr-only` if the design has none.
- Focus moves in on open, is trapped while open and returns to the trigger on close. When the trigger was a table row, make the row focusable so focus has somewhere to go back to.
- The page behind is inert while it's open.
- The close button is named Close and is 28px.
- Under reduced motion only opacity changes.
- Enter: Opens the sheet from its trigger.
- Tab: Moves through the controls inside, wrapping at the ends.
- Esc: Closes the sheet and returns focus.

Known gaps (follow the system, not the gap):
- The panel draws a CSS border on its inner edge as well as the dialog shadow. The Hairline-and-Lift Rule says a raised surface takes its edge from one composite shadow, not a border plus a shadow.
- `SheetFooter` is a plain padded row, not the Well Gray band Dialog uses, and it stacks by default. The product passes `flex-row justify-end border-t border-border` by hand in most of its sheets.
- `SheetTitle` has the default line height; DESIGN.md sets Title Large at line-height 1 for dialog and sheet titles, and `DialogTitle` follows it.
- The component's own classes say `duration-200 ease-drawer`. globals.css overrides them to 320ms in and 200ms out through `data-slot`, so a hand-rolled panel without the slot animates at 200ms both ways.
- Side sheets are 75% wide on phones. The product almost always passes `w-full`.
- `SheetPortal` and the overlay are defined but not exported.

API `Sheet` (extends Base UI `Dialog.Root`):
- `open?: boolean`. Controls whether it is open.
- `defaultOpen?: boolean` = false. Whether it starts open when uncontrolled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when it opens or closes.
- `onOpenChangeComplete?: (open: boolean) => void`. Called after the animation ends. Clear the selected record here.
- `modal?: boolean | "trap-focus"` = true. Leave it on.
- `disablePointerDismissal?: boolean` = false. Keeps a click on the scrim from closing it.

API `SheetTrigger` (extends Base UI `Dialog.Trigger` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render your own button, such as `<Button variant="outline" />`.

API `SheetHeader` (extends `<div>`):

API `SheetTitle` (extends Base UI `Dialog.Title` (`<h2>`)):

API `SheetDescription` (extends Base UI `Dialog.Description` (`<p>`)):

API `SheetFooter` (extends `<div>`):

API `SheetClose` (extends Base UI `Dialog.Close` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Usually `<Button variant="outline" />`.

### Drawer

- Level: Organism
- Category: Overlays
- Status: Experimental
- Import: `@oration/canon/components/drawer`
- Exports: `Drawer`, `DrawerContent`, `DrawerHeader`, `DrawerTitle`, `DrawerFooter`, `DrawerSwipeHandle`
- Docs: /design/components/drawer

Drawer is a panel that people can drag and swipe: from the bottom by default, or from any edge, with optional snap points and nested drawers. It is built for touch, where a bottom sheet that follows the finger feels native, and it is the only overlay in the suite that tracks a gesture. Nothing in the product uses it yet; on desktop and for record details, Sheet is the right choice. The easy mistake is shipping one without a way to close it that people can see: it has no close button, so show the swipe handle or put a Close in the footer.

When to use:
- For a short task on a phone, such as approving an invoice from a notification, where swiping down to dismiss is expected.
- For a picker or a filter list on touch screens that people open, choose from and flick away.
- With snap points, for a list that peeks at half height and expands to full when dragged up.

When not to use:
- For record details or a long edit on desktop. Use /design/components/sheet instead.
- For a focused task the page waits on, on any screen size. Use /design/components/dialog instead.
- For a confirmation. Use /design/components/confirm-dialog instead.
- For a menu of actions on a row. Use /design/components/dropdown-menu instead.

Rules:
- The One Filled Button Rule: The footer holds one filled button, the action the drawer exists for. On phones footer buttons stack full width, primary on top.
- Exits are faster than enters: A swipe closes it in time with the gesture: the exit runs `--drawer-swipe-strength` times 400ms, so a fast flick leaves faster than a slow drag.

Anatomy:
- Scrim: Black at 25% (55% in dark), fading as the drawer is dragged away. With snap points it never drops below 50% of that.
- Swipe handle: With `showSwipeHandle`: a 96 by 4px Well Gray pill in a 12px strip at the grabbing edge. Decorative; the whole panel is draggable.
- Panel: Popover White with 12px corners on the free edge and a hairline along it. From the bottom it is full width and up to the viewport height minus 6rem; from a side it is 75% wide, 24rem from 640px.
- Header: `DrawerHeader`, 16px padding with none below, `DrawerTitle` (16px, weight 500) and `DrawerDescription` (14px Slate Meta, balanced). Centered for top and bottom drawers below 768px.
- Body: Your content, inside a clipping column. Add `min-h-0 flex-1 overflow-y-auto` to a wrapper to scroll it.
- Footer: `DrawerFooter`, pushed down with `mt-auto`, 16px padding with none above, buttons stacked 8px apart.

States:
- Closed: Nothing is rendered.
- Opening: Slides fully in from its edge over 450ms on cubic-bezier(0.22, 1, 0.36, 1); the scrim fades in over 450ms on the drawer curve.
- Open: Modal by default: focus trapped, page inert. Text inside is selectable until a drag starts.
- Swiping: Follows the pointer with no transition, and the scrim fades in proportion. Text selection is turned off.
- Snapped: With `snapPoints`, rests at the nearest point on release. A fast flick can skip points unless `snapToSequentialPoints` is set.
- Nested open: When a drawer opens inside it, the parent scales down by 5%, peeks 1rem, dims to 95% brightness and fades its content out.
- Closing: Slides back out, in time with the release velocity when swiped.

Behavior:
- Built on Base UI Drawer. `DrawerTrigger` opens it; a swipe toward `swipeDirection`, Esc, a click on the scrim or any `DrawerClose` closes it.
- There is no close button. Show the swipe handle with `showSwipeHandle`, add a Close in the footer, or both.
- `swipeDirection` sets the edge: `down` (the default) enters from the bottom, `up` from the top, `left` and `right` from the sides.
- `snapPoints` takes fractions of the viewport height (0 to 1), pixel numbers or `px` and `rem` strings. Control the current point with `snapPoint` and `onSnapPointChange`.
- `modal={false}` leaves the page interactive and drops the scrim.
- Focus moves in on open and returns to the trigger on close, as with Dialog.
- A 3rem bleed in the panel color extends past the edge, so over-dragging never shows a gap.

Do and don't:
- Do: Show the swipe handle, and add a Close button when the drawer holds a form.
- Don't: Ship a drawer with no handle and no Close. Nothing on screen says how to get out.
- Do: Use a drawer on touch screens and a sheet or dialog on desktop for the same task.
- Don't: Use a bottom drawer for record details on a 1440px screen. It covers the list the details belong to.

Content:
- Titles are short and name the task: Approve INV-20931, Filter invoices.
- The description gives the one fact needed to decide: $18,240.00 to Northwind Freight, due Friday.
- Footer buttons follow Button: verb first, and Cancel or Close last.

Accessibility:
- The popup is `role="dialog"`, labelled by `DrawerTitle` and described by `DrawerDescription`. Always render a title.
- Swiping is never the only way out: Esc and the scrim close it, and a Close button in the footer serves people who can't drag.
- The swipe handle is `aria-hidden`; it's a visual cue only.
- Focus is trapped while it's modal and returns to the trigger on close.
- Hit areas in the footer are full width on phones and at least 32px tall.
- Enter: Opens it from the trigger.
- Tab: Moves through the controls inside.
- Esc: Closes it and returns focus.

Known gaps (follow the system, not the gap):
- No file in `apps/web` imports it; every edge panel in the product is a Sheet. Hence experimental.
- The panel takes its edge from a CSS border and has no shadow or ring. DESIGN.md gives dialogs and sheets the dialog shadow, and the Hairline-and-Lift Rule rules out a border as a raised surface's edge.
- It opens over 450ms on its own curve, cubic-bezier(0.22, 1, 0.36, 1). DESIGN.md caps state changes at 320ms and gives edge panels the drawer curve.
- Reduced motion isn't handled. The slide is driven by its own transform variables, which the global reduced-motion rule doesn't zero, so the drawer still slides.
- There is no close button and no prop for one, unlike Dialog and Sheet.
- The swipe handle pill is Well Gray on Popover White, which is very faint in light mode.

API `Drawer` (extends Base UI `Drawer.Root`):
- `open?: boolean`. Controls whether it is open.
- `defaultOpen?: boolean` = false. Whether it starts open when uncontrolled.
- `onOpenChange?: (open: boolean, eventDetails) => void`. Called when it opens or closes, including by swipe.
- `swipeDirection?: "up" | "down" | "left" | "right"` = "down". The direction that dismisses it, and so its edge.
- `showSwipeHandle?: boolean` = false. Draws the handle pill at the grabbing edge.
- `snapPoints?: (number | string)[]`. Resting positions: fractions of the viewport, pixels, or `px` and `rem` strings.
- `snapPoint?: number | string | null`. The current snap point, when controlled.
- `defaultSnapPoint?: number | string | null`. The starting snap point, when uncontrolled.
- `onSnapPointChange?: (snapPoint: number | string | null, eventDetails) => void`. Called when it settles on a new snap point.
- `snapToSequentialPoints?: boolean` = false. Stops a fast flick from skipping snap points.
- `modal?: boolean | "trap-focus"` = true. `false` keeps the page interactive and hides the scrim.
- `disablePointerDismissal?: boolean` = false. Keeps a click on the scrim from closing it.

API `DrawerTrigger` (extends Base UI `Drawer.Trigger` (`<button>`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render your own button, such as `<Button variant="outline" />`.

API `DrawerContent` (extends Base UI `Drawer.Popup`):
- `className?: string`. Merged onto the popup. Set `[--drawer-height:…]` for a fixed height.

API `DrawerHeader` (extends `<div>`):

API `DrawerTitle` (extends Base UI `Drawer.Title` (`<h2>`)):

API `DrawerDescription` (extends Base UI `Drawer.Description` (`<p>`)):

API `DrawerFooter` (extends `<div>`):

API `DrawerClose` (extends Base UI `Drawer.Close` (`<button>`)):

API `DrawerSwipeHandle` (extends `<div>`):

API `DrawerOverlay` (extends Base UI `Drawer.Backdrop`):

API `DrawerPortal` (extends Base UI `Drawer.Portal`):

### Command menu

- Level: Organism
- Category: Navigation
- Status: Stable
- Import: `@oration/canon/components/command`
- Exports: `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandGroup`, `CommandItem`, `CommandShortcut`, `CommandEmpty`
- Docs: /design/components/command

Command is a filterable list of actions and records driven from the keyboard, built on cmdk. In Oration it powers the ⌘K palette (search records, jump to a page, run an action) and the searchable pickers inside popovers, such as Filter by. Typing filters and ranks items, the arrow keys move a highlight and Enter runs the item. The palette opens and closes without motion, because it is a keyboard surface people open dozens of times a day. The common mistake is reaching for the ready-made `CommandDialog`: the product composes `Dialog` and `Command` itself to get the right width, position and no-motion behavior.

When to use:
- For the ⌘K palette: one input that finds records, pages and actions across the workspace.
- For a searchable list inside a popover: Filter by, Assign to, Move to stage, Add a label.
- For an action menu on selected rows that's driven from the keyboard, such as the ticket action palette.

When not to use:
- For choosing one value in a form field. It needs a field's label, value display and validation. Use /design/components/combobox instead.
- For five or fewer actions on a button, with no search. Use /design/components/dropdown-menu instead.
- For a search box that filters a table on the page. Use /design/components/search-field instead.
- For picking from a short fixed list in a form. Use /design/components/select instead.

Rules:
- Keyboard surfaces don't animate: The ⌘K palette opens and closes with no motion: pass `data-no-motion` on `DialogContent`. Highlight changes are instant too; only hover color eases.
- The Hairline-and-Lift Rule: Inside a palette the input sits over a hairline and the footer under one. Groups split with `CommandSeparator` hairlines, not boxes.

Anatomy:
- Input: `CommandInput`: a search icon and a borderless input. In the palette it is 40px tall over a hairline; on its own it is a 32px tinted field.
- Group heading: `CommandGroup heading`: 12px medium Slate Meta, 8px from the left. Sentence case: Actions, Suppliers.
- Item: `CommandItem`: a 16px icon, a 14px label and an optional trailing detail. The highlighted item fills Well Gray. 10px corners inside a dialog, 6px elsewhere.
- Shortcut: `CommandShortcut`, right-aligned 12px Slate Meta with wide tracking. Turns ink when its item is highlighted.
- Separator: `CommandSeparator`, a hairline that bleeds to the list edges.
- Footer: The palette's own row of key hints over a hairline: ↑ ↓ to move, ↵ to open, esc to close. Not part of the component; compose it with `Kbd`.

States:
- Rest: Items show their label and icon in ink, details in Slate Meta.
- Highlighted: The item under the arrow keys or the pointer fills Well Gray (`data-selected`). Its icon and shortcut turn ink.
- Checked: Pass `data-checked` on an item to show the trailing check, for multi-select pickers. Items with a shortcut never show it.
- Disabled: `disabled` items dim to 50%, ignore the pointer and are skipped by the arrow keys.
- Filtered: Typing hides items that don't match and reorders the rest by score. Groups with no matches hide.
- Empty: `CommandEmpty` renders only when nothing matches. Say what can be searched.

Behavior:
- cmdk filters as you type, matching the item's `value` (its text by default) and any `keywords`. Give items a `value` with synonyms, as the palette does: Invite members teammates.
- ↑ and ↓ move the highlight, Enter calls the item's `onSelect`, and pointer hover highlights too. `loop` wraps from the last item to the first.
- In a dialog: compose `Dialog`, `DialogContent` and `Command` yourself. The palette passes `data-no-motion`, `showCloseButton={false}`, `top-[16%] translate-y-0 p-0 gap-0 sm:max-w-xl`, and a hidden `DialogTitle` and `DialogDescription`.
- Selecting an item doesn't close anything. Close the dialog or popover in `onSelect`, then navigate or run the action.
- In a popover, pass `p-0` to both the popover and the Command, and `className="rounded-lg!"` so the corners match.
- `CommandList` scrolls at 18rem by default with its scrollbar hidden. The palette raises it to `max-h-[min(60vh,26rem)]`.
- `shouldFilter={false}` turns filtering off for async results you filter on the server.

Do and don't:
- Do: Open the palette instantly, with no scale or fade, and keep the input focused.
- Don't: Animate it in like a dialog. People hit ⌘K, type and press Enter in under a second; motion only gets in the way.
- Do: Group results under short headings, put the most likely group first, and show a trailing detail that tells similar items apart.
- Don't: Dump everything in one long ungrouped list, with three Northwind Freight rows and nothing to tell them apart.
- Do: Write an empty state that says what can be searched: No matches. Try a supplier, invoice number or amount.
- Don't: Leave it at No results found.

Content:
- Placeholder says what can be found: Search suppliers, invoices and actions. No ellipsis.
- Action items start with a verb: New payment run, Invite members, Switch to dark theme.
- Record items are the record's name, with one disambiguating detail on the right: a domain, an amount, an invoice number.
- Group headings are plural nouns: Actions, Pages, Suppliers, Invoices.
- Shortcuts use symbols: ⌘J, ?, G then I.

Accessibility:
- cmdk renders the input as a `combobox` that controls a `listbox`, with `aria-activedescendant` pointing at the highlighted `option`, so screen readers announce the highlight while focus stays in the input.
- Give the input an accessible name: `CommandInput` has none of its own beyond the placeholder. Pass `aria-label`, or set `label` on `Command`.
- In a dialog, render a `DialogTitle` and `DialogDescription`, visually hidden, so the palette is announced by name.
- Icons in items are decorative; the label carries the meaning. Shortcuts are read as text, so write them as people would say them where it matters.
- Opening without motion also serves people who prefer reduced motion.
- ⌘ + K: Opens the palette (wired by the app shell).
- ↓: Highlights the next item.
- ↑: Highlights the previous item.
- Home: Highlights the first item. End goes to the last.
- Enter: Runs the highlighted item.
- Esc: Closes the palette or popover.

Known gaps (follow the system, not the gap):
- `CommandDialog` renders its hidden title and description outside `DialogContent`, so they sit in the page whether or not the dialog is open, and it doesn't pass `data-no-motion`, so it animates. Its defaults, Command Palette and Search for a command to run..., break sentence case and the no-ellipsis rule.
- Item corners are 6px outside a dialog and 10px inside one. DESIGN.md gives menu and select items 8px corners.
- `CommandList` hides its scrollbar (`no-scrollbar`) with no fade at the clipped edge, against the Scroll Edge Rule.
- `CommandInput` has no accessible name of its own; the product's palette relies on the placeholder.
- The input group overrides use `!important` modifiers (`h-8!`, `rounded-lg!`, `shadow-none!`), so the palette has to override them with `!` again.

API `Command` (extends cmdk `Command` (`<div>`)):
- `label?: string`. Accessible label for the input.
- `loop?: boolean` = false. Wraps the highlight from the last item to the first.
- `shouldFilter?: boolean` = true. Set `false` to filter items yourself.
- `filter?: (value: string, search: string, keywords?: string[]) => number`. Custom ranking. Return 0 to hide, 1 for best.
- `value?: string`. The highlighted item's value, when controlled.
- `onValueChange?: (value: string) => void`. Called when the highlight moves.
- `disablePointerSelection?: boolean` = false. Stops hover from moving the highlight.
- `vimBindings?: boolean` = true. Ctrl+N, Ctrl+P, Ctrl+J and Ctrl+K move the highlight.

API `CommandInput` (extends cmdk `Command.Input` (`<input>`)):
- `value?: string`. The search text, when controlled.
- `onValueChange?: (search: string) => void`. Called as the search text changes.
- `placeholder?: string`. What can be searched.

API `CommandList` (extends cmdk `Command.List`):

API `CommandEmpty` (extends cmdk `Command.Empty`):

API `CommandGroup` (extends cmdk `Command.Group`):
- `heading?: React.ReactNode`. The group heading.
- `forceMount?: boolean`. Keeps the group visible when nothing in it matches.

API `CommandItem` (extends cmdk `Command.Item`):
- `onSelect?: (value: string) => void`. Runs on Enter or click.
- `value?: string`. The text it's matched on. Defaults to its text content; add synonyms.
- `keywords?: string[]`. Extra terms it matches on.
- `disabled?: boolean`. Dims it and skips it.
- `forceMount?: boolean`. Keeps it visible whatever the search.
- `data-checked?: boolean`. Shows the trailing check.

API `CommandShortcut` (extends `<span>`):

API `CommandSeparator` (extends cmdk `Command.Separator`):

API `CommandDialog` (extends `Dialog` root props):
- `title?: string` = "Command Palette". Hidden dialog title.
- `description?: string` = "Search for a command to run...". Hidden dialog description.
- `showCloseButton?: boolean` = false. Draws the dialog close button.
- `className?: string`. Merged onto `DialogContent`.
- `children: React.ReactNode`. Usually a `Command`.

### Sidebar

- Level: Organism
- Category: Navigation
- Status: Beta
- Import: `@oration/canon/components/sidebar`
- Exports: `SidebarProvider`, `Sidebar`, `SidebarContent`, `SidebarGroup`, `SidebarMenu`, `SidebarMenuButton`, `SidebarInset`, `SidebarTrigger`, `useSidebar`
- Docs: /design/components/sidebar

Sidebar is the app rail: a provider that owns the open state and ⌘B, a shell that draws a 16rem Cool Rail on desktop and an 18rem sheet below 768px, and a kit of groups, menus, badges and sub-menus to fill it. Every workspace screen sits beside it (collapsing to a 3rem icon rail), and these docs use it too. The part people get wrong is the current page: mark it with `isActive` and `aria-current="page"`, pass `accent` to the `Sidebar`, and let the gliding mark draw it. Don't paint the active row yourself.

When to use:
- For the persistent, grouped navigation of a whole workspace or app, beside the content plane.
- When the rail should collapse to icons with tooltips, or slide away entirely, and come back with ⌘B.
- For long navigation that needs group labels, counts, per-item menus and one level of nesting.
- When the same navigation must work on a phone: below 768px it becomes a sheet with no extra code.

When not to use:
- For switching between two to six panels inside one page or card. Use /design/components/tabs instead.
- For the sections of one settings page or record, in a column beside the form. Use /design/components/side-tabs instead.
- For a horizontal top bar with flyout panels, as on a marketing site. Use /design/components/navigation-menu instead.
- For jumping anywhere by name from the keyboard. Use /design/components/command instead.
- For showing where a record sits in a hierarchy. Use /design/components/breadcrumb instead.

Rules:
- One current page, one mark: Exactly one row carries `isActive`: the page you're on. Its surface and 3px tick come from the gliding mark, in the `accent` color. When a collapsed group or parent hides the current page, that label or parent carries `isActive` instead.
- The Quiet Indigo Rule: The rail is Cool Rail and Rail Ink; the only color in it is the active mark. The docs use Quiet Indigo (`var(--primary)`); the workspace uses the current app's identity color. Icons, labels and badges stay neutral.
- The Thirteen-Fourteen Rule: Nav items are Body Dense at 13px on 28px rows (36px at 14px below 768px), group labels are 12px medium Slate Meta, and counts are 11px Slate Meta. These are the component defaults; don't resize rows at the call site.

Anatomy:
- Header: `SidebarHeader`: the 40px workspace switcher and the 32px search field with hairline lift and a ⌘K key.
- Group label: `SidebarGroupLabel`: 12px medium Slate Meta, sentence case. In the icon rail it slides up and fades out.
- Menu button: `SidebarMenuButton`: a 16px Slate Meta icon and a 13px label with a 10px gap, 8px corners, Rail Highlight on hover.
- Active row: The gliding surface (Card White with hairline lift) and a 3px tick in the `accent` color at the rail's left edge.
- Badge: `SidebarMenuBadge`: a count at the right of a row, in tabular figures. Hidden in the icon rail.
- Sub-menu: `SidebarMenuSub`: one nested level on a hairline under the parent's icon. Sub-items are 13px Slate Meta and darken on hover; the active one's tick sits on that line.
- Footer: `SidebarFooter`: the user menu, help and settings, divided from the content by a hairline.

States:
- Rest: Rail Ink text and Slate Meta icons on Cool Rail.
- Hover: Rail Highlight fill (white at 5% in dark) and foreground text. The active row never takes the hover fill, so nothing covers its card.
- Focus visible: A 2px ring in `--sidebar-ring` (indigo) around the row.
- Pressed: Rail Highlight while held.
- Active, no accent: `isActive` without `accent`: the row paints the same Card White surface with hairline lift itself, with medium weight and a foreground icon. No tick, no glide.
- Active with accent: The row's own fill clears and the shared surface and tick draw it. Switching rows glides both over 240ms with no bounce. During the 200ms width ease the row paints its card again and the tick stays.
- Open: A row whose menu is open (`data-popup-open`) keeps the hover fill.
- Disabled: `disabled` or `aria-disabled`: 50% opacity and no pointer events.
- Icon rail: `collapsible="icon"` and collapsed: 3rem wide, rows become 32px squares, labels and badges hide, group labels fade and tooltips name each row.
- Off canvas: `collapsible="offcanvas"` and collapsed: the rail slides out to the left and the content takes the width.
- Mobile: Below 768px the rail renders in an 18rem sheet from its side, opened by the trigger.
- Loading: `SidebarMenuSkeleton` rows at the row height, with an optional icon block.

Behavior:
- `SidebarProvider` owns `open` (desktop) and `openMobile` (sheet). Pass `defaultOpen`, or `open` and `onOpenChange` to control it. `useSidebar()` reads the state and `toggleSidebar()` from any descendant; it throws outside a provider.
- ⌘B (Ctrl+B) toggles the rail from anywhere: the desktop state, or the sheet on mobile. Each change writes the `sidebar_state` cookie for 7 days; read it on the server to pass `defaultOpen`.
- `SidebarTrigger` is a 28px ghost icon button that toggles; `SidebarRail` is a 16px hit strip on the rail's edge that toggles on click and shows a 2px hairline on hover. The rail is skipped by Tab.
- The rail's width eases over 200ms. `collapsible="none"` renders a static rail with no collapse, no sheet and no fixed positioning.
- Below 768px (`useIsMobile`) the rail moves into a Sheet with a screen-reader title. Close it on navigation yourself: call `setOpenMobile(false)` in each link's `onClick`, as both product sidebars do.
- `accent` turns on the gliding mark. It measures the active row and springs to the next one (240ms, no bounce), sticks to its row on scroll and resize, is clipped to the scroll area so a row scrolled out of view takes its mark with it, rides the row during the 200ms width ease, and fades out 180ms after no row is active. Under reduced motion it jumps.
- A collapsed group label with `isActive` wins the mark over the row it hides, and an active sub-item wins over its parent. In the icon rail the mark stays on the icon row.
- `tooltip` on a menu button only shows while the rail is collapsed to icons, on the right, and never on mobile.
- `showOnHover` on `SidebarMenuAction` hides the action until the row is hovered or focused, or its menu is open. On touch it is always visible.

Do and don't:
- Do: Mark the current page with `isActive` and `aria-current`, pass `accent`, and let the gliding mark draw the surface and tick.
- Don't: Style the active row yourself with an indigo fill. It fights the mark, breaks the rail's calm and reads as a button.
- Do: Write group labels as short sentence-case nouns: Payables, Compliance, Views.
- Don't: Set group labels in uppercase with letter spacing. It's the eyebrow pattern Canon refuses.
- Do: In the icon rail, give every row an icon and a `tooltip` with its label, and keep the header and footer icon-only too.
- Don't: Collapse a rail whose rows have no icons, or ship icons with no tooltip. The collapsed rail becomes a row of unnamed squares.

Content:
- Item labels are the page's name, one or two words, sentence case: Invoices, Payment runs, W-9s.
- Group labels are nouns that sort the items: Payables, Compliance, Views. Skip the label for the first, ungrouped block.
- Counts only for work waiting on the viewer: Approvals 12, Exceptions 7. Add screen-reader text for the unit ("12 invoices").
- Saved views are named for their filter: Due this week, On hold, not My view 2.
- Tooltips in the icon rail repeat the label exactly.

Accessibility:
- Wrap the menus in `<nav aria-label>`; `SidebarMenu` is a `<ul>` and each item an `<li>`, so screen readers announce the count.
- `isActive` only sets `data-active`. Add `aria-current="page"` to the current row yourself.
- In the icon rail, labels stay in the DOM (clipped, not removed), so every row keeps its accessible name; the tooltip is for sighted users.
- `SidebarTrigger` carries screen-reader text; wrap it in a Tooltip that names the shortcut. `SidebarRail` is `tabIndex={-1}`, so keyboard users toggle with the trigger or ⌘B.
- The mobile sheet traps focus, closes on Escape or the scrim, and returns focus to the trigger.
- Counts in `SidebarMenuBadge` need screen-reader text for the unit, and a disclosure parent needs `aria-expanded`.
- Under reduced motion the active mark jumps instead of gliding.
- ⌘ + B: Toggles the rail (Ctrl+B on Windows).
- Tab: Moves through rows, actions and the footer.
- Enter: Follows the focused link or runs the row.
- Space: Activates a button row.
- Esc: Closes the mobile sheet.

Known gaps (follow the system, not the gap):
- With `accent`, the active row is drawn as a Card White surface with hairline lift and a colored tick. DESIGN.md's Navigation section still describes a Rail Highlight fill; one of them should change.
- `isActive` sets `data-active` but not `aria-current`, so every call site must add it.
- Every `SidebarProvider` listens for ⌘B on `window` and writes the same `sidebar_state` cookie. Nested providers, like the demos on this page inside the docs shell, all toggle together. The provider never reads the cookie back.
- The screen-reader strings are hard-coded: the trigger and rail say Toggle Sidebar in title case, and the mobile sheet's description reads Switch apps and move between pages even in these docs.
- The 200ms width ease and the group label slide are plain CSS transitions with no `motion-reduce` variant; only the active mark respects reduced motion.
- `floating` uses `shadow-sm` with a ring and `inset` uses `shadow-sm` on `SidebarInset`, not the hairline lift. Neither variant is used in the product.
- `SidebarInput` isn't used: both product rails hand-roll the search field as a button with hairline lift and a ⌘K key, because it opens the command menu.
- `SidebarMenuSkeleton` picks its width with `Math.random()` in state, so a server-rendered skeleton hydrates with a different width than the client's.

API `SidebarProvider` (extends `<div>`):
- `defaultOpen?: boolean` = true. Initial desktop state when uncontrolled.
- `open?: boolean`. Controlled desktop state.
- `onOpenChange?: (open: boolean) => void`. Called when the desktop state changes.
- `className?: string`. Merged after `flex min-h-svh w-full`. Pass `min-h-0` to contain it in a box.

API `Sidebar` (extends `<div>` (the sidebar container)):
- `side?: "left" | "right"` = "left". Edge the rail sits on and the sheet slides from.
- `variant?: "sidebar" | "floating" | "inset"` = "sidebar". `sidebar` is flush with a hairline edge; `floating` insets the rail 8px with a ring; `inset` sets the content in a raised panel.
- `collapsible?: "offcanvas" | "icon" | "none"` = "offcanvas". How it collapses: slide away, shrink to a 3rem icon rail, or never.
- `accent?: string`. Color of the active-row mark, such as `var(--primary)`. Omit to draw no mark; active rows still paint their card.
- `className?: string`. Applied to the container (or the static rail when `none`).

API `SidebarTrigger` (extends Button):
- `onClick?: (event: MouseEvent) => void`. Runs before the toggle.

API `SidebarRail` (extends `<button>`):

API `SidebarInset` (extends `<main>`):

API `SidebarHeader, SidebarFooter` (extends `<div>`):

API `SidebarContent` (extends `<div>`):

API `SidebarSeparator` (extends Separator):

API `SidebarInput` (extends Input):

API `SidebarGroup` (extends `<div>`):

API `SidebarGroupLabel` (extends `<div>` (via `render`)):
- `isActive?: boolean` = false. Draws the mark on this label, for a folded group that holds the current page.
- `render?: ReactElement | (props, state) => ReactElement`. Render as a `<button>` for a collapsible group.

API `SidebarGroupAction` (extends `<button>` (via `render`)):
- `render?: ReactElement | (props, state) => ReactElement`. Render as another element.

API `SidebarGroupContent` (extends `<div>`):

API `SidebarMenu, SidebarMenuItem` (extends `<ul>`, `<li>`):

API `SidebarMenuButton` (extends `<button>` (via `render`)):
- `isActive?: boolean` = false. Marks the current page (`data-active`). Add `aria-current` yourself.
- `variant?: "default" | "outline"` = "default". `outline` adds a White Plane fill and a hairline ring.
- `size?: "default" | "sm" | "lg"` = "default". 28px at 13px (the nav row), 24px at 12px, or 48px.
- `tooltip?: string | TooltipContent props`. Shown on the right while collapsed to icons.
- `render?: ReactElement | (props, state) => ReactElement`. Render as `<Link href />` for navigation.

API `SidebarMenuAction` (extends `<button>` (via `render`)):
- `showOnHover?: boolean` = false. Hidden on desktop until the row is hovered or focused, or its menu is open.
- `render?: ReactElement | (props, state) => ReactElement`. Render as another element.

API `SidebarMenuBadge` (extends `<div>`):

API `SidebarMenuSkeleton` (extends `<div>`):
- `showIcon?: boolean` = false. Adds a 16px icon block.

API `SidebarMenuSub, SidebarMenuSubItem` (extends `<ul>`, `<li>`):

API `SidebarMenuSubButton` (extends `<a>` (via `render`)):
- `isActive?: boolean` = false. Marks the current page; its tick sits on the sub-menu line.
- `size?: "sm" | "md"` = "md". 13px on 28px, or 12px on 24px.
- `render?: ReactElement | (props, state) => ReactElement`. Render as `<Link href />` or a `<button>`.

API `useSidebar`:

### Navigation menu

- Level: Organism
- Category: Navigation
- Status: Experimental
- Import: `@oration/canon/components/navigation-menu`
- Exports: `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink`
- Docs: /design/components/navigation-menu

Navigation menu is a horizontal row of top-level links whose triggers open rich flyout panels, built on Base UI Navigation Menu. It's for site-level navigation on public, marketing-style pages, where a section needs a few described links. Oration's workspace doesn't use it: the app navigates with the Sidebar, and actions live in menus and toolbars. The mistake to avoid is treating it as a menu of commands; every item in it goes somewhere.

When to use:
- For the top bar of a public page such as a product site, a changelog or a help center.
- When a top-level section needs a panel of three to eight links, each with a one-line description.
- To mix flyout triggers with plain links (Pricing, Customers) in one row.

When not to use:
- For navigation inside the workspace. It is always the rail. Use /design/components/sidebar instead.
- For a list of actions on the current page or record. Use /design/components/dropdown-menu instead.
- For an editor's File, Edit and View commands. Use /design/components/menubar instead.
- For switching views of the same content. Use /design/components/tabs instead.
- For jumping to any page by name. Use /design/components/command instead.

Rules:
- Links, not commands: Every item in a navigation menu is a link to a page. If an item runs an action, it belongs in a dropdown menu or a toolbar.
- The One Filled Button Rule: A top bar may carry one filled call to action beside the menu, such as Book a demo. The triggers themselves stay ghost.

Anatomy:
- Trigger: `NavigationMenuTrigger`: a 36px ghost control at 14px medium with a 12px chevron. Open, it keeps a Well Gray fill at 50%.
- Chevron: Rotates 180° while its panel is open.
- Plain link: A `NavigationMenuLink` styled with `navigationMenuTriggerStyle()`, for sections without a panel.
- Popup: One shared popup and viewport, 10px corners on Popover White, 8px below the row. It resizes to each panel.
- Panel link: `NavigationMenuLink` inside `NavigationMenuContent`: 8px padding, Well Gray on hover and focus, an icon, a title and a description.

States:
- Rest: Transparent trigger, ink label.
- Hover: Well Gray fill over 150ms. Hovering opens the panel after 50ms.
- Focus visible: A 3px Focus Indigo ring at 50% and a 1px outline.
- Open: `data-popup-open`: Well Gray at 50%, chevron turned, panel shown. Moving to another trigger swaps panels inside the same popup.
- Active link: `active` sets `data-active`: Well Gray at 50%. Pair it with `aria-current="page"`.
- Disabled: 50% opacity and no pointer events.

Behavior:
- Hover or focus a trigger and press Enter, Space or Down to open its panel. The popup opens after `delay` (50ms) and closes `closeDelay` (50ms) after the pointer leaves.
- All panels render into one shared popup and viewport. Moving between triggers keeps the popup open and animates its size and position over 350ms.
- The popup enters from a 0.9 scale and fades; it exits over 150ms.
- Links don't close the popup by default. Pass `closeOnClick` for links that stay on the same page or route client-side.
- `align` on `NavigationMenu` aligns the popup to the start, center or end of the trigger. `value`, `defaultValue` and `onValueChange` control which item is open; `null` closes it.
- Escape closes the popup and returns focus to its trigger.

Do and don't:
- Do: Use it for a public site's sections: Product, Solutions, Pricing.
- Don't: Put commands in it. Edit, Export and Approve are actions for a menu or toolbar, not places to go.
- Do: Give each panel link a title and one line that says what's there.
- Don't: Fill a panel with a dozen bare links. If a section needs that many, give it a page.

Content:
- Triggers are one-word section names in sentence case: Product, Solutions, Resources.
- Panel link titles name the page; descriptions are one short sentence with no trailing call to action.
- Don't repeat the section name in each link: under Product, write Approvals, not Product approvals.

Accessibility:
- The root renders a `<nav>`. Give it an `aria-label` when the page has more than one navigation landmark.
- Triggers expose `aria-expanded` and control their panel. Panel links are plain anchors, so they announce and open like links.
- Mark the current page with `active` and `aria-current="page"` on its link.
- Hover opening is a convenience; everything works from the keyboard and on touch by tapping the trigger.
- Transitions aren't reduced for reduced-motion users; see known gaps.
- Tab: Moves into the row, then into an open panel's links.
- Enter: Opens the focused trigger's panel, or follows a link.
- Space: Opens the focused trigger's panel.
- ↓: Opens the panel and moves focus into it.
- ← + →: Moves between triggers and links in the row (roving focus).
- Esc: Closes the panel and focuses its trigger.

Known gaps (follow the system, not the gap):
- Nothing in `apps/web` imports it. The workspace has no top navigation, so treat it as experimental.
- Motion runs outside the system: panels and the popup move over 350ms on `cubic-bezier(0.22, 1, 0.36, 1)` and enter from a 0.9 scale, where DESIGN.md caps state changes at 320ms, uses the house ease and enters popovers from 0.97. Nothing is reduced for reduced-motion users.
- The popup draws its edge with `shadow` and `ring-1` instead of the overlay shadow and ring menus and popovers use.
- Triggers are 36px, not the 32px control height, and focus draws both a ring and an outline.
- `NavigationMenuContent` carries Radix-era classes (`data-[motion=…]`, `group-data-[viewport=false]`) that Base UI never sets, so those branches do nothing.
- `NavigationMenuIndicator` wraps Base UI's `NavigationMenu.Icon` (the trigger icon slot) and styles itself with Radix `data-[state]` attributes, so it isn't a working indicator. Base UI's `NavigationMenu.Arrow` isn't wrapped.
- `NavigationMenuPositioner` is exported, but `NavigationMenu` always renders its own, so `side` and `sideOffset` can't be changed from the root.

API `NavigationMenu` (extends Base UI `NavigationMenu.Root` (`<nav>`)):
- `align?: "start" | "center" | "end"` = "start". Aligns the popup to its trigger.
- `value?: any | null`. Controlled open item. `null` closes.
- `defaultValue?: any | null` = null. Uncontrolled initial open item.
- `onValueChange?: (value, eventDetails) => void`. Called when the open item changes.
- `delay?: number` = 50. Milliseconds before hover opens a panel.
- `closeDelay?: number` = 50. Milliseconds before leaving closes it.
- `orientation?: "horizontal" | "vertical"` = "horizontal". Arrow-key direction between triggers.

API `NavigationMenuList` (extends Base UI `NavigationMenu.List`):

API `NavigationMenuItem` (extends Base UI `NavigationMenu.Item`):
- `value?: any`. Identifies the item for controlled use. Generated if omitted.

API `NavigationMenuTrigger` (extends Base UI `NavigationMenu.Trigger` (`<button>`)):

API `NavigationMenuContent` (extends Base UI `NavigationMenu.Content`):

API `NavigationMenuLink` (extends Base UI `NavigationMenu.Link` (`<a>`)):
- `active?: boolean` = false. Marks the current page (`data-active`).
- `closeOnClick?: boolean` = false. Closes the popup when the link is clicked.
- `render?: ReactElement | (props, state) => ReactElement`. Render as `<Link href />` for client routing.

API `navigationMenuTriggerStyle`:

API `NavigationMenuPositioner` (extends Base UI `NavigationMenu.Positioner`):
- `side?: "top" | "bottom" | "left" | "right"` = "bottom". Side of the trigger.
- `sideOffset?: number` = 8. Gap from the trigger in px.
- `align?: "start" | "center" | "end"` = "start". Alignment to the trigger.
- `alignOffset?: number` = 0. Offset along the alignment axis.

API `NavigationMenuIndicator` (extends Base UI `NavigationMenu.Icon`):

### Menubar

- Level: Organism
- Category: Navigation
- Status: Experimental
- Import: `@oration/canon/components/menubar`
- Exports: `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`
- Docs: /design/components/menubar

Menubar is a desktop-style row of menus (File, Edit, View) for editors with more commands than a toolbar can hold. It's built on Base UI Menubar, and each menu reuses Dropdown menu, so items, checkboxes, radios, submenus and shortcuts behave the same way. Nothing in Oration uses it yet: the workspace's editors get by with toolbars and a single More menu. Reach for it only when an editor has several groups of commands that people will learn by heading; most screens want a toolbar.

When to use:
- For a document-style editor with many commands in familiar groups: a remittance template, an email template or a report layout.
- When the commands need keyboard shortcuts shown beside them and people expect to find them under File, Edit and View.
- For view options that are toggles or a single choice, as checkbox and radio items.

When not to use:
- For a few actions on a page or record. Show them as buttons, with the rest in one menu. Use /design/components/toolbar instead.
- For a single overflow menu behind a button. Use /design/components/dropdown-menu instead.
- For navigation between pages. Use /design/components/navigation-menu instead.
- For commands people search for by name. Use /design/components/command instead.
- For right-click actions on an object. Use /design/components/context-menu instead.

Rules:
- Headings people already know: Menus are named the way desktop apps name them: File, Edit, Insert, View, Help. Invent a heading only for a group with no conventional home.
- Destructive is a tint: A destructive item is red text on a 10% red highlight, set apart by a separator at the end of its menu, and named for what it removes.

Anatomy:
- Bar: `Menubar`: a 32px row with a hairline border, 10px corners and 3px padding.
- Trigger: `MenubarTrigger`: a 14px medium label; Well Gray on hover and while its menu is open.
- Menu: `MenubarContent`: Popover White, 10px corners, 4px padding, 8px below the bar and nudged 4px left.
- Item: `MenubarItem`: a 14px row with 8px corners; Menu Hover when highlighted.
- Shortcut: `MenubarShortcut`: right-aligned 12px Slate Meta keys.
- Indicator: Checkbox and radio items reserve 28px on the left for a check.
- Submenu: `MenubarSubTrigger` with a trailing chevron opens `MenubarSubContent` to the right.

States:
- Rest: Ink labels on the bar.
- Trigger hover: Well Gray fill. Once a menu is open, hovering another trigger opens it.
- Trigger open: `aria-expanded`: Well Gray fill while its menu shows.
- Item highlighted: Menu Hover fill under pointer or keyboard focus.
- Checked: A 16px check in the left gutter; radios show the same check.
- Disabled: 50% opacity, skipped by pointer; still announced.
- Destructive: Red text; highlighted, a 10% red tint (20% in dark).
- Submenu open: The sub-trigger keeps the Menu Hover fill.

Behavior:
- Click a trigger, or focus it and press Enter, Space or Down, to open its menu. While one menu is open, hovering or arrowing to another trigger switches menus.
- Focus moves between triggers with the arrow keys and loops at the ends (`loopFocus`, on by default).
- Menus are modal by default (`modal`): the page behind doesn't scroll and outside clicks close the menu first.
- Items close the menu when chosen. Checkbox and radio items toggle in place; control them with `checked` and `onCheckedChange`, or `value` and `onValueChange` on the radio group.
- Menus open in about 100ms with a fade, a 0.95 zoom and a short slide from the bar. Submenus fade and zoom both ways; top-level menus have no exit animation.
- Escape closes the open menu and returns focus to its trigger.

Do and don't:
- Do: Use a menubar when an editor has four or more groups of commands under familiar headings.
- Don't: Put two or three actions in a menubar. They're buttons; a bar of one-item menus hides them behind an extra click.
- Do: Show the shortcut beside every command that has one, in the same notation as the rest of the suite (⌘, ⇧, ↵).
- Don't: Invent shortcuts that clash with the browser or the suite, such as ⌘K or ⌘B.

Content:
- Headings are single words: File, Edit, View.
- Items start with a verb or name the setting: Export as PDF, Insert field, Show rulers.
- Name destructive items for what they remove: Cancel run, Delete template.

Accessibility:
- The bar has `role="menubar"` and each trigger is a `menuitem` with `aria-haspopup` and `aria-expanded`. Give the bar an `aria-label` that names what it edits.
- Only one trigger is in the tab order; arrows move between the rest (roving focus).
- Checkbox and radio items expose `menuitemcheckbox` and `menuitemradio` with `aria-checked`.
- A `MenubarLabel` must sit inside a `MenubarGroup` so it labels that group.
- Shortcuts are shown, not bound: wire the keys up yourself and keep them in sync with the label.
- Triggers draw no focus ring; see known gaps.
- Tab: Moves focus to the bar's current trigger, then out of the bar.
- ← + →: Moves between triggers, or between open menus.
- Enter: Opens the focused menu, or runs the highlighted item.
- Space: Opens the focused menu, or toggles a checkbox item.
- ↓ + ↑: Opens the menu, then moves through its items.
- →: Opens a submenu from its trigger.
- Esc: Closes the menu and focuses its trigger.

Known gaps (follow the system, not the gap):
- Nothing in `apps/web` imports it, so its styling hasn't met a real screen.
- `MenubarTrigger` is `outline-hidden` with no `focus-visible` style, so a keyboard user can't see which trigger is focused until a menu opens.
- The bar draws a CSS border, and triggers use `rounded-sm` with 2px vertical padding. DESIGN.md has no menubar, but controls elsewhere are 28 or 32px with 8px corners.
- `MenubarContent` inherits Dropdown menu's `w-(--anchor-width)`, so a menu is only as wide as `min-w-36` unless you set a width.
- Menus use `shadow-md` and `shadow-lg` with a ring, not the overlay shadow, open in 100ms rather than 160ms, and the top-level menu has no exit animation.
- `MenubarShortcut` letter-spaces its keys (`tracking-widest`), which Canon avoids elsewhere; Kbd is the shared key style.
- `MenubarLabel` is 14px medium ink, where Dropdown menu's label is 12px Slate Meta; the demos set it to match.

API `Menubar` (extends Base UI `Menubar` (`<div role="menubar">`)):
- `modal?: boolean` = true. Locks page scroll and outside interaction while a menu is open.
- `disabled?: boolean` = false. Disables every menu.
- `orientation?: "horizontal" | "vertical"` = "horizontal". Arrow-key direction between triggers.
- `loopFocus?: boolean` = true. Wraps focus from the last trigger to the first.

API `MenubarMenu` (extends Base UI `Menu.Root`):
- `open?: boolean`. Controlled open state.
- `onOpenChange?: (open, eventDetails) => void`. Called when it opens or closes.

API `MenubarTrigger` (extends Base UI `Menu.Trigger`):

API `MenubarContent` (extends Dropdown menu content (Base UI `Menu.Popup` and positioner)):
- `align?: "start" | "center" | "end"` = "start". Alignment to the trigger.
- `alignOffset?: number` = -4. Nudges the menu to line up with the bar's padding.
- `side?: "top" | "bottom" | "left" | "right"` = "bottom". Side of the trigger.
- `sideOffset?: number` = 8. Gap below the bar.
- `className?: string`. Set a width such as `w-56`; the default tracks the trigger.

API `MenubarItem` (extends Base UI `Menu.Item`):
- `variant?: "default" | "destructive"` = "default". Red text and tint for destructive commands.
- `inset?: boolean`. Indents the label 28px to line up with checkbox items.
- `disabled?: boolean` = false. Dims and skips the item.
- `onClick?: (event) => void`. Runs the command.

API `MenubarCheckboxItem` (extends Base UI `Menu.CheckboxItem`):
- `checked?: boolean`. Controlled state.
- `defaultChecked?: boolean`. Uncontrolled initial state.
- `onCheckedChange?: (checked: boolean, eventDetails) => void`. Called on toggle.
- `inset?: boolean`. Kept for parity; checkbox items are always inset.

API `MenubarRadioGroup` (extends Base UI `Menu.RadioGroup`):
- `value?: any`. Controlled value.
- `onValueChange?: (value, eventDetails) => void`. Called when the choice changes.

API `MenubarRadioItem` (extends Base UI `Menu.RadioItem`):
- `value: any`. The option's value.
- `inset?: boolean`. Kept for parity; radio items are always inset.

API `MenubarGroup, MenubarLabel` (extends Base UI `Menu.Group`, `Menu.GroupLabel`):
- `inset?: boolean`. Indents the label to line up with checkbox items.

API `MenubarSeparator` (extends Base UI `Menu.Separator`):

API `MenubarShortcut` (extends `<span>`):

API `MenubarSub, MenubarSubTrigger, MenubarSubContent` (extends Base UI `Menu.SubmenuRoot`, `Menu.SubmenuTrigger`, Dropdown menu content):
- `inset?: boolean`. On the trigger: indents the label.

API `MenubarPortal` (extends Base UI `Menu.Portal`):

### Data grid

- Level: Organism
- Category: Data display
- Status: Stable
- Import: `@oration/canon/components/data-grid`
- Exports: `DataGrid`, `DataGridColumn`
- Docs: /design/components/data-grid

Data grid is the record table at Attio density: companies, people, deals, lists, tables, runs, tools and conversations all render through it. It draws 32px sticky headers, 36px rows ruled in hairlines, right-aligned tabular numbers, pinned columns, resizable widths and row selection, and leaves sorting, filtering and cell content to you. The common mistake is treating it as a styled `<table>` for a handful of rows inside a card; that's a Table or Card table. Data grid is for a full-bleed list page where the grid is the view and scrolls on its own.

When to use:
- For the main list of a record type: Companies, People, Deals, a list or a table, full-bleed under the page toolbar.
- When rows can be selected for bulk actions, with the Action bar rising over the grid.
- When a row opens a record or a side panel and the open row needs to stay marked (`activeRowId`).
- When columns are wide or many, so the first column needs to stay pinned while the rest scroll sideways.
- For enrichment and AI columns whose cells resolve row by row.

When not to use:
- For a short, static table inside a report card or panel, such as a leaderboard. Use /design/components/table instead.
- For a list of keys, members or deliveries inside a settings section. Use /design/components/card-table instead.
- For pipeline stages you move cards between. Use /design/components/kanban instead.
- For a short list the user reorders by hand, such as sequence steps. Use /design/components/sortable-list instead.
- For a list of rows with one line of text each and no columns to compare. Use /design/components/item instead.

Rules:
- The Tabular Figures Rule: Every number that changes or gets compared is set in tabular figures, and numeric columns align right. `align: "right"` does both for the whole column, header included.
- The Scroll Edge Rule: Clipped content shows its edge. The last pinned column casts its edge shadow only once the grid scrolls sideways, so at rest the grid reads as one flat ledger.
- The Quiet Indigo Rule: Indigo in a grid means selection: a 6% tint on selected and active rows, the checked checkbox and the 1px resize rule. Never color a row, cell or column header to show a value.
- The Label-Beside-Color Rule: A status cell is a dot and a word, never a colored cell or a bare dot. A strong ICP fit can turn its bar green because the number and a screen-reader band travel with it.

Anatomy:
- Header row: 32px, White Plane, 13px medium Slate Meta, sticky to the top of the grid's own scroll area.
- Column icon: Optional 14px icon in Faint Slate before the header label, set with the column's `icon`.
- Resize handle: An 8px hit strip on each header's right edge that shows a 1px indigo rule on hover and drags the width down to `minWidth`.
- Row checkbox: A 40px sticky column when `selection` is passed. Checkboxes appear on row hover, on keyboard focus, or for every row once any row is selected.
- Pinned column: Columns with `pinned` stick left. The last one carries a hairline and, once the grid scrolls sideways, the pinned edge shadow.
- Numeric column: With `align: "right"`, header and cells align right and cells use tabular figures.

States:
- Rest: White Plane cells with hairline right and bottom rules. Row checkboxes are hidden until a row is hovered or anything is selected.
- Row hover: Every cell in the row fills Row Mist (`--surface`) over 100ms, and that row's checkbox fades in.
- Selected: A 6% indigo tint mixed into the plane on every cell, including the pinned and checkbox cells. All checkboxes stay visible.
- Active: The row whose id matches `activeRowId`, such as the record open in a side panel, takes the same 6% tint without a checked box.
- Indeterminate: The header checkbox shows a dash when some but not all rows are selected; checking it selects every row passed in `rows`.
- Scrolled sideways: `data-scrolled-x` is set on the grid and the last pinned column casts an 8px shadow over the columns sliding under it.
- Resizing: The handle's 1px indigo rule shows on hover, and the whole page takes the column-resize cursor while dragging.
- Empty: With no rows, headers stay in place and your `empty` node renders under them, pinned to the left edge.
- Loading: Not drawn by the grid. Render `SkeletonTable` through Data state until rows arrive, at the same row height.

Behavior:
- Widths start at each column's `width` (180px if omitted) and are then owned by the grid. Dragging a handle sets a width no smaller than `minWidth` (80px by default). Columns added later get their starting width; changing `width` on an existing column after mount has no effect.
- The table is `table-fixed` and `w-max`, with a filler column after the last one, so it always spans its container and grows past it when columns are wide.
- The grid is its own scroll container. Give it a bounded height, as list pages do with `flex-1 min-h-0` inside a full-height column, or the page scrolls instead and the header can't stick.
- Pinned columns stick at their cumulative left offset, after the 40px checkbox column when selection is on. The edge shadow switches on as soon as `scrollLeft` is above zero.
- Selection is controlled: pass a `Set` of row ids and `onSelectionChange`. The header checkbox selects or clears every row in `rows`, so pass the filtered rows, not the whole data set.
- `onRowClick` makes the whole row clickable. Clicks on the checkbox cell don't reach it; stop propagation on links and menus inside cells yourself, as the companies grid does.
- `density` sets cell height to 32, 36 or 44px. The header stays 32px.
- `footer` renders inside the scroll area after the table. Make it `sticky bottom-0 left-0` so counts and totals stay in view.
- `trailingHeader` adds a 160px column after the data columns, for an Add column control.
- Only colors transition. Nothing in the grid moves, so there is nothing to reduce for reduced motion; enrichment shimmer stops under it.

Do and don't:
- Do: Right-align amounts and counts with `align: "right"` so digits line up in tabular figures.
- Don't: Leave numbers left-aligned in proportional figures. Columns of money become hard to compare at a glance.
- Do: Say what an empty cell means in Faint Slate words: None, Scoring, No result.
- Don't: Leave cells blank or write N/A and null. A blank reads as still loading, and machine words read as broken.
- Do: Keep rows plain: Row Mist on hover, a 6% indigo tint when selected, and color only inside tags and status labels.
- Don't: Tint whole rows by stage or stripe them. The grid stops reading as one ledger, and color starts to carry meaning without a label.

Content:
- Column headers are one or two nouns in sentence case: AP spend, Invoices a month, Last remittance. No units in brackets; put the unit in the cell.
- The first column names the record and links to it. Keep it pinned.
- Empty values get a word in Faint Slate that says why: None when nothing exists, Scoring or Researching while it's being worked out, No result when enrichment found nothing.
- Dates in rows are short and absolute (Sep 25); relative times (2h ago) are for activity columns only.
- Footer counts use the record noun: 6 companies, then totals such as AP spend $61.2M.
- Machine strings such as invoice and run IDs are Geist Mono at 12px; names, amounts and dates stay in Geist Sans.

Accessibility:
- The grid renders a real `<table>` named by `label` (`aria-label`), with `scope="col"` headers and `aria-rowcount`, so screen readers announce rows and columns.
- It isn't an ARIA grid: there is no arrow-key cell navigation. Put a real link in the first cell so each row has a keyboard path, as the companies and people grids do; `onRowClick` alone is mouse-only.
- Row checkboxes are hidden with opacity, not removed, so they stay in the tab order and fade in on `focus-visible`.
- Every row checkbox is labelled Select row, and the header one Select all rows. Screen readers can't tell rows apart from the checkbox alone; see known gaps.
- The resize handle is `aria-hidden` and pointer-only. Keep default widths readable so nobody has to resize to read a column.
- Status cells pair the dot with text, and ICP bars carry a screen-reader band (ICP fit Strong), so nothing relies on color.
- Tab: Moves through the header checkbox, row checkboxes, links and buttons in cells, in reading order.
- Space: Toggles the focused checkbox.
- Enter: Opens the focused link in a cell.
- Shift + Tab: Moves back through the same controls.

Known gaps (follow the system, not the gap):
- Every row checkbox has the same name, Select row. There is no prop to name it after the record, so screen reader users hear a list of identical checkboxes.
- `onRowClick` is attached to the `<tr>` with no keyboard equivalent, and the resize handle is pointer-only. Grids stay usable only because product columns put a link in the first cell.
- Widths live in internal state. They can't be controlled, persisted per view or reset, and a changed `width` prop is ignored after the first render.
- Loading isn't part of the grid. Every list page wraps it in Data state with `SkeletonTable`, and the enrichment cell states (queued, running, found, no result, error) are rebuilt by the tables grid rather than offered here.
- The pinned edge shadow is a literal `oklch(0 0 0 / 0.18)` (0.6 in dark) rather than a token, unlike every other shadow in the system.
- DESIGN.md's color section pairs the 6% selected tint with a 22% inset indigo ring; the grid draws only the tint, which matches its own Data grid section.

API `DataGrid`:
- `columns: DataGridColumn<T>[]`. Columns in display order. See `DataGridColumn`.
- `rows: T[]`. The rows to render, already filtered and sorted. Select all works on these.
- `getRowId: (row: T) => string`. A stable id per row, used for keys and selection.
- `label: string`. Accessible name of the table, such as Companies.
- `selection?: Set<string>`. Selected row ids. Pass with `onSelectionChange` to show the checkbox column.
- `onSelectionChange?: (selection: Set<string>) => void`. Called with a new set when a checkbox changes.
- `onRowClick?: (row: T) => void`. Makes rows clickable with a pointer cursor. Mouse only; keep a link in the first cell.
- `activeRowId?: string | null`. Marks one row with the selected tint, such as the record open in a side panel.
- `density?: "compact" | "default" | "comfortable"` = "default". Cell height: 32, 36 or 44px.
- `trailingHeader?: ReactNode`. Content for a 160px header cell after the last column, usually an Add column button.
- `footer?: ReactNode`. Rendered inside the scroll area after the table. Make it sticky to the bottom and left.
- `empty?: ReactNode`. Shown under the headers when `rows` is empty.
- `rowClassName?: (row: T) => string | undefined`. Classes for a row's `<tr>`. Cells paint their own background, so target them with `[&>td]:`.
- `className?: string`. Classes for the scroll container. Give it a bounded height (`flex-1`, `h-96`).

API `DataGridColumn`:
- `id: string`. Unique per grid; keys the column and its width.
- `header: ReactNode`. The header label. Truncates to one line.
- `icon?: ReactNode`. A lucide icon before the label, sized to 14px.
- `width?: number` = 180. Starting width in pixels.
- `minWidth?: number` = 80. Narrowest width the resize handle allows.
- `align?: "left" | "right"` = "left". `right` aligns header and cells right and sets tabular figures.
- `pinned?: boolean` = false. Sticks the column to the left. Pin leading columns only, in order.
- `headerAccessory?: ReactNode`. Pushed to the right end of the header cell, for a sort or column menu button.
- `cell: (row: T, index: number) => ReactNode`. Renders a cell. Content sits in a flex row with a 6px gap; truncate long text.
- `cellClassName?: string`. Classes added to every `<td>` in the column.

### Table

- Level: Organism
- Category: Data display
- Status: Stable
- Import: `@oration/canon/components/table`
- Exports: `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableFooter`, `TableCaption`
- Docs: /design/components/table

Table is a thin, semantic wrapper over `<table>` for small, static data sets: a leaderboard in a report panel, the deals behind a pipeline chart, a cohort breakdown, a list of reports. It gives you a horizontally scrolling container, hairline row rules and a hover fill, and nothing else: no selection, pinning, resize or sticky header. The thing people get wrong is shipping the defaults. Out of the box the header is 40px Graphite Ink at 14px; in Canon a table inside a card reads at 13px with 32px Slate Meta headers, so almost every product table sets those itself.

When to use:
- For a short table inside a report card, panel or sheet: a leaderboard, the top suppliers by AP spend, the deals behind a chart.
- For read-only rows where the columns are worth comparing, with numbers right-aligned.
- For an index of a few dozen items with one link per row and a row menu, such as reports or skills.
- When you need a footer row for totals or a caption that explains the data.

When not to use:
- For a record list page with selection, pinned columns, resize or bulk actions. Use /design/components/data-grid instead.
- For a table that is the whole content of a settings section, such as API keys or members. Use /design/components/card-table instead.
- For two-column label and value pairs about one record. Use /design/components/meta instead.
- For rows with a title, description and trailing action but no columns to compare. Use /design/components/item instead.
- For a trend over time. Show the shape as a chart and put the table under it only if people need the exact figures. Use /design/components/chart instead.

Rules:
- The Tabular Figures Rule: Counts, amounts, rates and durations are set in tabular figures, and numeric columns align right, header included. Table does neither for you: add `text-right tabular-nums` to the head and every cell in the column.
- The Thirteen-Fourteen Rule: Rows in a card or panel are dense UI at 13px, and headers are meta at 12px. The defaults are 14px, so pass `text-[13px]` to `Table` and set the head size yourself.
- The Tint Well Rule: A table inside a card is part of the card, not a card of its own. Don't wrap it in a second bordered or shadowed box; let the card's padding or a hairline divide it.

Anatomy:
- Container: A `relative w-full overflow-x-auto` div around the `<table>`, so wide tables scroll sideways inside their card.
- Header row: `TableHeader` and `TableHead`. 40px by default; in cards set it to 32px, 12px, regular weight, Slate Meta.
- Row: `TableRow` with a hairline bottom rule. The last row in the body drops its rule.
- Numeric cell: A `TableCell` with `text-right tabular-nums`, matched by the same classes on its head.
- Footer: `TableFooter`, a Well Gray band at 50% with a top hairline and medium weight, for totals.

States:
- Rest: Rows on the card or plane, ruled by hairlines.
- Row hover: Well Gray at 50% under the whole row, 150ms. Opt out on header rows with `hover:bg-transparent`.
- Menu open: While a row's menu trigger has `aria-expanded`, the row keeps the hover fill so you can see which row the menu belongs to.
- Selected: Set `data-state="selected"` on a row to fill it Well Gray, for the current user in a leaderboard. It is a mark, not a selection model.
- Loading: Not drawn by Table. Render `SkeletonTable` through Data state in its place.
- Empty: Not drawn by Table. Render Empty state instead of the table, or a single spanning row for a filtered list.

Behavior:
- `Table` renders the container div and the `<table>`; its `className` goes on the table, not the container. There is no prop for the container.
- Cells are `whitespace-nowrap`. For a column that should truncate, give its cell `max-w-0 w-full` and a `truncate` child, as the reports index does.
- The table is `caption-bottom`; `TableCaption` sits under the rows at 14px Slate Meta.
- `TableHead` and `TableCell` drop their right padding when they hold a checkbox, so a checkbox column hugs the edge.
- Hide low-priority columns on narrow screens with `max-md:hidden` on the head and each cell, as the reports and customers tables do, before relying on sideways scroll.
- Only the row fill transitions (150ms). Nothing moves.

Do and don't:
- Do: In a card, set rows to 13px and headers to 32px, 12px Slate Meta, and right-align numbers in tabular figures.
- Don't: Ship the defaults next to dense UI: 40px, 14px headers in full ink, with numbers left-aligned.
- Do: Put one real link in the first cell of each row, and keep row actions in a labelled menu at the end.
- Don't: Make the `<tr>` clickable with `onClick` and nothing else. The row can't be reached with Tab and doesn't announce as a link.
- Do: Keep Table for a few dozen read-only rows inside a card.
- Don't: Grow it into a list page with checkboxes and sticky headers. That is Data grid, and it already solves pinning, selection and bulk actions.

Content:
- Headers are short nouns in sentence case: Agent, Handled, AHT, Close date. Spell out an abbreviation in the page or an Info tip the first time it appears.
- Put units in the cell, not the header: 4m 12s, 92%, $18,240.00.
- The header of an actions column is screen-reader text only: `<span className="sr-only">Actions</span>`.
- Footer rows start with Total and use the same units and precision as the column above.
- When a value is missing, write why in Slate Meta (Not scheduled, No description) rather than leaving it blank.

Accessibility:
- It is a native table, so rows and columns are announced with no ARIA. Name it: pass `aria-label` or render a `TableCaption`, or point `aria-labelledby` at the card title.
- `TableHead` renders `<th>` without a `scope`. Simple one-row headers are read correctly anyway; add `scope="col"` when a table has row headers too.
- Give each row's menu trigger a name that includes the row, such as Options for Monday containment review, and a tooltip.
- Don't hide a column's only link in a hidden-on-mobile column; the first column must always carry the row's link.
- The selected fill is a Well Gray tint only. Say who the row is in text as well, as the leaderboard does with You.
- Tab: Moves through links and buttons in the cells, row by row.
- Enter: Follows the focused link.
- Space: Opens the focused row menu or toggles a checkbox.

Known gaps (follow the system, not the gap):
- The defaults disagree with DESIGN.md's tables: headers are 40px, 14px medium Graphite Ink instead of 32px Slate Meta; rows are 14px instead of Body Dense 13px; row hover is Well Gray at 50% instead of Row Mist; selected is Well Gray instead of the 6% indigo tint. `h-8 text-xs font-normal text-muted-foreground` is repeated on more than 30 `TableHead`s in the product.
- Seven product tables pass `className="text-13"`. Table merges classes with the `cn` package, which reads `text-13` as a color, so `text-sm` is kept and wins in the stylesheet: those tables still render at 14px. Use `text-[13px]`.
- Numeric alignment isn't built in. There is no `align` prop, so every numeric column repeats `text-right` on the head and `text-right tabular-nums` on each cell.
- `TableHead` renders `<th>` with no `scope`, and there's no prop for the scroll container, so it can't be named, given a max height or a sticky header.
- Selection uses Radix's `data-state="selected"`, while Data grid uses `data-selected`. The file is also marked `"use client"` though it has no client code.

API `Table` (extends `<table>`):
- `className?: string`. Merged after `w-full caption-bottom text-sm`. Pass `text-[13px]` for dense tables, `table-fixed` or a `min-w-*` for wide ones.

API `TableHeader` (extends `<thead>`):

API `TableBody` (extends `<tbody>`):

API `TableFooter` (extends `<tfoot>`):

API `TableRow` (extends `<tr>`):
- `data-state?: "selected"`. Fills the row with Well Gray.

API `TableHead` (extends `<th>`):
- `className?: string`. Cards pass `h-8 text-xs font-normal text-muted-foreground`; numeric columns add `text-right`.

API `TableCell` (extends `<td>`):
- `className?: string`. Numeric cells add `text-right tabular-nums`; truncating cells add `max-w-0 w-full`.

API `TableCaption` (extends `<caption>`):

### Card table

- Level: Organism
- Category: Data display
- Status: Beta
- Import: `@oration/canon/components/card-table`
- Exports: `CardTable`, `Th`, `Td`, `CardTableEmpty`
- Docs: /design/components/card-table

Card table is a table that is its own card: a 12px-corner Card White surface with hairline lift, 36px Slate Meta headers, 48px rows on hairline rules and an empty row. It is the table of every settings page in Oration (members, API keys, webhooks, disposition codes), where the table is the content of a section rather than a block inside a bigger card. The thing to get right is placement: it already is the card, so it never goes inside another one.

When to use:
- For the main table of a settings section: members, API keys, webhooks, approval thresholds.
- For editable rows where each cell holds an input, a select or a switch.
- For a short list of records with a status and a row menu, where selection and sorting aren't needed.
- When the table needs a friendly empty row that keeps its headers visible.

When not to use:
- For a table inside a card that already has a title and other content. Use the plain table so you don't nest cards. Use /design/components/table instead.
- For a record list with selection, pinned columns, resize or bulk actions. Use /design/components/data-grid instead.
- For a list of rows with a title, description and a trailing action but no columns. Use /design/components/item instead.
- For label and value pairs that describe one record. Use /design/components/meta instead.

Rules:
- The Tint Well Rule: Card table is a card. Don't put it inside another card or panel; set it directly in the settings section, with the section's title and actions above it.
- The Tabular Figures Rule: Counts, amounts and dates that get compared are set in `tabular-nums`, and numeric columns align right, header included.
- The Machine Mono Rule: Keys, tokens and IDs in a cell are Geist Mono at 12px. Names, dates and roles stay in Geist Sans.

Anatomy:
- Card: A Card White surface with 12px corners and hairline lift. Clips its corners and scrolls sideways below `minWidth`.
- Header cell: `Th`: 36px, 16px side padding, 12px medium Slate Meta, `scope="col"`, a hairline below.
- Body cell: `Td`: 48px tall, 16px side padding, 13px, vertically centered, a hairline below.
- Last row: The last body row drops its rule so the card's edge closes the table.

States:
- Rest: Rows on Card White, ruled by hairlines. Rows have no hover fill.
- Editing: Inputs and selects sit in cells at 32px with `py-2` on the cell, so the row grows to fit.
- Empty: `CardTableEmpty` spans the columns with one row; set its height and centering, and say why it's empty.
- Overflow: Below `minWidth` (36rem by default) the table scrolls sideways inside the card.
- Loading: Not drawn. Render a skeleton or Data state in its place.

Behavior:
- `CardTable` renders the card, a scroll container and a `<table>`; you write `<thead>`, `<tbody>` and `<tr>` yourself and fill them with `Th` and `Td`.
- `label` names the table with `aria-label`. It isn't drawn; put the visible title in the section header.
- `minWidth` sets the table's minimum width. Narrower than that, the table scrolls sideways inside the card instead of squeezing its columns.
- The table uses separate borders, so rules are drawn on cells and the last body row's cells drop theirs.
- Nothing moves or transitions.

Do and don't:
- Do: Set the card table straight into the settings section, under the section title.
- Don't: Wrap it in another card with its own title. That's a card in a card, with two edges and doubled padding.
- Do: Keep the headers and say in an empty row why there's nothing yet and what to do.
- Don't: Render a header with no rows. It reads as broken or still loading.

Content:
- Headers are short sentence-case nouns: Name, Last used, Amount over.
- An actions column's header is screen-reader text only: Actions or Remove.
- Empty rows say what's missing and what happens next: No webhooks yet. Add an endpoint to send payment events.
- Write "Never" or "Not used yet" for a missing date rather than leaving a blank or a dash.
- Masked keys keep the prefix and last four: `sk_live_…4f2a`.

Accessibility:
- It is a native table with `aria-label` from `label`, and `Th` sets `scope="col"`, so screen readers announce headers with each cell.
- Give every input in a cell its own `aria-label` that includes the row, such as Threshold 2 amount.
- Row menu and remove buttons are icon buttons: name them after the row and add a tooltip.
- The empty row is a real row, so it's read in the table; keep its message short.
- Horizontal overflow scrolls with a trackpad or Shift and the wheel; nothing in the card is focusable just to scroll, so keep the first column meaningful at narrow widths.
- Tab: Moves through inputs, links and buttons in reading order.
- Enter: Activates the focused button or link.

Known gaps (follow the system, not the gap):
- The only importer is `settings-kit.tsx`, which re-exports it as `SettingsTable` and `SettingsTableEmpty`; 19 settings files use those names, so a search for `CardTable` finds almost nothing.
- `CardTableEmpty` has no default height, centering or color. Every call site sets `h-24 text-center text-muted-foreground` or similar.
- There's no numeric alignment option and no shared base with Table: headers here are 36px 12px medium, Table's product convention is 32px 12px regular, and both differ from Data grid's 32px 13px medium.
- `label` only feeds `aria-label`. There's no caption or title slot, so the visible section title isn't tied to the table unless you wire `aria-labelledby` yourself, which `CardTable` doesn't accept.
- The scroll container shows no edge fade when columns are clipped, unlike the Scroll Edge Rule for tab rows and pinned grid columns.

API `CardTable`:
- `label: string`. Accessible name of the table.
- `children: React.ReactNode`. `<thead>` and `<tbody>`.
- `minWidth?: string` = "36rem". Minimum table width before it scrolls sideways.
- `className?: string`. Applied to the card.

API `Th` (extends `<th>`):
- `className?: string`. Widths such as `w-40`, or `text-right` for numbers.

API `Td` (extends `<td>`):
- `className?: string`. `py-2` around inputs, `text-right tabular-nums` for numbers, `font-mono text-xs` for keys.

API `CardTableEmpty`:
- `colSpan: number`. The number of columns to span.
- `children: React.ReactNode`. The message, and an action if there is one.
- `className?: string`. Applied to the cell. Set a height and `text-center`.

### Kanban

- Level: Organism
- Category: Data display
- Status: Beta
- Import: `@oration/canon/components/kanban`
- Exports: `Kanban`, `KanbanItems`
- Docs: /design/components/kanban

Kanban is a board of draggable cards in Well Gray columns, built on dnd-kit. It's the board view of deals and tickets in Oration, and the right shape for any queue where the column is the record's stage. It owns drag, drop, reordering and the drag overlay; you render the column header, the cards, the footer and the empty column. The thing people get wrong is the card: the whole card is the drag handle, so it should open its record through one stretched link, not a row of buttons.

When to use:
- For records that move through stages, where the stage is the column: supplier onboarding, invoice exceptions, deals, tickets.
- As the board alternative to a list view of the same records, with the same filters.
- When people reorder work by priority inside a stage as well as moving it between stages.
- For up to a few dozen cards per column; past that, a grid with a stage filter reads faster.

When not to use:
- For a dense record list with many fields to compare. Use /design/components/data-grid instead.
- For reordering a single list, such as statuses or attributes. Use /design/components/sortable-list instead.
- For showing progress through stages on one record. Use /design/components/stepper instead.
- For a dashboard of unrelated cards. That's the card mosaic Canon refuses.

Rules:
- The Option Hue Rule: A stage column's header may carry the stage as a Tag in its option hue. The column itself stays Well Gray; never tint a whole column or give cards colored edges.
- The Hairline-and-Lift Rule: Cards are Card White with hairline lift and 12px corners, deepening to the hover lift on hover and while dragged. No borders.
- The Tabular Figures Rule: Column counts and totals and the amounts on cards are tabular, so they don't jitter as cards move.

Anatomy:
- Column: A 288px `<section>` with 12px corners in Well Gray at 60% (40% in dark), and a scrolling body with 8px gaps.
- Column header: From `renderColumnHeader`: the stage tag, a count and a total, in 12px Slate Meta tabular figures.
- Card: From `renderItem`, wrapped in a focusable drag handle with a 12px focus ring.
- Placeholder: The card's slot while it's dragged, at 40% opacity, showing where it will land.
- Column footer: From `renderColumnFooter`: usually a ghost add button.
- Drag overlay: A copy of the card under the pointer (`overlay: true`), tilted 1.5° with a large shadow.

States:
- Rest: Cards with hairline lift on the column.
- Hover: Cards deepen to the hover lift over 150ms (set in your card).
- Focus visible: A 3px Focus Indigo ring at 40% around the card wrapper.
- Dragging: The slot drops to 40% opacity, the overlay follows the pointer, and other cards slide aside.
- Drop target: The column under the card fills Well Gray at 100% over 150ms.
- Dropped: The overlay settles into the slot over 200ms on the house ease-out.
- Empty column: From `renderColumnEmpty`: a dashed Firm Hairline box with a line of Slate Meta.

Behavior:
- The board is controlled. `items` maps column ids to arrays; every move calls `onItemsChange` with the next map, and you store it.
- A drag starts after the pointer moves 4px, so a click on a card still opens it.
- Moving across columns updates `items` while dragging, so the card's slot follows the pointer. On drop, `onItemMoved(item, from, to)` fires once if the column changed; reorders within a column only call `onItemsChange`.
- From the keyboard, focus a card and press Space or Enter to pick it up, the arrow keys to move it within and across columns, Space or Enter to drop, and Escape to cancel.
- Collision uses the closest corners, so a card dropped over an empty column lands in it.
- Columns are 288px by default; pass `columnClassName` to change the width. The board scrolls sideways when the columns don't fit, and each column scrolls on its own.

Do and don't:
- Do: Keep columns Well Gray and show the stage as a Tag in the header, with a count and a total.
- Don't: Tint whole columns in the stage hue, uppercase the header and add colored left borders to cards.
- Do: Give each card one stretched link to its record, with `draggable={false}` so the link doesn't start a native drag.
- Don't: Pack a card with buttons. Every control inside the drag handle competes with dragging and clutters the tab order.

Content:
- Column headers use the stage's name exactly as it appears on the record: W-9 received, not W9 Rcvd.
- Card titles are the record's name; one line of meta below it (owner, amount, reason).
- Empty columns say what belongs there or what to do: Drag a supplier here, No resolved exceptions this week.
- Confirm a move in a toast that names the record and its new stage.

Accessibility:
- Each card wrapper is a focusable `role="button"` with `aria-roledescription="sortable"` and instructions from dnd-kit, so it can be picked up from the keyboard.
- dnd-kit announces pick up, move and drop in a live region. The board doesn't pass custom announcements, so they read item ids, not names; see known gaps.
- Put the record link on the card's title and stretch it over the card. Keep other controls out of the card.
- Columns are `<section>` elements without a name. Put the stage name in the header as text, not only as color.
- Every move must also be possible without dragging: put the stage on the record page or in a menu.
- Tab: Moves between cards, links and column buttons.
- Space: Picks up the focused card, or drops it.
- Enter: Picks up or drops the focused card.
- ↑ + ↓: Moves the card within its column while held.
- ← + →: Moves the card to the neighboring column while held.
- Esc: Cancels the drag.

Known gaps (follow the system, not the gap):
- Pressing Escape after dragging a card into another column leaves it there: the move was already committed through `onItemsChange` during the drag, `onDragCancel` doesn't restore it, and `onItemMoved` never fires.
- Screen-reader announcements are dnd-kit's defaults, which read ids such as Picked up draggable item s4. There's no prop to name items.
- The whole card is the drag handle (`role="button"`), so links and buttons inside it are nested interactive content. Deal cards put their link inside it.
- The drag overlay tilts 1.5° with `shadow-lg`, where DESIGN.md says a dragged card takes the hover lift. Neither the tilt nor the 200ms drop animation is reduced for reduced-motion users.
- Columns are unnamed `<section>` elements, and their width is fixed at 288px unless every caller passes `columnClassName`.

API `Kanban`:
- `columns: C[] (C extends { id: string })`. Columns in order.
- `items: KanbanItems<T>`. Items per column id, in order.
- `getItemId: (item: T) => string`. A stable id for each item.
- `onItemsChange: (items: KanbanItems<T>) => void`. Called with the next map on every move.
- `onItemMoved?: (item: T, fromColumn: string, toColumn: string) => void`. Called once on drop when an item changed columns.
- `renderItem: (item: T, state: { overlay: boolean }) => ReactNode`. The card. `overlay` is true for the copy under the pointer.
- `renderColumnHeader: (column: C, items: T[]) => ReactNode`. The column's header.
- `renderColumnFooter?: (column: C, items: T[]) => ReactNode`. Below the cards, such as an add button.
- `renderColumnEmpty?: (column: C) => ReactNode`. Shown when a column has no items.
- `className?: string`. Applied to the board's scrolling row.
- `columnClassName?: string`. Applied to every column, such as a width.

API `KanbanItems`:

### Sortable list

- Level: Organism
- Category: Editors
- Status: Stable
- Import: `@oration/canon/components/sortable-list`
- Exports: `SortableList`
- Docs: /design/components/sortable-list

Sortable list is a vertical list that people reorder by dragging a handle or with the keyboard, built on dnd-kit. In Oration it orders the things whose order changes behavior: ticket statuses in a workflow, custom attributes on a form, an approval chain. It hands each row a ready-made handle and leaves the row's look to you. The mistake is making a list sortable when its order means nothing; if nothing reads the order, don't offer the drag.

When to use:
- When the order is a setting: approval steps, workflow statuses, the fields on a form, fallback rules.
- For short lists, up to about twenty rows, that fit on screen while dragging.
- For rows that are also editable, such as an input with a remove button, where only the handle starts a drag.

When not to use:
- For moving records between stages. Use /design/components/kanban instead.
- For sorting a table by a column. That's a sort control, not a drag. Use /design/components/data-grid instead.
- For a list whose order is alphabetical or by date. Sort it for people instead.
- For choosing a few items from many. Use /design/components/checkbox instead.

Rules:
- Show the order that matters: When the position decides behavior, show it: number the rows or say first, then in the description, so the result of a drag is readable.
- The Hairline-and-Lift Rule: A row being dragged lifts with the hover shadow on a 10px corner. Rows at rest stay flat on their card, split by hairlines.

Anatomy:
- List: `SortableList` renders a `<ul>`. Style it with `className`: a card with `divide-y`, or a gap between free-standing rows.
- Handle: A 24px button with a 14px grip in Faint Slate. Only the handle starts a drag.
- Row content: Whatever `renderItem` returns, with the handle placed where you put `{handle}`.
- Dragged row: The row itself moves (no overlay), raised above its neighbors. Lift it with `dragging`.

States:
- Rest: Handle in Faint Slate with a grab cursor.
- Handle hover: Well Gray fill and ink grip.
- Handle focus visible: A 3px Focus Indigo ring at 40%.
- Dragging: `dragging` is true for the moving row: give it a surface and the hover lift. The cursor turns to grabbing and other rows slide aside.
- Keyboard lifted: After Space on the handle, the row moves one slot per arrow key until it's dropped.

Behavior:
- The list is controlled. On drop, `onReorder` gets the reordered array; store it. Dropping in place does nothing.
- A pointer drag starts after 4px of movement, so a click on the handle doesn't start one.
- Movement is locked to the vertical axis, and the row snaps to the nearest slot by its center.
- `renderItem` receives `handle` (place it in the row), `dragging` and `index` (for numbering).
- There is no drag overlay: the row itself translates, with dnd-kit's slide transition on its neighbors.

Do and don't:
- Do: Number the rows when the order decides who approves first.
- Don't: Leave a meaningful order unlabeled. People can drag, but can't tell what the drag changed.
- Do: Put inputs and buttons beside the handle and keep the handle the only drag target.
- Don't: Make the whole row draggable when it holds inputs. Selecting text starts a drag.

Content:
- The section description says what the order does: Invoices go to each approver in this order.
- Name remove buttons after the row: Remove Priya Raman, Remove Cost center.
- Confirm a reorder that changes behavior in a toast that states the new order.

Accessibility:
- Each handle is a real `<button>` with dnd-kit's `aria-roledescription="sortable"` and instructions, so it can be picked up from the keyboard.
- Every handle is named Drag to reorder and there's no way to change it, so screen readers hear the same name on every row; see known gaps.
- dnd-kit announces pick up, move and drop with item ids, not names.
- Dragging isn't the only way to reorder for keyboard users, but pointer users without fine control have no Move up or Move down alternative unless you add one.
- Rows are `<li>` items in a `<ul>`, so the count is announced.
- Tab: Moves to the next handle or control.
- Space: Picks up the row, or drops it.
- Enter: Picks up or drops the row.
- ↑ + ↓: Moves the lifted row one slot.
- Esc: Cancels and puts the row back.

Known gaps (follow the system, not the gap):
- The handle's `aria-label` is fixed at Drag to reorder. It can't be named after its row, so a screen reader hears identical buttons.
- Announcements are dnd-kit's defaults and read row ids, not names.
- There's no single-pointer alternative to dragging (such as Move up and Move down in a row menu), which WCAG 2.5.7 asks for.
- The neighbors' slide transition and the dragged row's movement aren't reduced for reduced-motion users.
- There's no way to disable sorting for one row, such as a fixed first status.

API `SortableList`:
- `items: T[]`. Rows in order.
- `getId: (item: T) => string`. A stable id per row.
- `onReorder: (items: T[]) => void`. Called with the new order on drop.
- `renderItem: (item: T, state: { handle: ReactNode; dragging: boolean; index: number }) => ReactNode`. Renders a row. Place `handle` inside it.
- `className?: string`. Applied to the `<ul>`, merged after `flex flex-col`.

### Action bar

- Level: Organism
- Category: Actions
- Status: Beta
- Import: `@oration/canon/components/action-bar`
- Exports: `ActionBar`
- Docs: /design/components/action-bar

Action bar is the floating toolbar that rises from the bottom of a list or grid while rows are selected. It says how many records are selected, offers the two to four bulk actions that apply to all of them, and clears the selection from its trailing close button. It is absolutely positioned against its nearest positioned ancestor, so the common mistake is mounting it in a container without `relative`, where it floats to the bottom of the page instead of the list.

When to use:
- When one or more rows in a data grid, table or list are selected and the same action can apply to all of them: Approve, Export, Add to payment run.
- To show the selection count while the selection is off screen, so people can scroll and keep selecting.
- To group bulk actions that would otherwise crowd the page header, with overflow in a More menu.
- As the one place selection can be cleared in a single click, beside the actions it affects.

When not to use:
- For unsaved form changes with Discard and Save. That bar has a different job and keyboard shortcut. Use /design/components/save-bar instead.
- For actions on selected text inside an editor or a message. Use /design/components/selection-actions instead.
- For actions that are always available regardless of selection, such as filters, sort and view options. Use /design/components/toolbar instead.
- For a single record's actions. Put them in a row menu or the record header. Use /design/components/dropdown-menu instead.
- To confirm a destructive bulk action. The bar starts it; the confirmation lives in a dialog. Use /design/components/confirm-dialog instead.

Rules:
- The One Filled Button Rule: Actions inside the bar are `ghost` at `sm`. The bar is already the most elevated thing on the screen; a filled button inside it competes with the page's own primary action.
- The Quiet Indigo Rule: Selection is one of the few places indigo is spent: selected rows take the 6% indigo tint. The bar itself stays Popover White with ink text and never takes an indigo fill.
- Destructive is a tint: A destructive bulk action is a ghost button with Signal Red text, last before the close button, and it opens a confirmation instead of acting immediately.

Anatomy:
- Count: `{count} {noun}` in 13px medium tabular figures, so the width stays steady as the number changes.
- Separator: A 20px hairline (`bg-border`) between the count, the actions and the close button.
- Actions: Your `children`: ghost `sm` buttons, dropdown triggers or other compact controls, 4px apart.
- Clear selection: A ghost `icon-sm` button with an X and `aria-label="Clear selection"` that calls `onClear`.
- Surface: Popover White, 12px container corners, 6px padding and the floating bar shadow (`shadow-popover`), centered 20px above the bottom of its container.

States:
- Hidden: While `count` is 0 nothing renders, so the bar adds no DOM and no tab stops.
- Entering: When `count` goes above 0 the bar fades in and rises from 12px below at a 0.98 scale on a 300ms spring with no bounce.
- Shown: Full opacity at rest. The count updates in place as rows are added or removed; the bar does not re-animate.
- Exiting: When `count` returns to 0 it fades and drops 8px at a 0.98 scale over 140ms, faster than it entered.
- Action hover and focus: Each action is a Button, so it takes the ghost hover fill and the indigo focus ring.
- Menu open: A dropdown trigger inside the bar keeps its hover fill while its menu is open. Open menus upward with `side="top"` so they stay in view.

Behavior:
- Visibility is driven entirely by `count`. Pass the size of your selection; there is no `open` prop.
- The bar is `absolute bottom-5 left-1/2 -translate-x-1/2 z-40`. Give the scrolling list's wrapper `relative` and enough bottom padding (about 72px) that the last row can scroll clear of the bar.
- `pointer-events-auto` is set on the bar, so it stays clickable inside a `pointer-events-none` overlay layer.
- The close button only calls `onClear`. Clearing the selection is your job, and so is clearing it after a bulk action finishes.
- Enter and exit run through Motion's `AnimatePresence`. The component doesn't read `prefers-reduced-motion` itself; the app-wide `MotionConfig reducedMotion="user"` drops the rise and scale and keeps the fade.
- Actions are your own components, so they can open a menu, a dialog or a confirm. Dropdown menus portal to the body and are not clipped by the list.

Do and don't:
- Do: Use ghost `sm` buttons for every action in the bar.
- Don't: Fill the actions. Three primary buttons in a floating surface outshout the page they act on.
- Do: Keep two or three direct actions and move the rest into a More menu.
- Don't: Line up every bulk action. The bar grows past the list and gets clipped on narrow screens.

Content:
- Name what is selected through `noun`: 12 invoices selected, not 12 selected when the list mixes kinds of record.
- Handle the singular yourself. `noun` is printed as given, so pass `invoice selected` when `count` is 1.
- Action labels are short verbs, often without the object, since the count already names it: Approve, Export, Archive.
- After a bulk action, confirm with a toast that repeats the count and the outcome: 8 invoices approved.
- For a destructive action, put the count in the confirm dialog title: Archive 3 suppliers?

Accessibility:
- The bar is `role="toolbar"` with `aria-label="Bulk actions"`. Each child is a separate tab stop; there is no arrow-key roving between actions.
- Nothing announces the bar when it appears. The selected rows' checkboxes already announce their checked state, so people learn about the selection from there.
- Clear selection is an icon-only button with an accessible name. It has no tooltip.
- Mark icons inside actions `aria-hidden="true"`; the labels name the actions.
- Make sure the bar does not cover the focused row. Bottom padding on the list keeps the last row reachable.
- Under reduced motion the bar fades in place without rising. Keep its appearance obvious without the animation.
- Tab: Moves through the actions in order, then the clear button. The bar sits where it is mounted in the DOM, usually after the list.
- Enter: Runs the focused action.
- Space: Runs the focused action.

Known gaps (follow the system, not the gap):
- No reduced-motion handling of its own. The app-wide `MotionConfig` drops the rise and scale, but the 300ms spring isn't one of the three tiers.
- The bar is `role="toolbar"` but has no roving focus or arrow-key navigation, which the toolbar pattern implies.
- The clear button has an `aria-label` but no tooltip, unlike other icon-only buttons in the suite.
- There is no destructive ghost action. Four product bars (tables, deals, companies, people) pass `text-destructive hover:text-destructive` to a ghost Button instead.
- `noun` is not pluralized. The tickets bar switches between `ticket` and `tickets` by hand; others use the default and print 12 selected.
- The aria-label is fixed to Bulk actions and cannot be changed, and no other props (such as `id` or `data-*`) are forwarded.

API `ActionBar` (extends Nothing. Only the props below are accepted.):
- `count: number`. How many records are selected. The bar shows while it is above 0.
- `noun?: string` = "selected". Printed after the count, as in 12 invoices selected. Not pluralized for you.
- `onClear: () => void`. Called by the trailing clear button.
- `children: React.ReactNode`. The actions, between the count and the clear button. Ghost `sm` buttons.
- `className?: string`. Merged onto the bar, for example to change `bottom-5` or `z-40`.

### Save bar

- Level: Organism
- Category: Feedback
- Status: Stable
- Import: `@oration/canon/components/save-bar`
- Exports: `SaveBar`
- Docs: /design/components/save-bar

Save bar is the sticky unsaved-changes bar for settings and configuration pages. It springs up from the bottom of the page column the moment the form differs from what was saved, says how many fields changed, and offers Discard, Save and ⌘S. Pair it with `useDirtyForm`, which keeps the saved baseline and the change count for you. The common mistake is wiring `dirty` to "the user typed something" instead of "the values differ from the last save", so the bar stays up after someone types a value back to what it was.

When to use:
- On a settings or configuration page where several fields are edited and committed together: payment run defaults, remittance settings, an agent's details.
- When a page spans several sections and one save should commit all of them.
- When leaving with unsaved edits would lose work, so the tab-close warning and ⌘S are worth having.

When not to use:
- For a single setting that applies the moment it changes. Save it in place and confirm with a toast. Use /design/components/switch instead.
- For a short form in a dialog. The dialog footer is the save action. Use /design/components/form-dialog instead.
- For actions on selected rows in a table or list. Use /design/components/action-bar instead.
- For one inline value, such as a supplier name in a record header. Use /design/components/editable-text instead.
- For the saving model of a whole page, including autosave and drafts. Read the pattern first. Use /design/patterns/saving instead.

Rules:
- The One Filled Button Rule: While the bar is showing, its Save button is the view's one filled indigo button. Page-level actions above it stay outline or ghost, and sections never carry their own filled Save.
- The Quiet Indigo Rule: The 6px indigo dot is the unsaved-changes marker, one of the viewer's own markers the rule allows. Don't add other indigo to the bar.
- The Tabular Figures Rule: The change count is set in tabular figures, so 9 unsaved changes becoming 10 unsaved changes doesn't shimmy.

Anatomy:
- Bar: A `<section aria-label="Unsaved changes">` on the popover surface with 12px corners and the popover shadow. Sticky 16px above the bottom of the scroll container, plus the safe-area inset.
- Unsaved dot: A 6px Quiet Indigo dot, decorative.
- Message: 13px muted text, one line, truncated. The change count by default, or your `message`. A polite live region.
- Discard: A ghost button that resets the form to the saved values. Disabled while saving.
- Save: The filled button. Shows a spinner while `saving` and carries `aria-keyshortcuts`.
- Shortcut hint: A `Kbd` reading ⌘S on Apple platforms and Ctrl S elsewhere, tinted to sit on the fill. Hidden below 640px.

States:
- Hidden: While `dirty` is false nothing renders, and the shortcut and leave warning are off.
- Unsaved: The bar is up with the count, Discard and Save. ⌘S saves and closing the tab asks first.
- Saving: `saving` puts a 14px spinner before the Save label and disables both buttons and the shortcut.
- Save blocked: `saveDisabled` dims Save and turns the shortcut off. Discard still works. Say what blocks it in `message`.
- Entering: Springs up from 12px below at 98% scale on the slow spring (240ms, light bounce).
- Leaving: Drops 8px and fades over a 160ms ease-out tween, faster than it came.

Behavior:
- Visibility follows `dirty` alone. With `useDirtyForm`, pass `form.isDirty`, which is true only while a field differs from the last saved snapshot, so typing a value back to what it was hides the bar again.
- `changes` drives the message: 1 reads 1 unsaved change, more reads 3 unsaved changes, and 0 or nothing reads You have unsaved changes. `message` replaces it entirely.
- ⌘S (Ctrl+S off Apple platforms) calls `onSave` and suppresses the browser's save dialog, but only while the bar can save: dirty, not saving and not `saveDisabled`. Shift and Alt variants are ignored.
- With `warnOnLeave`, a `beforeunload` handler asks before the tab closes or reloads while dirty. It does not intercept in-app navigation.
- `useDirtyForm(initial, { onSave })` holds `values` and a `saved` baseline. `save()` sets `saving`, awaits `onSave(values)`, and moves the baseline only if it resolves; throw or reject to keep the form dirty. It returns `true` or `false`.
- `reset()` puts the values back to the baseline; `replace(next)` swaps both, for when data finishes loading. Values are compared with `Object.is`, then by JSON for objects and arrays.
- The bar is sticky, so it rides at the bottom of the nearest scrolling ancestor while the page scrolls and settles after the last section at the end. Render it last inside the page column.

Do and don't:
- Do: Say how many fields changed, in plain words: 3 unsaved changes.
- Don't: Alarm people with a vague message such as Warning: you have unsaved data!
- Do: Use one save bar for the whole page, under the last section, so one save commits every section.
- Don't: Put a filled Save button in each section. People save one, leave, and lose the edits in the other.
- Do: When something blocks saving, disable Save and name the fix in the message: Enter a full email address to save.
- Don't: Disable Save with the default count still showing, so nobody knows why it won't save.

Content:
- Leave the default count in most cases. It is specific, short and tabular.
- A custom `message` says what will happen or what blocks the save, in one short sentence without a period: Approval changes apply to the next payment run.
- Keep Save changes and Discard unless the commit means something more specific, such as Publish for a versioned procedure or Apply to 212 invoices.
- Confirm a successful save with a short toast, Changes saved. Report a failure with what to do: Couldn't save changes and Check your connection and try again.

Accessibility:
- The bar is a labelled region, Unsaved changes, so screen reader users can jump to it from the landmarks list.
- The message is `aria-live="polite"`, so a changing count is announced without stealing focus.
- The bar never takes focus when it appears. It sits after the form in source order, so Tab reaches Discard and Save after the last field.
- Save carries `aria-keyshortcuts` (`Meta+S` or `Control+S`). The visible key hint is `aria-hidden` so the name stays Save changes.
- While saving, the spinner is hidden from assistive tech and both buttons are disabled. Announce the result with a toast.
- Labels on both buttons are real text at the 32px control height.
- ⌘ + S: Saves while the bar is showing and can save. Ctrl+S off Apple platforms.
- Tab: Moves from the last field to Discard, then Save.
- Enter: Activates the focused button.

Known gaps (follow the system, not the gap):
- The ⌘S listener is on `window`. Two dirty save bars on one screen both save on one keypress, so keep one per page.
- `warnOnLeave` only covers closing or reloading the tab. Following an in-app link with unsaved edits loses them without asking.
- While saving, the spinner is added before the label rather than over it, so Save widens by the spinner's width. Pending button keeps the width steady.
- The message's live region mounts with its text already in it, so most screen readers don't announce the bar's arrival, only later count changes.
- The enter spring and exit tween have no reduced-motion check of their own. The app-wide `MotionConfig reducedMotion="user"` drops the rise and scale; the fade still plays.
- The key hint reads ⌘S on first render everywhere and switches to Ctrl S after mount on other platforms.
- A failed save is silent: `save()` swallows the error and returns `false`. Show the failure from `onSave` yourself.

API `SaveBar`:
- `dirty: boolean`. Shows the bar and arms the shortcut and leave warning. Pass `form.isDirty`.
- `onSave: () => void`. Runs on Save and on ⌘S. Usually `() => void form.save()`.
- `onDiscard: () => void`. Runs on Discard. Usually `form.reset`.
- `changes?: number`. Number of changed fields, shown as 3 unsaved changes. Pass `form.dirtyCount`.
- `message?: React.ReactNode`. Replaces the change count.
- `saving?: boolean` = false. Shows the spinner and disables both buttons and the shortcut.
- `saveDisabled?: boolean`. Disables Save and the shortcut. Discard stays enabled.
- `saveLabel?: React.ReactNode` = "Save changes". The Save button's label.
- `discardLabel?: React.ReactNode` = "Discard". The Discard button's label.
- `shortcut?: boolean` = true. Saves with ⌘S or Ctrl+S and shows the key hint.
- `warnOnLeave?: boolean` = true. Asks before closing or reloading the tab while dirty.
- `className?: string`. Classes for the sticky wrapper, such as a different `bottom-*`.

API `useDirtyForm`:
- `initial: T extends Record<string, unknown>`. The starting values and the first baseline. Read once on mount.
- `options.onSave?: (values: T) => void | Promise<void>`. Runs on `save()`. Throw or reject to keep the form dirty.

API `useDirtyForm return value`:
- `values?: T`. The current values.
- `saved?: T`. The last saved baseline.
- `set?: (key: K, value: T[K] | ((current: T[K]) => T[K])) => void`. Sets one field, with a value or an updater.
- `setValues?: React.Dispatch<React.SetStateAction<T>>`. Replaces all values without touching the baseline.
- `reset?: () => void`. Puts the values back to the baseline. Wire to Discard.
- `replace?: (next: T) => void`. Replaces values and baseline together, e.g. after a load.
- `save?: () => Promise<boolean>`. Runs `onSave` and moves the baseline on success. Resolves `false` on failure.
- `saving?: boolean`. True while `onSave` is pending.
- `dirtyKeys?: Array<keyof T>`. Keys whose value differs from the baseline.
- `dirtyCount?: number`. `dirtyKeys.length`. Pass to `changes`.
- `isDirty?: boolean`. True when any field differs. Pass to `dirty`.

API `changedKeys`:
- `saved: T`. The baseline snapshot.
- `values: T`. The current snapshot. Returns the keys that differ.

### Settings section

- Level: Organism
- Category: Layout
- Status: Stable
- Import: `@oration/canon/components/settings-section`
- Exports: `SettingsSection`, `SettingsGroup`, `SettingsRow`
- Docs: /design/components/settings-section

Settings section is the rhythm of every settings page. `SettingsSection` titles a block of settings and separates it from the next with a hairline and 40px of space, `SettingsGroup` is the card that holds its rows, and `SettingsRow` puts the label and description on the leading side and the control on the trailing side. The thing people get wrong is the description: the row gives it an id, but it's up to you to point the control's `aria-describedby` at it with `descriptionId`.

When to use:
- For any settings or configuration page: workspace, payments, remittance, an agent's details.
- To pair a named setting with its control and one sentence about its effect, in a row that stacks on narrow screens.
- To group related settings in one card under a section title, with section-level actions such as Add approver.
- With `data-settings-mode="read"` around it, to show the same page to people who can view but not change settings.

When not to use:
- For a form people fill in once, such as adding a supplier. Labels sit above controls there. Use /design/components/field instead.
- For a list of records with columns, such as API keys or approvers with roles. Put a table in the section instead. Use /design/components/card-table instead.
- For the heading of a content block on a dashboard or record page. Use /design/components/section-header instead.
- For a read-only list of facts about a record. Use /design/components/meta instead.
- For the page itself. Settings pages start with one page title. Use /design/components/page-title instead.

Rules:
- The Hairline-and-Lift Rule: The group card takes its edge from `shadow-border`, never a border plus a shadow. Rows are split by CSS hairlines, the structural dividers the rule allows, and sections by a hairline on top.
- The Tint Well Rule: A sub-region inside a group, such as a preview or a code sample, is a 70% Well Gray tint with 10px corners, not a second card.
- The Thirteen-Fourteen Rule: Labels and section titles are 14px; descriptions are 13px muted. Don't shrink descriptions further to fit more in a row.
- The One Filled Button Rule: Section actions are outline or ghost. The page's one filled button is the save bar's Save, or the page title's main action.

Anatomy:
- Section title: An `h2` at 14px semibold that names the section. The section is labelled by it.
- Info tip: Optional `InfoTip` beside the title or a row label, for jargon and deeper help.
- Section description: One 13px muted sentence on what these settings affect, up to 36rem wide.
- Section actions: Optional buttons on the trailing side, bottom-aligned with the description. They wrap below on narrow screens.
- Group: A Card White surface with 12px corners and `shadow-border`, with a hairline between rows.
- Row label and description: 14px medium label (a real `<label>` when `htmlFor` is set) and a 13px muted description up to 28rem wide.
- Control: Whatever the row sets, on the trailing side. Full width below 640px unless the row is `inline`.

States:
- Rest: Label and description on the left, control on the right, vertically centered from 640px up.
- Stacked: Below 640px a default row stacks: label, description, then a full-width control.
- Inline: `inline` keeps the control beside the label at every width, for switches and checkboxes.
- Top-aligned: `align="start"` pins the label to the top of a tall control such as a textarea.
- First section: The first section on a page drops its top hairline and top padding.
- Read-only: Inside `[data-settings-mode="read"]`, inputs and selects lose their border, fill and padding and read as plain text, select chevrons and row buttons disappear, and disabled controls stay at full opacity.

Behavior:
- Sections are 40px apart: `py-10` with a hairline on top. `first:` removes both on the first section, so a page's sections can be plain siblings.
- Give a section an `id` and its heading gets `<id>-heading`, and the section becomes a jump target with an 80px scroll margin for the sticky header. Side tabs and deep links use this.
- With `htmlFor`, the row label renders as `<label for>` with id `<htmlFor>-label`, and the description gets id `descriptionId(htmlFor)`. Without it both are plain `<div>`s.
- Rows stack below 640px unless `inline`. The control slot is full width when stacked, then shrinks to its content and right-aligns from 640px up.
- Section actions wrap under the title block when there isn't room beside it.
- Read-only mode is a CSS rule in `apps/web/src/app/globals.css`. The settings shell wraps a page in `<div data-settings-mode="read">`, shows a status note and puts the page in `<fieldset disabled className="contents">`, which disables native inputs and buttons. Pass `disabled` to Base UI controls such as Switch too.

Do and don't:
- Do: Keep labels on the leading side and controls on the trailing side, so every control in a group lines up on one edge.
- Don't: Put the control straight after the label text. The controls land at a different x on every row and the group reads ragged.
- Do: Put related rows in one group card, split by hairlines.
- Don't: Give every row its own card. It stacks edges on edges and breaks the section into unrelated pieces.
- Do: Keep the row description to one sentence about the effect, and move the explanation of jargon into an `InfoTip`.
- Don't: Write a paragraph of help under the label. The control drifts away from its name and nobody reads it.

Content:
- Section titles are short nouns in sentence case: Remittance, Approvals, API keys.
- Section descriptions say what the settings affect, in one sentence: Where remittance advice goes and what it includes.
- Row labels name the setting, not the action: Remittance email, not Set your remittance email. No colons.
- Row descriptions state the consequence: Invoices approved after this go in tomorrow's run.
- Switch labels describe the on state, so the switch reads as yes or no: Email suppliers when paid. Skip Enable and Toggle.
- Badges are single words in a tag, such as Beta or Admin only. Don't put status in the label text.

Accessibility:
- Each section is a `<section aria-labelledby>` pointing at its `h2`, so it is a named region. Section titles sit under the page's one `h1`.
- Set `htmlFor` to the control's id so the label is a real `<label>`; clicking it focuses or toggles the control.
- Wire the description yourself: `aria-describedby={descriptionId(id)}` on the control. The row only sets the id.
- Rows without `htmlFor` render their label as text, so give the control its own name with `aria-label`.
- `InfoTip` is a button named About {title} that opens on click, Enter or Space, or after 350ms of hover.
- In read-only mode the note above the page is `role="status"` and the disabled fieldset removes native controls from the tab order.
- Tab: Moves through info tips and controls in row order. Rows themselves are not focusable.
- Enter: Opens a focused info tip.
- Esc: Closes an open info tip.

Known gaps (follow the system, not the gap):
- `SettingsRow` sets the description's id but doesn't connect it to the control. Every call site has to add `aria-describedby={descriptionId(id)}`, and some don't.
- The read-only rule lives in `apps/web/src/app/globals.css`, not in `packages/canon`, so these components get no read-only styling outside the web app.
- Read-only mode hides every button inside a settings row, including harmless ones such as Copy or View logs, but leaves buttons in a section's `actions` visible (disabled by the fieldset). The settings page hides its page-level actions separately.
- In read-only mode switches and checkboxes keep their full-opacity look, so only the status note says they can't be changed.
- `SettingsSection` renders `description` inside a `<p>`, so block content there produces invalid HTML. `SettingsRow` uses a `<div>`.

API `SettingsSection`:
- `title: React.ReactNode`. The `h2`.
- `description?: React.ReactNode`. One sentence under the title. Renders in a `<p>`.
- `actions?: React.ReactNode`. Buttons on the trailing side of the header.
- `info?: React.ReactNode`. An `InfoTip` beside the title.
- `badge?: React.ReactNode`. A tag beside the title, such as Beta.
- `id?: string`. The section's id. The heading becomes `<id>-heading`. Use it for side tabs and deep links.
- `children?: React.ReactNode`. Usually one `SettingsGroup`, or a table.
- `className?: string`. Classes for the `<section>`.

API `SettingsGroup` (extends <div>):
- `className?: string`. Merged after the card classes.

API `SettingsRow`:
- `label: React.ReactNode`. The setting's name.
- `description?: React.ReactNode`. One sentence on the effect. Renders in a `<div>`.
- `htmlFor?: string`. The control's id. Makes the label a `<label>` and gives the description `descriptionId(htmlFor)`.
- `info?: React.ReactNode`. An `InfoTip` beside the label.
- `badge?: React.ReactNode`. A tag beside the label.
- `children?: React.ReactNode`. The control, on the trailing side.
- `inline?: boolean` = false. Keeps the control beside the label below 640px. For switches and checkboxes.
- `align?: "center" | "start"` = "center". Vertical alignment from 640px up. `start` for tall controls. Ignored when `inline`.
- `className?: string`. Classes for the row.

API `descriptionId`:
- `id: string`. The same id passed to `htmlFor`.

### Data state

- Level: Organism
- Category: Feedback
- Status: Stable
- Import: `@oration/canon/components/data-state`
- Exports: `DataState`, `EmptyState`, `ErrorState`, `useDelayedFlag`
- Docs: /design/components/data-state

Data state renders one data component's loading, empty, error and success states in place. Give it a query from `useMockQuery`, a skeleton shaped like the content, an `isEmpty` test and an `empty` description, and its children only ever run with data. `EmptyState` and `ErrorState` are exported for states that don't come from a query, and `useDelayedFlag` holds back spinners and hints for work that finishes fast. The mistake to avoid is one spinner for the whole page: each component owns its states, so a failed stat strip doesn't blank the table under it.

When to use:
- Around every component that reads data: a table, a list, a stat strip, a chart, a profile card.
- To show a skeleton shaped like the content while it loads, then reveal the content with the skeleton reveal without moving the layout.
- To say a read failed and offer Retry, inside the component that failed.
- With `EmptyState` on its own for filtered-to-nothing and no-results states that don't come from a query.
- With `useDelayedFlag` to show a spinner or a Still loading hint only after work has run for a beat.

When not to use:
- For a first-run page that needs more than a sentence and an action. Compose the empty state yourself. Use /design/components/empty instead.
- For an action in progress, such as Save or Send. Use /design/components/pending-button instead.
- For an action that failed. Reads fail in place; writes fail in a toast. Use /design/components/toast instead.
- For a problem that affects the whole page, such as a disconnected integration. Use /design/components/alert instead.
- For the placeholder shapes themselves. Use /design/components/skeleton instead.

Rules:
- The One Filled Button Rule: Retry is an outline button, and empty-state actions are outline unless filling the list is the one thing the view is for. A failed card never adds a second filled button to the page.
- The Thirteen-Fourteen Rule: At `md` titles and descriptions are 14px. At `sm` the title steps down to 13px and the description to 12px meta. Nothing goes smaller.

Anatomy:
- Illustration: A line illustration. Empty states pick one (`done`, `search`, `filters`…); errors always use `error` at 80px.
- Title: One line, semibold: what is empty or what failed.
- Description: One muted sentence: what shows up here, or what to do about the failure.
- Action or Retry: The empty state's next step, or the outline Retry button that calls `query.retry`.
- Wrapper: `<div data-slot="data-state" data-status>` with `aria-busy` while loading, plus the `.t-skel` reveal class. `data-status` is `loading`, `error`, `empty` or `content`; `data-phase` is `loading`, `enter`, `revealing` or `done`.
- Status region: A visually hidden `role="status"` that announces the error title and description.

States:
- Loading: Your skeleton, plus a visually hidden Loading. The wrapper is `aria-busy`.
- Warm: A key that resolved once this session renders its content straight away, with no skeleton and no animation.
- Success: `children(data)`, revealed over the skeleton: a 400ms cross-fade with a 2px cross-blur.
- Empty: `EmptyState` from `empty`, when `isEmpty(data)` is true. Both props are needed.
- Error: `ErrorState` with `errorTitle`, the error's message plus Try again in a moment., and Retry. Announced politely.
- Retrying: Retry starts a new attempt: back to the skeleton, then success or the error again.
- Small: `size="sm"` for cards and rails: tighter padding, the small illustration, a 13px title, a 12px description and an extra-small Retry.

Behavior:
- The view is chosen in order: loading, then error, then empty (only when both `empty` and `isEmpty` are given and `isEmpty(data)` is true), then content.
- Loading to the first settled view runs the skeleton reveal (transitions.dev): the skeleton pulses (1000ms, to 0.5 opacity), then content mounts under it and both layers cross-fade with a 2px cross-blur over 400ms ease-in-out before the skeleton unmounts. Going back to loading snaps, never animating the reverse. The first render of warm data never animates.
- Swaps between settled views (content to empty, error to content) are keyed inside `AnimatePresence` with `mode="popLayout"` and `initial={false}`: fade in on the fast spring (80ms), out over a 60ms tween, the leaving view popped out of layout.
- `useMockQuery(key, load, options)` waits 250 to 850ms (stable per key) times the demo latency setting, then resolves. `fail: true` always fails, `enabled: false` stays loading, and the demo failures setting fails each key's first attempt.
- Keys that resolved stay warm for the session, like a cache, until `replayLoading()` from `@oration/canon/lib/demo-data` forgets them.
- `query.retry()` starts a new attempt for the same key. Once settled, `data` is re-read from `load` on every render, so live mock data stays current.
- `useDelayedFlag(flag, delay = 200)` turns true only after `flag` has stayed true for `delay` ms, and false the moment `flag` does.

Do and don't:
- Do: Give each data component its own `DataState`, so a failed card fails alone and the rest of the page keeps working.
- Don't: Hold the whole page behind one spinner until every request finishes.
- Do: Name what failed in `errorTitle`: Couldn't load invoices on hold.
- Don't: Leave the default Couldn't load this, or show the raw error, so nobody knows which part broke.
- Do: Shape the skeleton like the content, row for row, so the crossfade doesn't move anything.
- Don't: Show a centered spinner in a list that then jumps to its full height.

Content:
- Error titles name the thing: Couldn't load queue totals, Couldn't load callbacks. Use Couldn't, not Failed to or Error:.
- Error descriptions say what happened and what to do. The default is the error's message plus Try again in a moment.
- Empty titles say what's empty in plain words: Nothing on hold, No callbacks waiting. Not No data.
- Empty descriptions say what shows up here and how it gets here: Invoices that fail matching wait here for review.
- When a filter or search caused it, say so and offer the way back: No suppliers match with Clear search.
- Loading has no words. If it runs long, add one quiet line after a delay: Still loading invoices.

Accessibility:
- While loading the wrapper is `aria-busy` and holds a visually hidden Loading; skeletons from `@oration/canon/components/skeletons` are `aria-hidden`.
- Errors are announced through a polite `role="status"` region as the title and description.
- Illustrations are decorative. The title and description carry the meaning.
- Retry and empty-state actions are real buttons with text labels, at 28px (`md`) or 24px (`sm`).
- Keep the empty state's action a link when it goes somewhere, such as Add a supplier opening another page.
- Tab: Reaches Retry or the empty state's action.
- Enter: Retries, or runs the empty state's action.

Known gaps (follow the system, not the gap):
- `DataState` only accepts a `MockQuery<T>`. There is no adapter for a real data layer yet, so production reads will need one with the same `{ status, data, error, retry }` shape.
- Pressing Retry swaps the error view for the skeleton, so the focused button disappears and focus falls back to the page. Nothing moves focus to the content when it arrives.
- Only errors are announced. The status region stays empty while loading and when content or an empty state arrives.
- `isEmpty` is ignored without `empty`, so a list that forgot `empty` renders its children with no rows and no message.

API `DataState`:
- `query: MockQuery<T>`. `{ status, data, error, retry }`, from `useMockQuery`.
- `skeleton: React.ReactNode`. Placeholder shaped like the content.
- `children: (data: T) => React.ReactNode`. Renders the content. Only called with data.
- `isEmpty?: (data: T) => boolean`. True when the data has nothing to show. Needs `empty`.
- `empty?: EmptyStateProps`. `{ illustration?, title, description?, action? }` for the empty view.
- `errorTitle?: string` = "Couldn't load this". Names what failed.
- `errorDescription?: string`. Replaces the default, which is the error's message plus Try again in a moment.
- `size?: "sm" | "md"` = "md". `sm` for cards and rails.
- `className?: string`. Classes for the wrapper.
- `contentClassName?: string`. Classes for the element around each view, such as `h-full` or `flex flex-col`.

API `EmptyState`:
- `title: string`. What is empty.
- `illustration?: IllustrationName`. Shown at 120px (`md`) or 80px (`sm`).
- `description?: React.ReactNode`. One sentence.
- `action?: React.ReactNode`. Buttons or links, centered under the text.
- `size?: "sm" | "md"` = "md". Padding, illustration and type size.
- `className?: string`. Classes for the root.

API `ErrorState`:
- `title?: string` = "Couldn't load this". Names what failed.
- `description?: React.ReactNode` = "The request didn't finish. Try again in a moment.". What happened and what to do.
- `onRetry?: () => void`. Shows the Retry button when set.
- `size?: "sm" | "md"` = "md". Padding, type size and a 28px or 24px Retry.
- `className?: string`. Classes for the root.

API `useDelayedFlag`:
- `flag: boolean`. The raw condition, such as `query.status === "loading"`.
- `delay?: number` = 200. How long `flag` must hold, in ms.

API `useMockQuery`:
- `key: string`. Identifies the read. Resolved keys stay warm for the session.
- `load: () => T`. Returns the mock data.
- `options.delay?: number`. Base wait in ms before the latency multiplier. Defaults to 250 to 850ms per key.
- `options.fail?: boolean` = false. Always fail, to show the error state.
- `options.enabled?: boolean` = true. While false, stays in loading.

### Page intro

- Level: Organism
- Category: Content
- Status: Stable
- Import: `@oration/canon/components/page-intro`
- Exports: `PageIntro`, `resetPageIntro`
- Docs: /design/components/page-intro

Page intro is a slim, dismissible banner at the top of an overview page. In two sentences it says what this place is and why you'd use it, with an optional short video and a link to the full article. Once someone closes it, it stays closed in that browser, keyed by its `id`. It is orientation, not news: the common mistake is using it for a release note or a promotion, or putting one on a dense tool screen that people use all day.

When to use:
- At the top of an overview page people meet early and come back to: Procedures, Queues, Callbacks, Cohorts.
- To explain the idea a page assumes, such as what a procedure is compared to a prompt, with a video or article for the rest.
- Once per page, directly under the page title.

When not to use:
- For a term or metric that needs explaining in place. Put an info tip beside it. Use /design/components/info-tip instead.
- For an announcement, an outage or a warning that has to be read. Use /design/components/alert instead.
- For a confirmation after an action. Use /design/components/toast instead.
- For a page with nothing in it yet. The empty state explains and offers the first action. Use /design/components/empty instead.
- For a dense tool screen such as the inbox or the agent workspace. Leave it bare and use info tips where needed. Use /design/patterns/education instead.

Rules:
- A tint, not a card: The intro is a 70% Well Gray tint with 12px corners and no edge or shadow, so it reads as help about the page rather than content on it.
- The One Filled Button Rule: The intro carries links and a ghost dismiss button only. The page's filled button stays in the page title.
- The Thirteen-Fourteen Rule: The title and description are 14px reading text; the links are 13px. The intro is read once, so it doesn't shrink to dense type.

Anatomy:
- Banner: A `<section>` labelled by its title: Well Gray at 70%, 12px corners, 12px top and bottom padding, room on the right for dismiss.
- Title: An `h2` at 14px semibold, balanced across lines.
- Description: 14px muted text up to 42rem wide. One or two sentences.
- Video link: With `video`, a 13px indigo link, Watch the 4-minute overview, that opens the video in a dialog.
- Learn more: With `learnMoreHref`, a 13px indigo link. External URLs open in a new tab.
- Dismiss: A 24px ghost icon button in the top-right corner, named Dismiss {title}, with a tooltip.
- Illustration: Optional, 72px wide, on the leading side. Hidden below 640px, and left out of the drawing here.

States:
- Unknown: On the server and the first client render nothing is drawn, until the browser has said whether it was dismissed. It never flashes in and out.
- Shown: Appears without animation on page load.
- Dismissing: Collapses its height and fades over a 120ms ease-out tween, taking `spaceAfter` with it. Focus moves to a hidden {title} dismissed note.
- Dismissed: Renders nothing. Stays dismissed across reloads and in other tabs.
- Shown again: After `resetPageIntro(id)`, opens from zero height on the moderate spring (160ms).
- Video open: A dialog titled with the video's title, its duration as the description, and the player already loading.

Behavior:
- Dismissal is stored in `localStorage` under `oration:intro:<id>`. Intros with the same id update together in this tab, and a `storage` listener keeps other tabs in step.
- When storage is blocked, as in some private windows, dismissal is held in memory for the session.
- `resetPageIntro(id)` shows one intro again. `resetPageIntro()` with no id clears every intro in the browser, which is what a Show page tips again setting wants and a demo never does.
- `spaceAfter` is bottom spacing in pixels inside the collapsing element, so the gap below the intro closes with it. A parent `gap` or margin would stay behind and jump.
- `video` takes `{ youtubeId, title, duration }`. The link reads the duration rounded to whole minutes (at least 1); the dialog loads the privacy-enhanced player straight away.
- `learnMoreHref` starting with `http://` or `https://` opens in a new tab with `rel="noopener noreferrer"`. Other paths open in place.
- Only an intro that was dismissed and shown again animates in. The first reveal on load doesn't.

Do and don't:
- Do: Say what the place is for and when you'd use it, in two sentences, and link the video or article for the rest.
- Don't: Use the intro for a release note or a promotion, with an exclamation point and a filled call to action.
- Do: Use one intro per page, under the page title, on overview pages.
- Don't: Stack intros, or put one above the inbox or a data grid people work in all day.
- Do: Give each intro a stable, namespaced id such as `ai.procedures` and keep it.
- Don't: Share an id across pages, so closing one hides both, or change it every release, so it comes back after people closed it.

Content:
- The title says what you can do here, as an outcome, in sentence case without a period: Keep high-stakes calls on the rails, Every queue, live.
- Don't repeat the page title. The page title names the place; the intro says why it matters.
- The description is one or two sentences: what this is, then when you'd use it or what to open next.
- Write the video's `duration` as `m:ss`, such as `4:05`. The link text is generated from it.
- No exclamation points, no New, no marketing. If it changes, it isn't an intro.

Accessibility:
- The banner is a `<section>` labelled by its `h2` title, under the page's one `h1`.
- Dismiss is an icon-only button named Dismiss {title}, with a Dismiss tooltip and a 24px target.
- After dismissing, focus moves to a visually hidden {title} dismissed note, so keyboard and screen reader users aren't dropped at the top of the page.
- The video link is a button that opens a dialog. The dialog is titled with the video's title and described by its duration; Esc closes it and focus returns to the link.
- External Learn more links announce (opens in a new tab), and both links include the intro title for screen readers.
- The illustration is decorative.
- Tab: Moves through the links, then Dismiss.
- Enter: Follows a link, opens the video or dismisses the intro.
- Esc: Closes the video dialog.

Known gaps (follow the system, not the gap):
- Because nothing renders until the browser has read storage, the intro appears just after hydration on every visit and pushes the page down once. Reserve the space or accept the shift.
- The collapse and expand animate height through Motion. The app-wide `MotionConfig reducedMotion="user"` only drops transforms, so the height animation still plays under reduced motion.
- `className` lands on the inner tinted box, so a margin passed through it doesn't collapse with the banner. Use `spaceAfter` for the gap below.

API `PageIntro`:
- `id: string`. Stable, namespaced key for the dismissal, such as `ai.procedures`. Stored as `oration:intro:<id>`.
- `title: string`. The `h2`. Also names the dismiss button.
- `description: React.ReactNode`. One or two sentences.
- `illustration?: IllustrationName`. Shown at 72px from 640px up.
- `video?: { youtubeId: string; title: string; duration: string }`. Adds the video link and its dialog.
- `learnMoreHref?: string`. Adds a Learn more link. External URLs open in a new tab.
- `spaceAfter?: number` = 0. Bottom spacing in px that collapses with the banner.
- `className?: string`. Classes for the tinted box inside the collapsing section.

API `resetPageIntro`:
- `id?: string`. The intro to show again. Omit to reset them all.

### Page title

- Level: Organism
- Category: Layout
- Status: Beta
- Import: `@oration/canon/components/page-title`
- Exports: `PageTitle`, `PageBody`
- Docs: /design/components/page-title

Page title is the page's one `h1`, with an optional sentence of description, a leading icon or avatar, and the page's actions on the trailing side. `PageBody` is the centered 72rem column that document pages sit in. What goes wrong is the heading outline: a page has exactly one `h1`, so a page without a visible page title passes `heading` to the app header instead, and nothing else on the page is an `h1`.

When to use:
- At the top of every document page: list pages, settings pages, record pages and overviews.
- To hold the page's main action, the one filled button, with its secondary actions beside it.
- With an avatar or monogram tile in `icon` on a record page, such as a supplier or a customer.
- `PageBody` as the content column of a document page, so pages share one width and one gutter.

When not to use:
- For a heading inside the page. Sections get an `h2`. Use /design/components/section-header instead.
- For a block of settings on a settings page. Use /design/components/settings-section instead.
- For where-am-I navigation at the top of the window. Use /design/components/breadcrumb instead.
- For the title of a dialog or sheet. Use /design/components/dialog instead.
- For full-bleed tool screens such as the inbox or a flow canvas, which name themselves in the header. Use /design/templates/workspace instead.

Rules:
- One h1 per page: Every page has exactly one `h1`. It is the page title, or, where the design has no visible title, the visually hidden `heading` of the app header. Sections are `h2`.
- The One Filled Button Rule: Page actions hold the view's one filled button at most, last in the row. Everything else beside it is outline or ghost, at `sm` in the product.
- The Quiet Indigo Rule: Titles are ink, never indigo or a category hue. Status beside a title is a tag with words, not a colored title.

Anatomy:
- Icon: Optional. An avatar or monogram tile on the leading side, top-aligned with the title, 12px from it.
- Title: The `h1`: 20px semibold with -1.5% tracking. Wraps rather than truncating.
- Description: Optional. One 14px muted sentence, up to 42rem wide.
- Actions: Optional buttons on the trailing side, top-aligned. They wrap under the title block when there isn't room.
- Page body: `PageBody`: a centered column, 72rem wide at most, with 24px side and 32px top and bottom padding.

States:
- Rest: Title block on the leading side, actions on the trailing side.
- Wrapped: When the row is narrower than the 16rem title block plus the actions, the actions move below it, aligned to the start.
- With icon: The icon sits beside the title and description, aligned to the top.
- Title only: Without description or actions it is a single 20px line.

Behavior:
- The row is a wrapping flex: the title block grows from a 16rem basis and the actions don't shrink, so actions drop below the title on narrow screens instead of squeezing it.
- PageTitle has no outer margin. Space it from what follows at the call site; settings pages put 40px before the first section, list pages use `className="mb-6"`.
- `PageBody` spreads its props onto a `<div>` with `mx-auto w-full max-w-6xl px-6 py-8`; override the width with `className` for full-width lists.
- Neither component has state or effects, so both render on the server.
- Pages that don't show a page title pass `heading` to the app header, which renders a visually hidden `h1`.

Do and don't:
- Do: Give the page one filled action, last, with secondary actions as outline.
- Don't: Fill every action in the title row. Nothing reads as the main thing to do.
- Do: Name the place in the title and say what's in it in the description.
- Don't: Write the title as an instruction and repeat it in the description.
- Do: Use one page title per page and `h2` section headings under it.
- Don't: Add a second page title for a tab or a section. Screen reader users lose the page's name.

Content:
- List pages are a plural noun: Suppliers, Payment runs, Callbacks. Record pages are the record's name: Northwind Freight.
- Settings pages are the area's name: Remittance, Business hours.
- The description is one sentence on what's here and its scope: Every supplier contact who has reached Cedarline support, with their open conversations.
- Keep counts and status out of the title text. Put status in a tag beside it and counts in the content.
- Action labels are verb first: Schedule run, Import contacts, Export CSV.

Accessibility:
- The title is the page's `h1`. Check the heading outline: one `h1`, then `h2` for sections.
- An avatar in `icon` that repeats the title is decorative; hide it from assistive tech or give it empty alt text.
- Actions come after the title and description in source order, so they are read after the page's name.
- Don't put links or buttons inside `title`. Keep the heading plain text, plus at most a tag.
- Icon-only actions need an `aria-label` and a tooltip.

Known gaps (follow the system, not the gap):
- PageTitle always renders an `h1` and takes no `id` or heading level, so it can't be previewed or reused without adding another `h1`. The previews on this page add several to it.
- `description` renders inside a `<p>`, so block content there produces invalid HTML.
- There is no spacing contract below the title. Call sites add `mb-6`, `mt-10` on the next block or nothing, so the gap varies from page to page.

API `PageTitle`:
- `title: React.ReactNode`. The `h1` content. Text, plus at most a tag.
- `description?: React.ReactNode`. One sentence under the title. Renders in a `<p>`.
- `actions?: React.ReactNode`. Buttons on the trailing side.
- `icon?: React.ReactNode`. An avatar or tile on the leading side.
- `className?: string`. Classes for the row, such as a bottom margin.

API `PageBody` (extends <div>):
- `className?: string`. Merged after the column classes.

### Card stack

- Level: Organism
- Category: Data display
- Status: Beta
- Import: `@oration/canon/components/card-stack`
- Exports: `CardStack`, `CardStackItem`
- Docs: /design/components/card-stack

Card stack draws a pile of cards: the first item in front and up to two more peeking out above it. Hovering or focusing the pile fans it open a little, and clicking it either opens the front item or cycles to the next. The product uses it for the what's new cards at the bottom of the sidebar and for agent templates, where the pile says "there's more than one of these" in the space of one card. The whole pile is a single button, so the mistake to avoid is putting links or buttons inside a card: they can't be reached, and the markup is invalid.

When to use:
- To show that several items of the same kind are waiting, in the space of one, such as unread updates or held remittances.
- For a template or preset that bundles several parts, where the back cards hint at what's included.
- When one click should open the front item, or step through the pile.

When not to use:
- For items people need to compare or act on one by one. Show them as a list. Use /design/components/item instead.
- For slides browsed in order with previous and next controls. Use /design/components/carousel instead.
- For pages read in order inside a modal. Use /design/components/stacked-dialog instead.
- For a single card with actions inside it. Use /design/components/card instead.

Rules:
- The Hairline-and-Lift Rule: Every card in the pile is Card White with the hairline lift and 12px corners. No borders, and no heavier shadow on the front card; depth comes from the offset and scale.
- The Tint Well Rule: Don't nest a card stack inside a card as a second bordered card. Inside a card, use a tint well or a list.

Anatomy:
- Front card: The first item, full size, with its content visible. Its text is the pile's accessible name unless `label` is set.
- Back cards: Up to `max - 1` more cards behind it, each `peek` px higher and 5% smaller. Their content is hidden; only the shells show.
- Peek space: Top padding of `(count - 1) × peek` px, or twice that when the fan is on, so the open pile stays inside its box.
- Focus ring: On keyboard focus, a 2px Focus Indigo ring at 50% on the front card.

States:
- Rest: Back cards offset by `peek` px per step and scaled 5% per step.
- Fanned: On pointer hover (not touch) or keyboard focus: each back card rises to twice its rest offset and keeps its rest scale. No tilt, and the front card stays put. The moderate spring, 160ms with no bounce; each card starts 40ms after the one in front, and closing drops that delay.
- Focus visible: Fans the pile and rings the front card.
- Cycling: Without `onSelect`, a click moves the front card to the back and the next one forward.
- Single item: One card, no peek space, nothing to cycle.
- Empty: Renders nothing when `items` is empty.

Behavior:
- The pile is one `<button type="button">`. Click, Enter or Space calls `onSelect` with the front item's index in `items`, or cycles the pile when there's no `onSelect`.
- Fanning follows hover for mouse and pen, and `:focus-visible` for the keyboard, so tapping on a phone never fans it.
- `items` can be plain nodes or `{ id, content }`. Use ids when the list changes, so each card keeps its identity as it moves.
- Only `max` cards render (3 by default). When cycling, the order wraps.
- Put controls that act on the pile, such as a dismiss button, outside it as a sibling and position them over it, as the sidebar's what's new cards do.
- Under the app's `MotionConfig reducedMotion="user"` the cards move to their positions without animating.

Do and don't:
- Do: Keep the front card to a line or two of text, and put actions beside the pile.
- Don't: Put a button or link inside a card. It's nested in the pile's button, so it can't be focused and clicks go to the pile.
- Do: Give the pile a `label` that says what clicking does and how many are waiting: What's new: 3 unread updates. Open.
- Don't: Rely on the peeking cards to say there are more. Screen readers only hear the front card.

Content:
- Front card: a short caption (What's new, a date) over one line of title text, truncated.
- `label`: what it is, what's in front and the count. Held remittances: Northwind Freight, 3 waiting.
- Back cards show no text, so don't put anything there that people need.

Accessibility:
- The pile is a native button. Back cards are `aria-hidden` and ignore the pointer.
- Without `label`, the accessible name is the front card's text. Pass `label` when the text alone doesn't say what clicking does.
- Fanning is decorative; nothing is announced when it fans.
- Don't nest interactive elements inside `items`.
- The focus ring is on the front card, so it stays visible as the pile fans.
- Tab: Focuses the pile and fans it.
- Enter: Opens the front item, or cycles the pile.
- Space: The same as Enter.

Known gaps (follow the system, not the gap):
- The focus ring is 2px at 50%. Elsewhere the suite's focus ring is 3px, at 40% on buttons and 50% on fields.
- Interactive cards in DESIGN.md take the hairline lift, hover on hover. The front card keeps the resting shadow; only the fan shows hover.
- Back cards render their full content and hide it with `opacity-0`, so every visible item's content mounts even though only the front card shows.
- `cursor-pointer` is set on the pile; other buttons in the suite keep the default cursor.

API `CardStack`:
- `items: CardStackItem[]`. The cards, front first. Each is a node or `{ id: string; content: ReactNode }`.
- `onSelect?: (index: number) => void`. Called with the front item's index on click. Without it, clicking cycles the pile.
- `fan?: boolean` = true. Spread the pile on hover and keyboard focus.
- `max?: number` = 3. Cards shown, front included.
- `peek?: number` = 6. How far each back card shows above the one in front, in px.
- `label?: string`. Accessible name. Defaults to the front card's text.
- `className?: string`. Merged onto the button.
- `cardClassName?: string`. Merged onto every card, such as a fixed height.

API `CardStackItem`:

### Carousel

- Level: Organism
- Category: Content
- Status: Experimental
- Import: `@oration/canon/components/carousel`
- Exports: `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselNext`, `CarouselPrevious`
- Docs: /design/components/carousel

Carousel is a scroller of slides with Previous and Next buttons, built on Embla. It drags with a pointer or a finger, snaps to each slide and moves with the arrow keys when focus is inside. It suits a short, optional set of things of the same kind: upcoming payment runs, a tour of a new feature, sample remittance templates. Nothing in the product uses it yet. The common mistake is hiding content people need inside one: whatever is on slide four is effectively invisible, so anything people must see or compare belongs in a list or a grid.

When to use:
- For a short, optional set of same-shaped cards in a narrow space, such as the next four payment runs on an overview.
- For images or previews people flick through, such as remittance email templates.
- When more than one card fits per view and the rest can scroll in, with part of the next card showing.

When not to use:
- For items people compare or act on. Show them all in a list or table. Use /design/components/item instead.
- For pages read in order in a modal, such as what's new. Use /design/components/stacked-dialog instead.
- For a pile that says there are more without showing them. Use /design/components/card-stack instead.
- For switching between views of the same content. Use /design/components/tabs instead.

Rules:
- The Hairline-and-Lift Rule: Slides that are cards use Card White with the hairline lift. The carousel itself draws no surface.
- No autoplay: Slides move only when someone moves them. Embla's autoplay plugin isn't installed, and motion that starts on its own breaks the reduced-motion story.

Anatomy:
- Viewport: `CarouselContent`: an `overflow-hidden` box around a flex track with a -16px leading margin.
- Slide: `CarouselItem`: 16px leading padding (the gutter) and `basis-full`. Pass `basis-1/2` or `basis-1/3` for more per view.
- Next slide: Clipped by the viewport. Showing part of it tells people there's more.
- Previous: `CarouselPrevious`: a 28px round outline icon button 48px outside the leading edge, named Previous slide.
- Next: `CarouselNext`: the same, 48px outside the trailing edge, named Next slide.

States:
- At the start: Previous is disabled at 50% opacity, unless `loop` is set.
- In the middle: Both buttons are enabled.
- At the end: Next is disabled.
- Dragging: The track follows the pointer and snaps to the nearest slide on release, with Embla's own easing.
- Button hover and focus: The outline button states: Well Gray on hover, the indigo ring on keyboard focus.

Behavior:
- Drag with a mouse, pen or finger; the buttons scroll by one slide, or by a group of slides with `opts={{ slidesToScroll: 'auto' }}`.
- The left and right arrow keys move to the previous and next slide when focus is anywhere inside the carousel. That includes inputs inside slides, where the arrow keys stop moving the caret.
- `opts` goes straight to Embla: `align` (`"start"`, `"center"` or `"end"`), `loop`, `slidesToScroll`, `dragFree` and the rest. `axis` is set from `orientation`.
- `setApi` hands you the Embla API, for a counter (`api.selectedScrollSnap()`, `api.scrollSnapList()`) or for jumping with `api.scrollTo(index)`. Listen to `select` and clean up with `off`.
- `orientation="vertical"` stacks the track; give `CarouselContent` a fixed height. The buttons move above and below and rotate 90 degrees.
- The buttons sit outside the carousel's box. Leave 48px on each side (`mx-12`) or move them in with `className`.
- Inside the carousel, call `useCarousel()` to build custom controls from `scrollPrev`, `scrollNext`, `canScrollPrev` and `canScrollNext`.

Do and don't:
- Do: Show part of the next slide and a position such as 2 of 5, so people know there's more and where they are.
- Don't: Show exactly one full-width slide with nothing to say more exist. Most people never press Next.
- Do: Name the carousel with `aria-label`, such as Upcoming payment runs.
- Don't: Leave the region unnamed. Screen readers announce an anonymous carousel.
- Do: Put anything people must see or compare in a list or grid.
- Don't: Hide a failed payment run on slide four of a carousel on the overview.

Content:
- Name the set in a heading above it and in `aria-label`: Upcoming payment runs.
- Keep slides parallel: the same fields in the same order, so flicking compares like with like.
- A counter reads 2 of 5, in tabular figures.

Accessibility:
- The root is `role="region"` with `aria-roledescription="carousel"`; give it an `aria-label`, because a region needs a name.
- Each slide is `role="group"` with `aria-roledescription="slide"`. Add `aria-label="2 of 5"` or the slide's title to each one.
- Previous and Next are buttons with hidden names, Previous slide and Next slide, and are disabled at the ends.
- Slide changes aren't announced. Add a counter with `aria-live="polite"` if position matters.
- Embla doesn't animate with CSS, so reduced-motion settings don't shorten its scroll. Keep jumps short.
- ←: Previous slide, when focus is inside.
- →: Next slide, when focus is inside.
- Tab: Moves through slide content and the buttons.
- Enter: Activates the focused button.

Known gaps (follow the system, not the gap):
- No file in `apps/web` imports it. Hence experimental.
- The buttons are `rounded-full`. DESIGN.md gives buttons 10px corners and keeps round for dots, avatars, meters and switches.
- Previous and Next are icon-only with no tooltip, unlike other icon-only buttons in the suite.
- The buttons sit 48px outside the carousel's box, so at narrow widths they fall off-screen unless the layout reserves the space.
- The arrow-key handler runs in the capture phase on the whole region and always prevents the default, so the left and right arrows don't move the caret in inputs inside a slide. In vertical carousels, up and down do nothing.
- The region has no accessible name by default, slides aren't labelled with their position, and slide changes aren't announced.

API `Carousel` (extends `<div>`):
- `opts?: EmblaOptionsType`. Embla options: `align`, `loop`, `slidesToScroll`, `dragFree`…
- `plugins?: EmblaPluginType[]`. Embla plugins. None are installed in the repo.
- `orientation?: "horizontal" | "vertical"` = "horizontal". Scroll axis.
- `setApi?: (api: CarouselApi) => void`. Receives the Embla API once it's ready.

API `CarouselContent` (extends `<div>`):

API `CarouselItem` (extends `<div>`):

API `useCarousel`:

API `CarouselApi`:

### Chart

- Level: Organism
- Category: Data display
- Status: Stable
- Import: `@oration/canon/components/chart`
- Exports: `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartConfig`
- Docs: /design/components/chart

Chart is the wrapper every Recharts chart in Oration sits in. `ChartContainer` takes a `config` that names each series and gives it a color, writes those colors as `--color-<key>` variables, makes the chart responsive and restyles Recharts' grid, cursor and ticks with Canon tokens; `ChartTooltipContent` and `ChartLegendContent` draw the tooltip and legend from the same config. The common mistake is reaching for brand or tag colors: series take the chart set in order, starting with Chart Ink, and nothing else.

When to use:
- For a trend over time that people read for its shape: invoices processed per week, days to pay, payments sent per day.
- To compare a handful of categories by magnitude, such as spend by supplier, as a vertical or horizontal bar chart.
- For part-to-whole over time, as a stacked bar or stacked area: payments by method per payment run.
- In report panels and settings pages where the chart sits under a title and a one-sentence takeaway.
- When people need a tooltip with exact values on hover or with the arrow keys.

When not to use:
- For a sparkline in a table cell, a stat or a list row. It has no axes and needs no container. Use /design/components/mini-chart instead.
- For a single ratio, such as 86% auto-matched. Use /design/components/radial-chart instead.
- For one magnitude against a limit, such as credits used this period. Meters use ink steps, not the chart set. Use /design/components/meter instead.
- For a status history, one tick per period. Use /design/components/health-bar instead.
- For two to five headline numbers. Don't chart a number that reads fine as text. Use /design/components/inline-stat-strip instead.
- When people need to read, sort or export exact values. Use /design/components/table instead.

Rules:
- The chart set: Series take `--chart-1` to `--chart-5` in order: Chart Ink, Chart Teal, Chart Amber, Chart Magenta, then Chart Soft Ink. Most charts lead with Chart Ink, and a single-series chart is always Chart Ink. The chart set is used inside the chart container only.
- The Option Hue Rule: The ten tag hues belong to option values and identity tints. They never color a chart series, even when the series is a stage or tier that has a tag color elsewhere.
- The Quiet Indigo Rule: Indigo never fills data. A series is not indigo because it is the important one; lead with Chart Ink instead.
- No hero-metric cards: Don't build grids of big numbers with tiny labels and trend chips. Show metrics as a stat strip, rows, a table or a real chart with axes.

Anatomy:
- Container: `ChartContainer`: a `data-chart` div that holds the config, the generated color variables and Recharts' `ResponsiveContainer`. Text is 12px.
- Legend: `ChartLegendContent`: an 8px swatch and the config `label` for each series, centered, 16px apart, 12px from the plot.
- Value axis: Ticks in Slate Meta. Product charts drop the tick and axis lines (`tickLine={false} axisLine={false}`) and give the axis a fixed `width`.
- Grid: Horizontal rules only (`vertical={false}`), drawn in Hairline at 50% by the container's styles.
- Series: Lines, bars or areas filled with `var(--color-<key>)`. Lines are 2px with no dots; bars get 3px corners on their outer end.
- Tooltip: `ChartTooltipContent`: the category label, then one row per series with its indicator, label and value in tabular figures.
- Category axis: Dates or names along the base, 8px from the plot, thinned with `minTickGap` so labels never collide.

States:
- Rest: Series, grid, axes and legend. No tooltip.
- Hover: The tooltip follows the nearest category. Line and area charts draw a Hairline cursor rule; bar charts fill the category band with Well Gray (product charts pass `opacity: 0.5`). The hovered point on a line shows its active dot.
- Keyboard focus: Recharts makes the chart a tab stop. Arrow keys move the tooltip between categories. The container hides the focus outline, so focus is not visible.
- Entering: Series animate in on mount. Recharts defaults to 1500ms for lines and areas and 400ms for bars; product charts use 250ms ease-out and turn it off for reduced motion.
- Loading: Not built in. Draw a Skeleton at the chart's height so the panel doesn't jump when data arrives.
- Empty: Not built in. Replace the chart with a sentence that says why there's nothing and what happens next; don't draw empty axes.

Behavior:
- Each `config` key becomes a CSS variable on the container: `{ ach: { color: "var(--chart-1)" } }` gives you `var(--color-ach)` for `fill` and `stroke`. Config keys must match your `dataKey`s so the tooltip and legend can find their labels.
- Use `color: "var(--chart-n)"` so the series follows the theme. A `theme: { light, dark }` map writes raw values per theme, keyed on a `.dark` ancestor.
- The chart fills its container's width and needs a height. The default is `aspect-video`; product charts use `aspect-auto` with `h-56` or an explicit `style.height` for horizontal bars sized by row count.
- `initialDimension` (320 by 200) is the size used before the container is measured, including on the server.
- The tooltip label comes from `labelKey`, then the category value (mapped through `config` if it matches a key). `labelFormatter` rewrites it, for example to Week of Sep 21.
- Values print with `toLocaleString()`. For currency or units pass `formatter`, which replaces the whole row, indicator included.
- With one series and a `line` or `dashed` indicator, the label nests beside the value instead of sitting above it.
- `ChartTooltip` and `ChartLegend` are Recharts' `Tooltip` and `Legend` unchanged, so `cursor`, `defaultIndex`, `verticalAlign` and the rest work as documented by Recharts.

Do and don't:
- Do: Color series from the chart set in order, starting with Chart Ink.
- Don't: Color series with indigo, red or tag hues. Red reads as an error and indigo as selection.
- Do: Keep the grid to horizontal hairlines and drop tick and axis lines.
- Don't: Leave Recharts' defaults: a dashed grid in both directions, axis lines, tick marks, dots and a heavy stroke.

Content:
- Put a title and a one-sentence takeaway above the chart that says what changed: Auto-match cleared 86% of invoices last week, up from 74% in early July.
- Series labels in `config` are nouns in sentence case: Auto-matched, Sent to review, Virtual card.
- Format axis ticks compactly ($184K, 30d) and tooltip values in full ($184,200).
- Name time categories the way people say them: Sep 21, and Week of Sep 21 in the tooltip.
- Label reference lines with what they mean: Net 30, Target.
- Don't add a legend for a single series; the title already names it.

Accessibility:
- Recharts' accessibility layer is on by default: the chart surface is `role="application"` with `tabIndex={0}`, and arrow keys move the tooltip. Pass `accessibilityLayer` explicitly if you want it to be obvious in code.
- Give the chart a written takeaway beside it. The SVG has no accessible name unless you pass `title` and `desc` to the chart.
- Never rely on color alone. The legend and tooltip name each series, and stacked charts keep the same order in the legend as in the stack.
- The set has five colors and two of them are inks, which differ mainly in lightness. Past three or four series, group the rest into Other rather than asking people to tell close colors apart.
- Turn off series animation for reduced motion with `isAnimationActive={!useReducedMotion()}`. The container does not do it for you.
- The focus outline on the chart is hidden by the container's styles; keyboard users can tab to it but can't see that they have.
- Tab: Focuses the chart.
- →: Moves the tooltip to the next category.
- ←: Moves the tooltip to the previous category.

Known gaps (follow the system, not the gap):
- The tooltip is `bg-background` with `border-border/50` and `shadow-xl`, not Popover White and the popover shadow every other floating surface uses.
- No reduced-motion handling. Recharts animates every series by default. Product charts import a `useChartMotion` helper from `apps/web/src/components/reports/report-parts.tsx` (250ms ease-out, off when reduced); it isn't in `packages/canon`.
- `[&_.recharts-surface]:outline-hidden` hides the focus outline on a chart Recharts makes focusable, so keyboard focus is invisible.
- There is no value formatter. `formatter` replaces the whole row, so reports, analytics and usage charts rebuild it with a hand-rolled `TooltipRow` (mono value, 10px swatch).
- The default `aspect-video` is overridden by every product use.
- The grid, cursor and dot styles match Recharts' default `#ccc` and `#fff` strokes. A `CartesianGrid` with a custom `stroke` loses the Hairline mapping.
- Some product charts skip ahead in the chart set: AI call containment pairs Chart Ink with Chart Soft Ink, and latency pairs it with Chart Amber.
- A config entry without a `label` renders a legend swatch with no text.

API `ChartContainer` (extends <div>):
- `config: ChartConfig`. One entry per series key: `label`, optional `icon`, and either `color` or `theme`.
- `children: ResponsiveContainer children`. A single Recharts chart: `LineChart`, `BarChart`, `AreaChart` and so on.
- `id?: string`. Used for `data-chart="chart-<id>"`. Defaults to a `useId()` value.
- `initialDimension?: { width: number; height: number }` = { width: 320, height: 200 }. Size used before the container has been measured.
- `className?: string`. Merged onto the container. Set `aspect-auto` and a height, or keep the default `aspect-video`.

API `ChartConfig`:
- `[key]?: { label?: ReactNode; icon?: ComponentType } & ({ color?: string } | { theme: { light: string; dark: string } })`. Keys match the series `dataKey`. `color` and `theme` are mutually exclusive.

API `ChartTooltip` (extends Recharts Tooltip):
- `content?: ReactElement`. Pass `<ChartTooltipContent />`.
- `cursor?: boolean | SVGProps` = true. The hover cursor. Product bar charts pass `{ fill: "var(--muted)", opacity: 0.5 }`.
- `defaultIndex?: number`. Shows the tooltip at this category on first render.

API `ChartTooltipContent` (extends Recharts Tooltip props and <div> props):
- `indicator?: "dot" | "line" | "dashed"` = "dot". The swatch beside each row.
- `hideLabel?: boolean` = false. Hides the category label.
- `hideIndicator?: boolean` = false. Hides the swatches.
- `labelFormatter?: (label, payload) => ReactNode`. Rewrites the label, for example to add Week of.
- `formatter?: (value, name, item, index, payload) => ReactNode`. Replaces each row entirely, including the indicator. Use it for currency and units.
- `labelKey?: string`. Config key to read the label from.
- `nameKey?: string`. Payload field to look up each row's config entry, when it isn't the `dataKey`.
- `color?: string`. Overrides every indicator color.
- `labelClassName?: string`. Classes for the label.
- `className?: string`. Merged onto the tooltip surface.

API `ChartLegend` (extends Recharts Legend):
- `content?: ReactElement`. Pass `<ChartLegendContent />`.
- `verticalAlign?: "top" | "middle" | "bottom"` = "bottom". Where the legend sits. Passed through to the content, which flips its padding.

API `ChartLegendContent` (extends Recharts legend content props and <div> props):
- `hideIcon?: boolean` = false. Hides the config `icon` and shows the swatch instead.
- `nameKey?: string`. Config key to read each label from.
- `verticalAlign?: "top" | "bottom"` = "bottom". Puts 12px padding below (top) or above (bottom).
- `className?: string`. Merged onto the legend row.

API `ChartStyle`:
- `id: string`. The container's `data-chart` value.
- `config: ChartConfig`. The config to write.

### Flow canvas

- Level: Organism
- Category: Editors
- Status: Stable
- Import: `@oration/canon/components/flow`
- Exports: `FlowCanvas`, `FlowNodeCard`, `FlowEdge`, `FlowRunBadge`
- Docs: /design/components/flow

Flow canvas is the surface for building and test-running automations: a React Flow canvas on the dotted grid, 288px node cards, smooth-step edges and run states that light up step by step. `FlowCanvas` wraps React Flow with Canon's grid, controls and minimap, `FlowNodeCard` is what your custom node types render, and `FlowEdge` is the edge type. The usual mistake is treating run state as a color: every ring travels with a labelled badge, and the marching indigo dash belongs only to the edge the run is on right now.

When to use:
- For a multi-step automation people build and read as a graph: Invoice received, Match PO, Approve under $5k, Schedule payment.
- To show a test run live, node by node, with the active edge marching.
- When the logic branches: a branch node with Yes and No outputs and labelled edges.
- For voice-agent flows and procedures, where each node is a stage of the conversation.
- To show one node card outside the canvas, such as in a palette preview or a run summary, with `target={false}` and `sourceHandles={[]}`.

When not to use:
- For a fixed sequence someone completes once, like supplier onboarding. Use /design/components/stepper instead.
- For a record of what already happened, such as a run log or an audit trail. Use /design/components/timeline instead.
- For an ordered list people reorder by dragging, with no branches. Use /design/components/sortable-list instead.
- For an agent's progress through a plan, shown as checkable tasks. Use /design/components/task-list instead.
- For where the milliseconds went in one call. Use /design/components/latency-timeline instead.
- For the whole editor page, with palette, inspector and test run. Use /design/templates/canvas instead.

Rules:
- Workflow Canvas (signature): Nodes are 288px cards with container corners and hairline lift, a 32px Well Gray icon tile, a 12px category with its run badge, a 13px medium title and a caption description. Handles are 10px white circles with a 1.5px Firm Hairline stroke. Edges are 1.5px Firm Hairline smooth-steps. Zoom controls and the minimap sit in 10px-corner hairline-lift boxes.
- The Label-Beside-Color Rule: A run ring never stands alone. Running, Passed, Failed, Queued and Skipped are always written in the node's badge, so a test run reads in grayscale and to a screen reader.
- One marching edge: Set `active` only on the edge the run is traversing. The dashed indigo march means work in progress now; idle edges stay Firm Hairline, and selection turns an edge indigo without the dash.
- The Option Hue Rule: The icon tile is Well Gray. Tint it through `iconClassName` only for identity, such as an agent's own color, never to color-code node kinds like triggers or integrations.

Anatomy:
- Card: 288px wide (`w-72`), `rounded-xl` on the card surface with `shadow-border`. Rings for selection and run state are drawn on it.
- Target handle: A 10px circle with a 1.5px Firm Hairline stroke at the top center. `target={false}` removes it for triggers.
- Icon tile: 32px, 10px corners, Well Gray with a 16px icon. Decorative; `iconClassName` overrides the tint.
- Category: 12px muted text naming the kind of step: Trigger, Filter, Payments.
- Run badge: `FlowRunBadge`, pushed to the end of the category row. Nothing renders while idle.
- Title: 13px at weight 500, one line, truncates.
- Description: 12px muted text, clamped to two lines.
- Footer: Optional `children` below a hairline, for conditions or an error. Padded 12px by 8px.
- Source handles: One per entry in `sourceHandles`, spaced evenly along the bottom edge. Each `id` is the edge's `sourceHandle`.

States:
- Idle: No ring and no badge. The resting state while editing.
- Queued: No ring; a muted Queued label. The run will reach this step.
- Running: 2px Focus Indigo ring at 60% and an indigo spinner with Running. The spinner only turns when motion is allowed.
- Passed: 1px Ledger Green ring at 50% and a check with Passed. The value is `success`.
- Failed: 2px Signal Red ring at 60% and an x with Failed. The value is `error`. Put the reason in the footer.
- Skipped: The whole card fades to 60% opacity with a muted Skipped label, for steps a branch didn't take.
- Selected: 2px indigo ring from `data-selected`. It wins over the run ring's color, so a selected failed node relies on its badge.
- Edge active: 1.75px indigo dashes (5 5) that march at 0.9s linear. Under reduced motion the dashes hold still and stay indigo.
- Edge selected: Solid indigo at 1.5px. Stroke color changes over 200ms.
- Insert button hover and focus: The plus darkens to ink and scales to 1.1 on hover, 0.95 while pressed. Keyboard focus adds a 3px ring at 40%.

Behavior:
- `FlowCanvas` passes every React Flow prop through. Its defaults (hidden attribution, zoom from 0.4 to 1.6, `fitViewOptions` of 0.25 padding and zoom 1 at most) are spread first, so your props override them.
- The wrapper is `relative size-full`. Give its parent an explicit height; React Flow draws nothing in a box with no height.
- It always draws the dotted grid (18px gap, 1.2px dots in Firm Hairline) and zoom controls at the bottom left without the lock button. `minimap` adds a pannable, zoomable minimap at the bottom right; the workflows editor turns it off.
- Register the pieces once, outside render or memoized: `edgeTypes={{ default: FlowEdge }}` and a `nodeTypes` map whose components render `FlowNodeCard`. New objects on every render make React Flow warn and remount nodes.
- `FlowEdge` reads `data.active`, `data.label` and `data.onInsert`. The label chip and insert button sit at the path midpoint with `nodrag nopan`, so clicking them never pans the canvas. Drop `onInsert` while a run is in progress.
- Edges are smooth-steps with 10px bends. Stroke color eases over 200ms on the house curve, `cubic-bezier(0.23, 1, 0.32, 1)`; card rings and opacity ease over 200ms.
- Pass `selected` from `NodeProps` into the card. Branches pass `sourceHandles={[{ id: "yes" }, { id: "no" }]}` and edges pick one with `sourceHandle`.
- `FlowNodeCard` renders React Flow `Handle`s, which only work inside a node. For a static card outside the canvas, pass `target={false}` and `sourceHandles={[]}`.
- On a long page, set `preventScrolling={false}` and `zoomOnScroll={false}` so the wheel scrolls the page instead of zooming the canvas.

Do and don't:
- Do: Write the run state in the badge and the reason in the footer, so a failed step says what failed.
- Don't: Signal failure with a red ring alone. In grayscale, and to a screen reader, nothing happened.
- Do: Keep icon tiles Well Gray and let the category and title say what the step is.
- Don't: Tint every node kind its own hue. Color-coded kinds compete with the run states and break the Option Hue Rule.
- Do: Name the step for what it does: Match PO, Approve under $5k, Schedule payment.
- Don't: Use the step type as the title: Filter, Action, Step 3.

Content:
- Titles are short verb phrases in sentence case: Match PO, Schedule payment, Request approval from Maya Okafor.
- The category names the kind of step in one or two words: Trigger, Filter, Payments, Agent.
- Descriptions say what this instance does with real values: Amount is less than $5,000, not Checks a condition.
- Error footers state the problem and the fix: Connect a payment account to run this step.
- Edge labels are one word, usually Yes and No from a branch.

Accessibility:
- Give the canvas an `aria-label`, such as Invoice approval workflow. React Flow makes nodes and edges focusable and gives them a role description.
- Set `ariaLabel` on each node and edge with the step and its run state, like Match PO, passed. The card itself has no name.
- Run states are written words, so they don't depend on the ring color. The spinner and the marching dash sit behind `motion-safe`.
- The icon tile is `aria-hidden`. Handles are pointer-only: offer another way to connect steps, such as the insert button or an inspector field.
- Every insert button is named Add step here. On a canvas with several edges they all sound the same; see Known gaps.
- Tab: Moves through nodes, then edges, then the insert buttons and zoom controls.
- Enter: Selects the focused node or edge, or activates the focused insert button.
- Arrow keys: Move the selected nodes when `nodesDraggable` is on. Hold Shift to move further.
- Backspace: Deletes the selected nodes and edges. Pass `deleteKeyCode={null}` to turn this off, as the workflows editor does.

Known gaps (follow the system, not the gap):
- The insert button is 20px, as DESIGN.md specifies, which is under the 24px minimum hit area. Every one is named Add step here, with no hint of which two steps it sits between.
- `sourceHandles[].label` is in the type but never drawn. Branch labels come from the edge's `data.label` instead.
- Run state values are `success` and `error`, while the badge and DESIGN.md say Passed and Failed.
- The selected ring overrides the run ring's color, so a selected node that failed shows an indigo ring and only its badge says Failed.
- `FlowNodeCard` doesn't spread props, so it takes no `aria-*`, `data-*` or `ref`. Names have to go on the React Flow node as `ariaLabel`.
- The workflows editor tints trigger tiles with `--tag-indigo` through `iconClassName`. That color-codes a node kind; DESIGN.md specifies Well Gray tiles.
- `FlowRunBadge` isn't used on its own anywhere in the app; the run log draws its own status icons.

API `FlowCanvas` (extends React Flow `ReactFlowProps<NodeType, EdgeType>`, spread onto `<ReactFlow>`):
- `minimap?: boolean` = true. Shows the minimap at the bottom right.
- `nodes?: NodeType[]`. Controlled nodes. Pair with `onNodesChange`, or use `defaultNodes`.
- `edges?: EdgeType[]`. Controlled edges. Give them `type: "default"` and register `FlowEdge`.
- `nodeTypes?: NodeTypes`. Your node components, each rendering `FlowNodeCard`. Define once.
- `edgeTypes?: EdgeTypes`. `{ default: FlowEdge }`. Define once.
- `minZoom?: number` = 0.4. Smallest zoom.
- `maxZoom?: number` = 1.6. Largest zoom.
- `fitViewOptions?: FitViewOptions` = { padding: 0.25, maxZoom: 1 }. Used by `fitView` and the fit button. Never zooms past 100% by default.
- `proOptions?: ProOptions` = { hideAttribution: true }. Hides the React Flow attribution.
- `className?: string`. On the wrapping `div`, which is `relative size-full`.
- `children?: ReactNode`. Rendered inside React Flow after the grid, controls and minimap, e.g. a `<Panel>`.

API `FlowNodeCard` (extends Doesn't spread props; renders `<div data-slot="flow-node" data-run data-selected>`):
- `icon: ReactNode`. A Lucide icon or avatar for the 32px tile. Sized to 16px.
- `iconClassName?: string`. Overrides the tile's Well Gray, for identity tints only.
- `category: string`. The kind of step, above the title.
- `title: string`. The step's name. Truncates to one line.
- `description?: string`. What this step does. Clamps to two lines.
- `selected?: boolean`. Draws the 2px indigo ring. Pass `selected` from `NodeProps`.
- `run?: FlowRunState` = "idle". Run state: ring, opacity and badge.
- `sourceHandles?: { id: string; label?: string }[]` = [{ id: "out" }]. Outputs along the bottom edge. `[]` for none. `label` is not drawn.
- `target?: boolean` = true. Draws the input handle. `false` for triggers and static cards.
- `children?: ReactNode`. Footer content below a hairline: conditions, an error.
- `className?: string`. Merged onto the card, e.g. a drop-target ring.

API `FlowEdge` (extends React Flow `EdgeProps<Edge<FlowEdgeData>>`):
- `data.active?: boolean`. Dashed indigo, 1.75px, marching. Only for the edge a run is on.
- `data.label?: string`. A small chip at the midpoint, like Yes or No.
- `data.onInsert?: (edgeId: string) => void`. Shows the 20px plus at the midpoint. Called with the edge id.
- `selected?: boolean`. From React Flow. Turns the stroke indigo.
- `markerEnd?: string`. From React Flow, passed to the path. The product draws none.

API `FlowRunBadge`:
- `run: FlowRunState`. Which state to show.

API `FlowEdgeData`:
- `FlowEdgeData?: { label?: string; active?: boolean; onInsert?: (edgeId: string) => void }`. The edge `data` that `FlowEdge` reads.

### Prompt editor

- Level: Organism
- Category: Editors
- Status: Beta
- Import: `@oration/canon/components/prompt-editor/prompt-editor`
- Exports: `PromptEditor`, `PromptEditorSkeleton`, `VariablesPanel`, `extractVariables`
- Docs: /design/components/prompt-editor

Prompt editor is where people write the long instructions a voice agent follows, such as the system prompt for Nora, Cedarline's supplier support agent. It is a Tiptap editor that stores plain text with light Markdown: `{{variables}}` become chips, `/` opens blocks and AI actions, selecting text offers AI rewrites as inline diffs, and the footer counts changes against the published version. The thing people get wrong is hard-coding per-call facts like a supplier's name into the prose; anything that changes per call belongs in a variable that is defined and described.

When to use:
- For an agent's system prompt, a procedure's instructions or a skill's body: long text the model reads.
- When the text references call-time values such as `{{supplier_name}}`, `{{invoice_number}}` or `{{payment_date}}`.
- When edits are drafted against a published version and people need to see what changed before publishing.
- When AI help (rewrite, shorten, add guardrails, translate) should arrive as a reviewable suggestion, not a silent overwrite.
- With `toolbar={false}` for a shorter templated message, like the first line the agent says.

When not to use:
- For a short single-line value, such as a variable's example. Use /design/components/input instead.
- For a plain note or description without variables or formatting. Use /design/components/textarea instead.
- For a chat message someone sends to an assistant. Use /design/components/prompt-bar instead.
- For showing code or a JSON payload that people read but don't write. Use /design/components/code-block instead.
- For comparing two finished versions side by side. Use /design/components/diff instead.

Rules:
- Suggestions, not overwrites: Every AI action runs as a proposal. The editor locks, the suggestion streams in beside the text it would replace, and nothing changes until someone accepts it. Accepting is one undoable step.
- The Label-Beside-Color Rule: Undefined variables are a warning tint plus an icon and a tooltip, and the change dot in the footer always sits beside its sentence, so neither depends on color.
- The Tint Well Rule: The variables panel's undefined warning sits in a 10px-corner warning well (`bg-warning/10`), not a bordered alert box.

Anatomy:
- Frame: A card surface with `rounded-xl` and `shadow-border`. While the text has focus it gains a 3px Focus Indigo ring at 20%.
- Text style menu: Text or Heading 1 to 3, in a 108px ghost trigger at the start of the toolbar.
- Formatting tools: 28px ghost icon buttons with tooltips and shortcuts: bold, italic, inline code, lists, quote, code block, undo and redo. Pressed tools fill with `--accent`.
- Variable button: Inserts `{{` at the caret, which opens the variable menu.
- Toolbar actions: `toolbarActions`, after a divider at the end of the toolbar.
- Writing area: 14px text on 24px lines (16px on small screens), 16px by 12px padding. Grows from `minHeight` and scrolls past `maxHeight`.
- Variable chip: An inline atom that serializes to `{{name}}`. Gray for custom, teal for system, a warning tint for undefined names.
- Change status: A 6px dot (indigo when changed) beside how many lines and words moved from `baseline`. Hidden without a baseline.
- View changes: Opens a line diff against the baseline. Only shown when something changed.
- Word and token count: Live word count and a rough token estimate, at the end of the footer.

States:
- Loading: Before Tiptap mounts, the frame shows four skeleton lines at `minHeight`. Use `PromptEditorSkeleton` while the prompt itself loads.
- Empty: The `placeholder` shows in muted text. Empty lines in a focused editor hint: Type / for commands or {{ for a variable.
- Focused: A 3px ring at 20% around the whole frame.
- Slash menu open: A popover of Blocks and AI actions under the caret, filtered as you type. The highlight follows the arrow keys.
- Variable menu open: Custom variables, then system variables, then Create name when the typed name is new and valid.
- Text selected: The AI bubble appears above the selection after 120ms: Ask AI, Rewrite, Shorten, Expand, Translate and Change tone.
- Suggestion streaming: The editor is locked. New text streams in green beside the struck original with a pulsing caret, and a Stop button.
- Suggestion ready: An inline word diff with Accept (focused), Reject and Try again. Whole-document actions replace the blocks with the diff.
- Suggestion failed or empty: Couldn't get a suggestion. with Try again and Dismiss, or No changes suggested. with Dismiss.
- Changed: Indigo dot and 3 lines and 12 words changed, with View changes. Unchanged reads Matches the published version.
- Undefined variable: The chip takes the warning tint, an icon and a tooltip saying it will be blank on calls.
- Disabled: The whole frame drops to 60% opacity, the text isn't editable and every toolbar tool is disabled.

Behavior:
- `value` and `onChange` are plain text. Chips serialize to `{{name}}`, and the Markdown subset (`#` headings, `-` and `1.` lists with two-space nesting, `>` quotes, fenced code, `---`, `bold`, `_italic_`, `` `code` ``) round-trips without escaping, so the model sees exactly what was written.
- It is controlled. A new `value` from outside replaces the document without calling `onChange`; values the editor just emitted are ignored.
- Typing `{{` opens the variable menu, matching names and descriptions. Picking one inserts the chip and a space. A new snake_case name offers Create, which inserts the chip and calls `onCreateVariable`.
- Typing a full `{{name}}` or pasting text that contains one turns it into a chip.
- `/` after a space or at the start of a line opens Blocks (Heading, Bulleted list, Numbered list, Quote, Divider, Variable) and AI (Write a section, Improve writing, Add guardrails, Summarize, Translate).
- Menus keep focus in the editor: arrows move the highlight, Enter or Tab picks, Escape closes. They enter with a fast spring.
- AI actions call `onAIAction` with the action, the selection and the whole document as text. The full answer is awaited, then streamed in a few words at a time. Without a handler, built-in simulated answers run, which is what these demos use unless noted.
- While a suggestion is open the editor is read-only. Accept inserts it as one undoable transaction and returns focus to the text; Reject restores focus without changes.
- The footer diff uses a deferred value, so typing stays smooth on long prompts. View changes folds unchanged lines, keeping two lines of context around each change.
- The toolbar is one tab stop and sticks to the top of the frame's scroll container. The `ref` handle offers `focus()`, `insertVariable(name)` and `openVariableMenu()`, which a variables panel uses to insert at the caret.

Do and don't:
- Do: Put anything that changes per call in a variable: Greet {{supplier_name}} and confirm {{invoice_number}}.
- Don't: Hard-code one supplier's facts into the prompt. Every other call gets Northwind Freight's invoice.
- Do: Structure long prompts with headings and numbered steps the model can follow.
- Don't: Write one dense paragraph. People can't scan it, and changes are hard to review in the diff.
- Do: Define and describe every variable the prompt uses, so the panel has nothing to warn about.
- Don't: Leave names undefined. They are blank on every call, and the agent says nothing where the value should be.

Content:
- Write the prompt to the agent in the second person: You are Nora, the supplier support agent for Cedarline.
- Use `#` headings for sections (Who you are, How you sound, What you do, Guardrails) and numbered lists for steps in order.
- Variable names are lowercase snake_case nouns: `supplier_name`, `invoice_number`, `payment_date`.
- Describe each variable in one sentence that says where the value comes from, and give a realistic example such as INV-20931.
- The placeholder says what to write, not how the editor works: the default is Describe who the agent is, what it should do and how it should sound…
- Set `baselineLabel` to the version people know: published version 4 reads as Matches the published version 4.

Accessibility:
- The writing area is `role="textbox"` with `aria-multiline`. Name it with `aria-label` (default Prompt) or point `aria-labelledby` at a visible heading.
- A visually hidden hint, linked by `aria-describedby`, explains `/`, `{{`, AI rewrites and the ⌘J or Ctrl J shortcut. Your own `aria-describedby` is appended to it.
- While a menu is open the editor carries `aria-expanded`, `aria-controls`, `aria-autocomplete="list"` and `aria-activedescendant` pointing at the highlighted option, and a live region announces the count.
- The AI bubble is a `role="toolbar"` with arrow-key movement. Suggestions are a labelled group; added and removed words carry visually hidden Added and Removed prefixes, and a live region says when a suggestion is ready.
- Undefined variables carry an icon and a tooltip, not only the warning tint. The footer dot is `aria-hidden`; its sentence carries the meaning.
- The streaming caret pulses only when motion is allowed.
- /: Opens blocks and AI actions after a space or at the start of a line.
- { + {: Opens the variable menu.
- ↑ + ↓: Move the highlight in an open menu.
- Enter: Picks the highlighted item. Tab does the same.
- Esc: Closes a menu, leaves the AI bubble, or rejects an open suggestion.
- ⌘ + J: With text selected, moves focus into the AI bubble. Ctrl J on Windows.
- ← + →: Move between toolbar tools or AI bubble actions. Home and End jump in the toolbar.
- ⌘ + Enter: Accepts a ready suggestion.
- ⌘ + B: Bold. ⌘I italic, ⌘E inline code, ⌘⇧8 bulleted list, ⌘⇧7 numbered list.
- ⌘ + Z: Undo. ⌘⇧Z redo.

Known gaps (follow the system, not the gap):
- The AI bubble's buttons don't set `type="button"`. The bubble is appended inside the editor, so inside a `<form>` choosing Rewrite or Shorten submits the form.
- The AI bubble's buttons and the toolbar's Variable button pass `text-13` next to a text color through Button's `cn`, so the 13px size is dropped and they render at 14px.
- `onAIAction` gets no `AbortSignal`. Stop ends the local stream, but the request keeps running.
- The suggestion hint reads ⌘↵ to accept, Esc to reject on every platform; the toolbar detects Windows and shows Ctrl, the hint doesn't.
- Try again in a ready suggestion is an icon button named with `title`, not a tooltip.
- `disabled` dims the whole frame to 60%, text included. There is no read-only mode at full contrast for people who can read but not edit.
- The menus' entrance spring and the AI bubble have no reduced-motion check of their own. The app-wide `MotionConfig` drops their transforms, but their fades still play.
- The token count is characters divided by four, a rough estimate rather than the model's tokenizer.
- `PromptEditorSkeleton` takes a number for `minHeight` while `PromptEditor` also accepts strings.

API `PromptEditor` (extends Doesn't spread props; renders `<div data-slot="prompt-editor">`):
- `value: string`. Prompt text with light Markdown and `{{variables}}`.
- `onChange: (text: string) => void`. Called with plain text on every edit.
- `variables: PromptVariable[]`. Known variables, for the menu, chip states and tooltips.
- `baseline?: string`. The published text. Enables the change count and View changes.
- `baselineLabel?: string` = "published version". Names the baseline in the footer and the diff dialog.
- `onCreateVariable?: (name: string) => void`. Called when someone creates a variable from the `{{` menu. The chip is inserted either way.
- `onAIAction?: (request: AIActionRequest) => Promise<string>`. Runs an AI action and resolves with the replacement text. Without it, simulated answers run.
- `placeholder?: string` = "Describe who the agent is, what it should do and how it should sound…". Shown while the document is empty.
- `toolbar?: boolean` = true. Shows the formatting toolbar.
- `toolbarActions?: ReactNode`. Extra controls at the end of the toolbar.
- `minHeight?: number | string` = 280. Height of the writing area, like 240 or "18rem".
- `maxHeight?: number | string`. Past this height the writing area scrolls.
- `id?: string`. Set on the writing area, for a `<label htmlFor>`.
- `aria-label?: string` = "Prompt". Name of the writing area.
- `aria-labelledby?: string`. Id of a visible heading that names the writing area.
- `aria-describedby?: string`. Added after the built-in keyboard hint.
- `disabled?: boolean` = false. Read-only text, disabled toolbar, 60% opacity.
- `ref?: Ref<PromptEditorHandle>`. Imperative handle: `focus`, `insertVariable`, `openVariableMenu`.
- `className?: string`. Merged onto the frame.

API `PromptEditorHandle`:
- `focus?: () => void`. Focuses the writing area.
- `insertVariable?: (name: string) => void`. Inserts a chip at the caret.
- `openVariableMenu?: () => void`. Types `{{` at the caret, which opens the variable menu.

API `PromptVariable`:
- `name: string`. snake_case name, without braces.
- `description?: string`. Shown in the menu, the chip tooltip and the panel.
- `example?: string`. A realistic value, shown beside the description.
- `kind?: "custom" | "system"` = "custom". System variables are filled in at call time and drawn teal.

API `AIActionRequest`:
- `kind: "write" | "improve" | "guardrails" | "summarize" | "translate" | "rewrite" | "shorten" | "expand" | "tone" | "custom"`. Which action ran.
- `instruction?: string`. Free text for write and custom, the language for translate, the tone for tone.
- `selection?: string`. The selected text, when the action runs on a selection.
- `document: string`. The whole prompt as text, with variables as `{{name}}`.

API `VariablesPanel` (extends Doesn't spread props; renders `<section aria-labelledby>`):
- `variables: PromptVariable[]`. Defined variables, custom and system.
- `usedNames: string[]`. Every `{{name}}` in the prompt, repeats included.
- `onInsert?: (name: string) => void`. Shows an insert button on each row.
- `onCreate?: (name?: string) => void`. Shows New variable, and Define beside each undefined name (called with that name).
- `onEdit?: (variable: PromptVariable) => void`. Shows an edit button on custom rows.
- `title?: string` = "Variables". The panel heading.
- `className?: string`. Merged onto the section.

API `PromptEditorSkeleton`:
- `toolbar?: boolean` = true. Draws a toolbar row.
- `minHeight?: number` = 280. Match the editor's `minHeight`.
- `className?: string`. Merged onto the frame.

API `extractVariables`:
- `text: string`. Prompt text.

API `docToText`:
- `doc: JSONContent`. A Tiptap document.

API `textToDoc`:
- `text: string`. Prompt text.

### JSON schema builder

- Level: Organism
- Category: Editors
- Status: Beta
- Import: `@oration/canon/components/json-schema-builder`
- Exports: `JsonSchemaBuilder`, `toJsonSchema`, `createSchemaProperty`
- Docs: /design/components/json-schema-builder

JSON schema builder edits the parameters a tool accepts, or the data an agent pulls out of a call, as a tree of named and typed fields, and shows the JSON Schema it produces. In Oration it defines tools like `get_payment_status` and post-call extraction. The part people skip is the description: the model reads it to decide what to pass, so a field without one is a guess.

When to use:
- To define the input of a tool an agent calls, such as `get_payment_status` with `invoice_number`, `supplier_id` and `include_remittance`.
- To define what an agent extracts from a call: a dispute reason, a promised payment date, the invoices discussed.
- When people who don't write JSON need to shape a schema, including enums, lists and nested objects.
- When the generated schema should be readable and copyable in the same place.

When not to use:
- For flat string pairs such as HTTP headers or metadata. Use /design/components/key-value-editor instead.
- For a form people fill in. Build the fields themselves. Use /design/components/field instead.
- For showing a schema or payload people read but don't edit. Use /design/components/code-block instead.
- For a single list of allowed values on its own. Use /design/components/tag-input instead.

Rules:
- Describe every field: The description is the instruction the model reads. Say what the value is, where it comes from and give an example: The invoice number the supplier reads out, like INV-20931.
- Names are snake_case: The name input converts spaces, hyphens and camelCase humps to underscores as people type, and anything outside lowercase letters, digits and underscores is flagged inline.
- The Tint Well Rule: The empty state is a Well Gray well (`rounded-[10px] bg-muted/70`) with one outline button, not a dashed box.

Anatomy:
- Field count: 13px muted text, tabular: No fields, 1 field, 3 fields.
- View switch: A segmented control named Schema view with Fields and JSON.
- Drag handle: From Sortable list, at the start of each row. Hidden while disabled.
- Name: A mono input with the placeholder `field_name`. Turns red with a message when invalid or repeated.
- Type: A 120px select with an icon per type: String, Number, Integer, Boolean, Enum, Array, Object.
- Required: A small switch with a visible Required label.
- More actions: Move up, Move down, Duplicate and a destructive Delete.
- Description: An input under the name, placeholder What should the agent capture here?, with an optional action beside it.
- Nested guide: A 1px hairline on the left that indents an object's fields and an array's item type.
- Add field: A small ghost button after each list.
- JSON view: A code block titled JSON Schema that scrolls past 28rem.

States:
- Empty: A well that says No fields yet. Add the first thing the agent should capture. with an outline Add field.
- Rest: Top-level rows separated by hairlines.
- Invalid name: The name input gets `aria-invalid` (red border and ring) and a red message below it, for a bad pattern or a name used twice at the same level.
- Dragging: The row lifts onto the card surface with `shadow-popover` while it moves.
- Enum: A mono tag input for the options appears under the description.
- Array: Each item is with its own type select, indented. Arrays of arrays aren't offered.
- Object: A nested field list behind the guide. Empty objects say No fields inside yet.
- Too deep: At `maxDepth`, Object is disabled in the type select with Too deep beside it.
- JSON: The generated schema in a code block, computed only while shown.
- Disabled: Every input, switch, select and button is disabled and the drag handles disappear.

Behavior:
- `value` and `onChange` are required; the builder holds no field state of its own. The view is internal unless you pass `view` and `onViewChange`.
- Adding a field focuses its name. Duplicate inserts a copy named `name_copy` below and focuses it. Delete removes the field and focuses its neighbor.
- Changing the type fills in what the new type needs: an empty option list for Enum, an empty field list for Object, a string item for Array. Nested data from the old type stays in the value but only the current type reaches the schema.
- Rows reorder by drag, by keyboard on the handle, or with Move up and Move down.
- `toJsonSchema(value)` skips unnamed fields, writes enums as strings with `enum`, adds `required` only when something is required, trims descriptions and sets `additionalProperties: false` on every object.
- Inline errors don't block anything. Call `validateSchemaProperties(value)` before saving; it returns unnamed fields, bad or repeated names and enums with no options, each with a dotted path.
- `maxDepth` counts the top level, so the default of 3 allows two levels of nesting and 1 turns objects off. `allowedTypes` limits the type select; a field keeps its current type even if it isn't allowed.
- `renderDescriptionAction` puts a control beside each description, such as an AI button that writes one from the field name.

Do and don't:
- Do: Describe each field with what it is, where it comes from and an example.
- Don't: Leave descriptions blank. The model guesses what `supplier_id` means and when to send it.
- Do: Name fields in snake_case nouns the model can match to what it hears: `invoice_number`.
- Don't: Use labels with spaces, capitals or symbols. They fail validation and read as prose, not keys.

Content:
- Field names are lowercase snake_case nouns: `invoice_number`, `supplier_id`, `include_remittance`.
- Booleans read as a yes or no question in the name: `include_remittance`, `is_disputed`.
- Descriptions are one sentence ending in a period, with an example in the supplier's words: like INV-20931.
- Enum options are snake_case values the code switches on: `wrong_amount`, `duplicate_invoice`, `missing_po`.
- Mark a field required only when the tool can't run without it.

Accessibility:
- Every control is named from its row: Field name 1, Type for invoice_number, invoice_number is required, Description for invoice_number, More actions for invoice_number.
- The visible Required text is `aria-hidden` because the switch already carries the full name.
- Name errors are linked with `aria-describedby` and mark the input `aria-invalid`.
- Nested Add field buttons name their parent: Add field to dispute.
- Focus moves to the new name after add or duplicate, and to a neighbor after delete, so keyboard users never land on nothing.
- Every drag handle is named Drag to reorder without the field's name; Move up and Move down in the row menu are the clearer keyboard path.
- Tab: Moves through handle, name, type, required, more actions and description in each row.
- Space: Toggles Required. On a handle, picks the row up or drops it.
- ↑ + ↓: Move a picked-up row, or move through an open select or menu.
- Enter: Opens the type select or the row menu, and chooses the highlighted item. In an enum, adds the typed option.
- Esc: Closes a select or menu, or cancels a drag.

Known gaps (follow the system, not the gap):
- There is no `format`, default or nullable option, so a payment date is a plain string and the description has to say the format.
- Missing descriptions aren't flagged anywhere, inline or by `validateSchemaProperties`, even though they matter most to the model.
- Delete in the row menu is immediate, with no undo, even for an object with fields inside.
- Every drag handle has the same name, Drag to reorder.
- `createSchemaProperty` makes ids with `crypto.randomUUID`, so building initial state with it on a server-rendered page gives different ids on server and client. Pass `id` yourself.
- The registry lists three exports; `validateSchemaProperties` and the `SchemaProperty`, `SchemaType` and `JsonSchema` types are exported too.

API `JsonSchemaBuilder` (extends Doesn't spread props; renders `<div data-slot="json-schema-builder">`):
- `value: SchemaProperty[]`. Top-level fields.
- `onChange: (value: SchemaProperty[]) => void`. Called with the whole tree on every edit.
- `allowedTypes?: SchemaType[]` = all seven types. Types offered in every type select.
- `maxDepth?: number` = 3. Levels of nesting, counting the top level. 1 disables objects.
- `renderDescriptionAction?: (prop: SchemaProperty, update: (next: Partial<SchemaProperty>) => void) => ReactNode`. A control beside each description, like an AI Describe button.
- `view?: "fields" | "json"`. Controls the view. Uncontrolled when omitted, starting on Fields.
- `onViewChange?: (view: "fields" | "json") => void`. Called when the view switch changes.
- `disabled?: boolean`. Disables every control and hides the drag handles.
- `className?: string`. Merged onto the root.

API `SchemaProperty`:
- `id: string`. Stable key. `createSchemaProperty` makes one.
- `name: string`. The JSON key. Empty names are skipped in the schema.
- `type: SchemaType`. One of the seven types.
- `description?: string`. What the model should pass here.
- `required?: boolean`. Adds the name to the parent's `required`.
- `enumValues?: string[]`. Options when `type` is enum.
- `items?: SchemaProperty`. Item shape when `type` is array. Its name is ignored.
- `properties?: SchemaProperty[]`. Child fields when `type` is object.

API `createSchemaProperty`:
- `partial?: Partial<SchemaProperty>` = {}. Fields to set. Pass `id` for stable ids in server-rendered pages.

API `toJsonSchema`:
- `props: SchemaProperty[]`. The builder's value.

API `validateSchemaProperties`:
- `props: SchemaProperty[]`. The builder's value.
- `path?: string` = "". Prefix for nested paths.

### Business hours picker

- Level: Organism
- Category: Inputs
- Status: Stable
- Import: `@oration/canon/components/business-hours-picker`
- Exports: `BusinessHoursPicker`, `WeekStrip`, `defaultBusinessHours`, `businessHoursPresets`
- Docs: /design/components/business-hours-picker

Business hours picker sets weekly opening hours for a queue, a phone number or an agent: a time zone, a 12 or 24-hour display, presets, and one to four ranges per day in 15-minute steps, with copy to other days and a week strip that shows the result and whether it's open now. It is controlled, so you hold a `BusinessHours` value and get a new one on every change. It flags backwards and overlapping ranges beside the day but doesn't stop them; call `hasBusinessHoursErrors` to block the save.

When to use:
- To set when a support queue, a phone number, an agent or a callback window is open.
- When hours differ by day, or a day has a break and needs two ranges.
- `WeekStrip` on its own to show a schedule read-only, such as in a queue's summary.

When not to use:
- For one time of day, such as a payment run cutoff. Use /design/components/select-field instead.
- For dates, holidays and closures. Use /design/components/calendar instead.
- For a length of time, such as a hold timeout. Use /design/components/duration-picker instead.
- For a time zone on its own. Use /design/components/timezone-select instead.

Rules:
- The Ink Fill Rule: Open ranges in the week strip are drawn in Ink 65 on a white track with a hairline. They are magnitudes of time, not status, so they stay ink.
- The Label-Beside-Color Rule: The open-now dot is never alone: green reads Open now, closes at 5:00 PM and gray reads Closed now.
- The Quiet Indigo Rule: Indigo marks the active preset (a 6% tint with a 22% inset ring) and the now marker on today's bar. Nothing else in the picker is indigo.
- The Tabular Figures Rule: Every time, in the selects, the strip and its axis, is set in tabular figures so ranges line up from day to day.

Anatomy:
- Time zone: A labelled `TimezoneSelect`. Every time on the page is in this zone.
- Time format: A segmented control, 12h or 24h, that changes display only.
- Presets: A group of 28px toggle buttons. The one matching the current days reads as pressed.
- Week strip: A Well Gray well with seven 24-hour bars, the open ranges filled, today's bar marked with the current time, and Open now or Closed now.
- Day row: A switch and the day's name in a 144px column. Off reads Closed.
- Time range: Two 116px selects, opens and closes, joined by to. A remove button appears when the day has more than one.
- Add and copy: Ghost icon buttons: add a range (up to four) and copy this day to all weekdays or every day.
- Error: A 13px red line with an alert icon under the day's ranges, naming what's wrong.

States:
- Open day: Switch on, one or more ranges.
- Closed day: Switch off, Closed in place of the ranges. The ranges are kept, so turning it back on restores them.
- Several ranges: Each range gets a remove button. Add is disabled at four.
- Backwards range: An end at or before the start. Both selects turn red and the day explains how to split overnight hours.
- Overlap: A range that starts before an earlier one ends. The later range is flagged and the message names the earlier one.
- Preset active: `aria-pressed` with the indigo tint and inset ring.
- Open now and closed now: In the strip, a green dot with the closing time, or a gray dot. Updated every minute.
- Disabled: `disabled` turns off the time zone, presets, switches, selects, add and copy.

Behavior:
- Controlled: `onChange` receives the whole next `BusinessHours`, `{ timezone, days }`, where each day is `{ enabled, slots: { start, end }[] }` and times are `"HH:MM"`. An end of `"24:00"` means midnight at the end of the day.
- Opening times run from 12:00 AM to 11:45 PM and closing times from 12:15 AM to Midnight, every 15 minutes.
- Add hours appends a three-hour range starting an hour after the day's latest close, clamped to the end of the day, and turns the day on.
- Copy offers Copy to all weekdays and Copy to every day, which copy the day's switch and ranges.
- A preset replaces the days and keeps the time zone. It reads as pressed whenever the days match it, whether you picked it or typed the same hours.
- Errors are checked per day after sorting by opening time. Only the first message shows; every invalid range's selects get `aria-invalid` and point at it.
- Hours can't cross midnight. Split overnight hours across two days: Friday 10:00 PM to Midnight and Saturday 12:00 AM to 6:00 AM.
- The 12 or 24-hour display is uncontrolled, starting at 12-hour, unless you pass `hour12` and `onHour12Change`.
- The strip reads the current time in the schedule's zone after mount and every minute, so server and client markup match.

Do and don't:
- Do: Keep the time zone in view next to the hours, and say in the section description whose clock they follow.
- Don't: Show hours without a zone, so a supplier in Lisbon and an agent in Chicago read them differently.
- Do: Block saving while `hasBusinessHoursErrors(value)` is true, and say why in the save bar.
- Don't: Let overlapping or backwards hours save. The queue closes when nobody expects it to.
- Do: Name custom presets for the schedule they set: Weekdays 8 to 6, Month-end close.
- Don't: Name presets after teams or people, such as Priya's hours, so nobody knows what they apply.

Content:
- Preset labels describe the schedule in sentence case: Weekdays 9 to 5, 24/7, Extended support hours.
- The section around the picker is titled Open hours, and its description says which zone applies and to whom.
- Times read 9:00 AM and Midnight in 12-hour, 09:00 and 24:00 in 24-hour. Use `formatTime` for the same strings elsewhere.
- The built-in errors say what to do. Don't add a second message beside them.

Accessibility:
- Each day is a `role="group"` labelled by its day name, and the switch is labelled by the same `<label>`.
- Every time select has its own name: Monday opens, Monday closes, range 2.
- Errors are linked to their selects with `aria-describedby` and mark them `aria-invalid`, so they're read when a select is focused.
- Presets are toggle buttons with `aria-pressed`, in a group labelled Presets. The time format is a radio group labelled Time format.
- Add and remove are icon buttons with names such as Add hours on Monday and tooltips. Copy is named Copy Monday's hours.
- The week strip is `role="img"` with the whole week as text: Monday 9:00 AM to 5:00 PM. Saturday closed.
- Tab: Moves through the zone, format, presets and each day's controls.
- Space: Turns a day on or off; presses a preset.
- Enter: Opens a time select or the copy menu.
- ↑ + ↓: Moves through times in an open select.
- ← + →: Switches between 12h and 24h.

Known gaps (follow the system, not the gap):
- `disabled` doesn't reach the 12h and 24h control, which stays interactive.
- Add and remove have tooltips; the copy button has a name but no tooltip.
- Errors appear without being announced. They're only read when someone focuses one of the flagged selects.

API `BusinessHoursPicker`:
- `value: BusinessHours`. `{ timezone: string; days: Record<DayKey, DaySchedule> }`.
- `onChange: (value: BusinessHours) => void`. Called with the whole next value.
- `presets?: BusinessHoursPreset[]` = businessHoursPresets. `{ id, label, days }[]`. Pass `[]` to hide the row.
- `hour12?: boolean`. Controls the 12 or 24-hour display. Uncontrolled, 12-hour first, when omitted.
- `onHour12Change?: (hour12: boolean) => void`. Called when the format changes.
- `showStrip?: boolean` = true. Shows the week strip.
- `disabled?: boolean`. Disables the editing controls.
- `className?: string`. Classes for the root.

API `WeekStrip`:
- `value: BusinessHours`. The schedule to draw.
- `hour12: boolean`. Axis labels and the closing time in 12 or 24-hour.
- `className?: string`. Classes for the well.

API `defaultBusinessHours`:
- `timezone?: string` = "America/Chicago". IANA zone.

API `hasBusinessHoursErrors`:
- `value: BusinessHours`. The schedule to check.

API `formatTime`:
- `time: string`. `"HH:MM"`.
- `hour12: boolean`. 12 or 24-hour.

API `businessHoursPresets`:
- `businessHoursPresets?: BusinessHoursPreset[]`. Spread it to add your own: `[...businessHoursPresets, mine]`.

### Provider model picker

- Level: Organism
- Category: Selection
- Status: Beta
- Import: `@oration/canon/components/provider-model-picker`
- Exports: `ProviderModelPicker`
- Docs: /design/components/provider-model-picker

Provider model picker chooses a provider, then one of its models, for an agent's language model, transcriber or voice. Providers sit in a segmented row of monogram tiles; models are radio rows with latency, cost, context and language meta, tags and an optional recommendation. Switching provider always selects a model, so the value is never half set. The mistake to avoid is dressing providers in their brand logos or colors: a provider is a neutral monogram tile, and the decision is made on the numbers.

When to use:
- To pick the language model behind an agent, with latency and cost per minute side by side.
- To pick a speech-to-text model for the transcriber, where language coverage matters.
- To pick a text-to-speech model before choosing a voice from it.
- When there is a recommended model for this agent and a one-line reason for it.

When not to use:
- For choosing a model in a chat or prompt bar, as a compact menu. Use /design/components/model-picker instead.
- For choosing a voice, with previews. Use /design/components/voice-picker instead.
- For a flat list of options with no grouping. Use /design/components/select instead.
- For two to five options that are just labels. Use /design/components/segmented-control instead.
- For a few rich options that don't belong to a provider. Use /design/components/choice-card instead.

Rules:
- Monograms, not logos: A provider is a one or two letter monogram (Oa, An, Dg) on a neutral tile, never a brand logo or brand color. Pass `tint: "gray"`; any other tint is an identity hue from the option palette, never the vendor's own color.
- The Option Hue Rule: Monogram tiles may carry an option hue as identity. The hue never signals quality, speed or status; tags and meta do that in words.
- Numbers decide: Meta is tabular and comparable across rows: time to first token, cost per minute, context window, languages. Say in the section description what the numbers mean.

Anatomy:
- Provider label: 13px medium text that names the provider group.
- Provider tray: A 10px-corner well (`bg-muted/70`) holding the provider radios. Two columns on small screens, a wrapping row above.
- Monogram tile: 20px with 6px corners and 11px semibold letters, from `monogram` or the first letter of the name.
- Selected pill: A white pill with `shadow-border` behind the checked provider, sliding between providers.
- Model count: Tabular count of the provider's models.
- Model label: 13px medium text that names the model group.
- Model row: A radio row with a 16px radio, the model name at 14px medium and meta on the right.
- Meta: 12px tabular muted text: 180 ms, $0.004/min, 128K context, 60 languages.
- Description and tags: 13px description and 20px gray tags such as Fastest or Multilingual.
- Recommendation: A lightbulb note naming the recommended model and why, with Use recommended when it isn't selected.

States:
- Provider rest: Muted label beside its tile.
- Provider hover: A shared highlight at 5% ink follows the pointer along the tray and the label turns ink.
- Provider selected: The white pill slides in on a 0.16s spring and the label turns medium ink.
- Model hover: The shared highlight follows the pointer down the list.
- Model selected: A 6% indigo tint with a 22% indigo inset edge, and the radio fills with a 5px indigo ring.
- Focus visible: A 3px Focus Indigo ring at 40% on the provider or model.
- Recommended: Recommended after the model name, and the note below. Use recommended disappears once it's selected.
- No models: Azure has no models available. in place of the list.
- Disabled: Every radio and the note's button at 50% and inert; the groups carry `aria-disabled`.

Behavior:
- It is controlled: pass `value` as `{ provider, model }` and update it in `onChange`.
- Choosing a provider selects its recommended model if the recommendation belongs to it, otherwise its first model. Choosing the provider that is already selected does nothing.
- Both groups behave like native radios. Only the checked item is in the tab order; arrow keys move and select, wrapping at the ends; Home and End jump.
- If `value.model` isn't in the list, nothing is checked and the first row takes focus.
- Numbers are formatted for you: `latency` 180 reads 180 ms and 1200 reads 1.2 s; `contextWindow` 128000 reads 128K context; `languages` as a number reads 60 languages, as a list of up to three it is joined, longer lists become a count. `cost` is shown as written.
- Use recommended sets both provider and model at once, even across providers.
- Each picker has its own `LayoutGroup`, so pills in two pickers on one page never animate into each other.

Do and don't:
- Do: Draw every provider as a neutral monogram and let the meta and tags carry the comparison.
- Don't: Color tiles in brand colors. It reads as an endorsement, and the hues fight the selection state.
- Do: Give the recommendation a reason specific to this agent: it follows Cedarline's payment scripts at the lowest latency.
- Don't: Recommend without a reason, or with a generic one like Best model.

Content:
- Use the provider's own model names and casing: GPT-4o mini, Nova-3, Flash v2.5.
- Descriptions say when to pick the model, in Cedarline's terms: Best accuracy on invoice numbers and supplier names.
- Tags are one or two words that compare models: Fastest, Lowest cost, Most accurate, Multilingual. Don't repeat Recommended as a tag; the component writes it.
- Write cost as a rate with its unit: $0.004/min or $0.60 per 1M tokens.
- The recommendation reason is one sentence that finishes is recommended.
- Mark retired models in the name, Nova-2 (legacy), rather than hiding them from agents that use them.

Accessibility:
- Providers and models are two `role="radiogroup"`s labelled by the visible Provider and Model labels. Rename them with `providerLabel` and `modelLabel`.
- The monogram is `aria-hidden`; the provider name is the accessible name, followed by the model count with a visually hidden models.
- Each meta value has a visually hidden label, so it reads Latency: 180 ms, Cost: $0.004/min.
- Selection is shown by the radio dot, the tint and the edge together, not by color alone.
- The pill slide and hover highlight run on springs that don't check reduced motion today.
- Tab: Moves to the checked provider, then the checked model, then Use recommended.
- ↑ + ↓: Move and select within a group. Left and Right do the same.
- Home: Selects the first item in the group. End selects the last.
- Enter: Selects the focused item. Space does the same.

Known gaps (follow the system, not the gap):
- Without `tint`, the tile hue is hashed from the provider id into seven hues, so tiles are colorful by default rather than neutral. The app maps its catalog colors onto tints instead of using gray.
- Provider buttons pass `text-13` next to a text color through the `cn` package, which drops the size, so provider names render at the inherited size instead of 13px.
- Model tags are hand-drawn gray spans, not the Tag component.
- The pill slide and the hover highlight have no reduced-motion handling of their own. They rely on the app-wide `MotionConfig reducedMotion="user"`, which drops the movement.
- When `value.model` matches no model, nothing says so; the list just has no selection.

API `ProviderModelPicker` (extends Doesn't spread props; renders `<div data-slot="provider-model-picker">`):
- `providers: ModelProvider[]`. Providers in display order, each with its models.
- `value: ProviderModelValue`. `{ provider, model }` ids.
- `onChange: (value: ProviderModelValue) => void`. Called with a complete value on every change.
- `recommendation?: { model: string; reason: ReactNode }`. A model id from any provider and why. Shows the note and the Recommended label.
- `providerLabel?: string` = "Provider". Label of the provider group.
- `modelLabel?: string` = "Model". Label of the model group.
- `disabled?: boolean`. Disables both groups and the note's button.
- `className?: string`. Merged onto the root.

API `ModelProvider`:
- `id: string`. Stable id, used in the value.
- `name: string`. Shown beside the tile.
- `monogram?: string`. One or two characters. Defaults to the first letter of `name`.
- `tint?: ProviderTint`. Tile hue. Without it the hue is hashed from `id`. Use `"gray"` for a neutral tile.
- `models: ProviderModel[]`. The provider's models, in order.

API `ProviderModel`:
- `id: string`. Stable id, used in the value and `recommendation.model`.
- `name: string`. The model's display name.
- `description?: string`. When to pick it.
- `tags?: string[]`. Short comparison tags.
- `latency?: number | string`. Time to first token. Numbers are milliseconds.
- `cost?: string`. Preformatted, like `$0.004/min`.
- `contextWindow?: number | string`. Numbers are tokens and read as 128K context.
- `languages?: number | string[]`. A count or a list of language names.

API `ProviderModelValue`:
- `ProviderModelValue?: { provider: string; model: string }`. The selected ids.

### Voice picker

- Level: Organism
- Category: Voice
- Status: Beta
- Import: `@oration/canon/components/voice-picker`
- Exports: `VoicePicker`, `Voice`
- Docs: /design/components/voice-picker

Voice picker is how people choose what an agent sounds like: a searchable list of voices with gender and accent filters, a short preview on every row and use-case tags. In Oration it sits in an agent's voice settings and in onboarding. The mistake is choosing from names alone; each row should say how the voice sounds and which calls it suits, and people should hear it say a real line before they pick.

When to use:
- To choose an agent's text-to-speech voice from the selected provider's catalog.
- When people need to hear a voice before choosing, saying a line the agent would actually say.
- When the catalog is long enough to search and filter, roughly more than five voices.
- In onboarding, to give the first agent a voice.

When not to use:
- For choosing the speech provider and model the voices come from. Use /design/components/provider-model-picker instead.
- For a short list of plain options with no previews. Use /design/components/radio-group instead.
- For two to four rich options that aren't voices. Use /design/components/choice-card instead.
- For showing an agent speaking during a live call. Use /design/components/voice-orb instead.
- For playing back a recorded call. Use /design/components/waveform instead.

Rules:
- Hear it before you pick it: Every row has a preview. Set `previewText` to a line from the agent's real calls, with the numbers and names it must read well: The remittance for invoice 48213 went out by ACH on September 24.
- The Label-Beside-Color Rule: Selection is a tint, an inset edge and `aria-checked` together. Playing swaps the icon to Stop, shows the level meter and announces Playing.
- The Ink Fill Rule: The playing meter is five bars in ink at 65%, never indigo. It shows activity, not a choice.

Anatomy:
- Search: An input group with a search icon and Search by name, accent or use.
- Filter chips: 28px pressed toggles for gender, then accent. A group only appears when it has two or more values.
- Count: 12px tabular text: 6 voices, or 2 of 6 voices while filtering.
- Voice row: 8px padding and `rounded-lg`. The selected row gets a 6% indigo tint and a 22% indigo inset edge.
- Preview button: A 32px ghost icon button: Play, or a filled Stop while playing.
- Name: 14px at weight 500.
- Meta: Gender, accent and age in 12px muted text.
- Playing meter: Five 2px ink bars beside the meta while the preview plays.
- Provider: 12px muted text at the end of the name row.
- Description: 13px muted text: how the voice sounds and where it fits.
- Best-for tags: 20px gray tags for the calls it suits.

States:
- Rest: Rows on the surface with no fill.
- Hover: A shared highlight follows the pointer down the list.
- Selected: 6% indigo tint, 22% indigo inset edge and `aria-checked`.
- Focus visible: A 3px Focus Indigo ring at 40% on the row's text, or on the preview button.
- Playing: The button shows a filled square in ink and is named Stop, the meter animates beside the meta and Playing is announced.
- Filter chip pressed: The same indigo tint and edge as a selected row. At rest chips are Well Gray at 70%; they scale to 0.96 while pressed.
- Filtered: The count reads 2 of 6 voices.
- No matches: A well with No voices match "Scottish". (or these filters) and Clear filters.
- Disabled: Voice rows at 50% and inert; the list carries `aria-disabled`.

Behavior:
- It is controlled: `value` is the selected voice id and `onChange` gets the new id.
- Search matches name, accent, gender, age, description, provider and best-for tags, ignoring case.
- Chips within a group widen the match (American or British); groups narrow it (female and British). Clear filters resets search and both groups.
- One preview plays at a time. Playing another stops the first, and pressing the playing one stops it. Unmounting stops playback.
- Without `speakPreview`, a preview is simulated for three seconds. With it, and where the browser supports speech synthesis, the browser speaks `previewText`, or Hi, I'm Nora. How can I help you today?, and stops when it finishes.
- Filtering never changes the selection. If the selected voice is hidden, the first visible row takes the tab stop.
- The list is a roving radio group: arrow keys move and select, wrapping at the ends, and Home and End jump. Clicking a row's padding selects it too.

Do and don't:
- Do: Describe how the voice sounds and where it shines, in a short sentence or two.
- Don't: Repeat the meta as the description. Female American voice tells people nothing the row doesn't already say.
- Do: Tag one to three call types the voice suits, in Cedarline's words.
- Don't: Pile on generic tags. Six adjectives make every voice look the same.

Content:
- Voice names are first names: Nora, Callum, Rafael.
- Descriptions are how it sounds, then where it fits: Clear and precise with even pacing. Reads long reference numbers well.
- Best-for tags are call types: Payment status, Remittance details, Spanish line.
- Accents are written as people say them: American, British, Mexican Spanish. Ages are decades: 30s.
- Preview lines come from real calls and include an amount, a date or an invoice number.

Accessibility:
- The list is a `role="radiogroup"` named by `label` (default Voice). Rows are radios; their name is the voice name and the rest of the row.
- Search is named Search voices and controls the list. The count is a polite live region, so filtering is announced.
- Filter chips are toggle buttons with `aria-pressed`, grouped as Gender and Accent.
- Preview buttons are named Play Nora preview and Stop Nora preview. The meter is `aria-hidden`; a visually hidden Playing carries the state.
- Best-for tags are introduced with a visually hidden Best for:.
- Only the selected row's preview button is in the tab order, so previewing another voice by keyboard means arrowing to it, which selects it.
- Tab: Moves through search, filter chips, then the selected row's preview button and radio.
- ↑ + ↓: Move to and select the previous or next voice. Left and Right do the same.
- Home: Selects the first visible voice. End selects the last.
- Space: Toggles a focused chip, or plays and stops a focused preview. Enter does the same.

Known gaps (follow the system, not the gap):
- Meta is joined with middle dots (Female · American · 30s), which Canon's writing rules ban.
- `disabled` only disables the voice radios. Search, filter chips and previews keep working.
- Previews share the roving tab stop with the radios, so only the selected row's preview is reachable by Tab.
- The level meter's comment says it holds still under reduced motion, but it animates regardless; it has no reduced-motion check of its own.
- Filter chips pass `text-13` next to a text color through the `cn` package, which drops the size, and they are a local copy rather than the Filter chip component.
- The app passes the provider id as `provider`, so rows in agent settings read elevenlabs rather than ElevenLabs.
- Simulated previews make no sound; only `speakPreview` produces audio, and nothing plays the provider's real sample.

API `VoicePicker` (extends Doesn't spread props; renders `<div data-slot="voice-picker">`):
- `voices: Voice[]`. The catalog, in display order.
- `value: string`. Id of the selected voice.
- `onChange: (id: string) => void`. Called with the newly selected id.
- `speakPreview?: boolean` = false. Speak previews with the browser's speech synthesis instead of simulating them.
- `label?: string` = "Voice". Accessible name of the list.
- `disabled?: boolean`. Disables the voice radios.
- `className?: string`. Merged onto the root.

API `Voice`:
- `id: string`. Stable id, used as the value.
- `name: string`. The voice's name.
- `description: string`. How it sounds and where it fits.
- `gender?: string`. Filterable. Compared lowercased and shown capitalized.
- `accent?: string`. Filterable, shown as written.
- `age?: string`. A decade, like 30s.
- `bestFor?: string[]`. Call types it suits, shown as tags.
- `provider?: string`. Shown at the end of the name row.
- `previewText?: string`. What the preview says when spoken.

### Questionnaire

- Level: Organism
- Category: Inputs
- Status: Experimental
- Import: `@oration/canon/components/questionnaire`
- Exports: `Questionnaire`, `QuestionnaireItem`, `QuestionnaireChoices`, `QuestionnaireNext`
- Docs: /design/components/questionnaire

Questionnaire asks one question at a time inside a form: radio or checkbox choices, free text, a progress line, and Previous, Skip, Next and Submit buttons that appear only when they apply. The headless `@shadcn/react` questionnaire owns navigation, validation, shortcuts and progress; Canon's wrapper adds the styling. It isn't used in the product yet. The thing people trip on is Next on an optional question: it still asks for an answer, and only Skip moves past it empty.

When to use:
- For setup or onboarding that is a short run of questions, each easy to answer on its own: how you pay suppliers, which ERP you use, who approves runs.
- For a survey such as a follow-up after a supplier dispute, one question per step.
- When speed matters: letter or number shortcuts pick an answer and Enter moves on.
- When some questions are optional, so people can skip what doesn't apply.

When not to use:
- For settings people change in any order and come back to. Use /design/components/settings-section instead.
- For a multi-page flow with its own steps, such as connecting a bank account. Use /design/components/stepper instead.
- For one choice inside a regular form. Use /design/components/radio-group instead.
- For choosing between a few rich options with descriptions on one screen. Use /design/components/choice-card instead.
- For a form people fill in once with all its fields visible. Use /design/patterns/forms instead.

Rules:
- The One Filled Button Rule: Next and Submit are the filled buttons and only one of them shows at a time. Previous and Skip are outline.
- The Quiet Indigo Rule: Indigo marks selection only: a checked choice gets a 40% indigo edge, a Well Gray fill and an indigo indicator. Unchecked choices stay neutral.
- The Tabular Figures Rule: The progress line, Question 2 of 4, is set in tabular figures so it doesn't shift as it counts.

Anatomy:
- Progress: Question 2 of 4 in 12px medium muted type. A progressbar that announces itself as it changes.
- Title: The question, as the item's `<legend>`, 16px medium.
- Description: Optional 14px muted help under the title.
- Choice: A row at least 44px tall with 10px corners and an input border. A native radio or checkbox is stretched invisibly over it.
- Indicator: A 16px circle (single choice) or 4px-cornered square (multiple), filled indigo with a dot or check when chosen.
- Shortcut key: With `shortcuts`, a 20px key on the trailing side showing A, B, C or 1, 2, 3.
- Actions: A grid: Previous on the start, Skip and then Next or Submit on the end. Buttons that don't apply are hidden.
- Input: Free text, 44px tall on touch screens and 32px from 640px up.
- Error: A red 14px line shown when Next is pressed on an unanswered question.
- Item: A `<fieldset>` per question. Only the active one is visible; the rest are hidden and inert.
- Root: A `<form noValidate>` around the items and the actions.

States:
- Rest: Input-colored border, transparent fill.
- Hover: The choice fills with Well Gray at 50%.
- Focus visible: When the hidden input has keyboard focus, the choice gets an indigo border and a 3px ring at 50%.
- Checked: Indigo border at 40%, a Well Gray fill, and an indigo indicator with a dot or a check.
- Invalid: After Next on an unanswered question: red choice borders, the error line and `aria-invalid` on the item.
- Skipped: Skip clears the answer and moves on. A skipped question submits nothing.
- Disabled: A disabled choice or item drops to 50% and ignores the pointer.
- First and last: Previous is hidden on the first question; on the last, Next gives way to Submit.
- Required: Skip is hidden, so the question must be answered.

Behavior:
- Next validates the active question. Answered or skipped passes; unanswered shows the error and focuses the first answer. Required questions hide Skip.
- Moving to another question focuses that question's fieldset, so screen readers announce the new legend.
- Submit validates every question. If one fails it jumps there and focuses it; otherwise `onSubmit` fires. Call `event.preventDefault()` and read answers with `new FormData(event.currentTarget)`.
- Each item's `name` is the field name and each choice's `value` its value. A `multiple` item submits every checked value under one name.
- Resetting the form, with `form.reset()` or a reset button, clears every answer and returns to the first question.
- Uncontrolled by default, starting at `defaultItem` or the first question. Pass `item` and `onItemChange` to control which question shows, for your own step list or for branching.
- `items` declares the questions as `{ name, required?, disabled?, choices? }`. It fixes the shortcut order and, in development, warns when the markup and the list disagree.
- `shortcuts="letters"` assigns A to Z and `"numbers"` 1 to 9 to the enabled choices, in order. Pressing one picks that choice.

Do and don't:
- Do: Ask one thing per question, with two to six answers that don't overlap.
- Don't: Fold two questions into one, such as How do you pay suppliers and how often?
- Do: Require only what you need to set things up, and let people skip the rest.
- Don't: Make every question required. People pick anything to get past it, and the answers stop meaning anything.
- Do: Write answers as parallel options in the person's words: ACH from our bank portal, Paper checks.
- Don't: Mix answers of different kinds, or add Other without a way to say what.

Content:
- Titles are questions, in sentence case, ending with a question mark: How do you pay suppliers today?
- Descriptions say why you're asking or how the answer is used: We'll set up your first payment run to match.
- Answers are short and parallel. Put detail in a `QuestionnaireChoiceDescription` rather than a longer label.
- Rename Submit for what it does: Finish setup, Send answers.
- Error messages say what to do: Choose an answer to continue., or for optional questions Choose an answer or skip this question.

Accessibility:
- Each question is a `<fieldset>` with its title as the `<legend>`, so answers are announced with the question.
- Answers are native radios or checkboxes stretched over the row, so they behave like any radio group or checkbox list; the drawn indicator is hidden from assistive tech.
- Progress is a progressbar whose value text is Question 2 of 4, announced politely as it changes.
- When shown, the error has `role="alert"` and is linked to the question with `aria-describedby`.
- Hidden questions and buttons are `inert`, so Tab and screen readers skip them.
- Shortcuts are exposed with `aria-keyshortcuts`. Choices are at least 44px tall on touch screens.
- Give a free-text input its own `aria-label`; the legend names the group, not the field.
- A: With `shortcuts="letters"`, picks that answer. `"numbers"` uses 1 to 9.
- ↑ + ↓: Moves between answers. On radios, also selects.
- ← + →: Previous question, and next once this one is answered. Not inside a text field or on a radio.
- Enter: On a chosen answer or filled text, goes to the next question or submits.
- ⌘ + Enter: Next or submit from anywhere in the question. Ctrl+Enter off Apple platforms.
- Tab: Moves to the visible action buttons.

Known gaps (follow the system, not the gap):
- Not used anywhere in the product yet, and marked experimental.
- The shortcut keys are set in Geist Mono at 10px. The Machine Mono Rule keeps keyboard keys in Geist Sans, The Thirteen-Fourteen Rule puts nothing under 11px, and `Kbd` already draws keys.
- Choices and the input use a 3px focus ring at 50%, where every other control uses 40%.
- Built-in strings are English and fixed in places: the progress value text is always Question {n} of {total} even when you replace the visible text.

API `Questionnaire` (extends @shadcn/react Questionnaire.Root (`<form>`)):
- `defaultItem?: string`. Name of the question to start on. Uncontrolled.
- `item?: string`. Name of the visible question. Controlled.
- `onItemChange?: (item: string) => void`. Called when the visible question changes.
- `items?: readonly { name: string; required?: boolean; disabled?: boolean; choices?: readonly { value: string; disabled?: boolean }[] }[]`. Declares the questions, for shortcut order and dev warnings.
- `shortcuts?: "letters" | "numbers"`. Assigns keys to answers.
- `noValidate?: boolean` = true. Set `false` to also run native constraint validation.
- `onSubmit?: React.FormEventHandler<HTMLFormElement>`. Fires once every question is valid.

API `QuestionnaireProgress` (extends @shadcn/react Questionnaire.Progress (`<div>`)):
- `children?: React.ReactNode` = "Question {n} of {total}". Replaces the visible text. The value text stays the default.

API `QuestionnaireItem` (extends @shadcn/react Questionnaire.Item (`<fieldset>`)):
- `name: string`. Field name, and the id used by `item`.
- `required?: boolean` = false. Hides Skip; an answer is needed.
- `multiple?: boolean` = false. Checkboxes instead of radios.
- `disabled?: boolean` = false. Removes the question from the flow.
- `invalid?: boolean` = false. Forces the invalid state, for server-side errors.
- `onStatusChange?: (status: "unanswered" | "answered" | "skipped") => void`. Called when the answer status changes.

API `QuestionnaireTitle` (extends @shadcn/react Questionnaire.Title (`<legend>`)):

API `QuestionnaireDescription` (extends @shadcn/react Questionnaire.Description (`<p>`)):

API `QuestionnaireChoices` (extends @shadcn/react Questionnaire.Choices (`<div>`)):

API `QuestionnaireChoice` (extends @shadcn/react Questionnaire.Choice (`<label>`)):
- `value: string`. Submitted value.
- `defaultChecked?: boolean` = false. Chosen at start. Uncontrolled.
- `checked?: boolean`. Chosen state. Controlled.
- `onChange?: React.ChangeEventHandler<HTMLInputElement>`. The hidden input's change event.
- `disabled?: boolean` = false. Disables this answer.

API `QuestionnaireChoiceDescription` (extends <span>):

API `QuestionnaireError` (extends @shadcn/react Questionnaire.Error (`<p>`)):
- `children?: React.ReactNode` = "Choose an answer to continue." (required), "Choose an answer or skip this question.". The message.

API `QuestionnaireActions` (extends <div>):

API `QuestionnairePrevious / QuestionnaireSkip / QuestionnaireNext / QuestionnaireSubmit` (extends @shadcn/react Questionnaire.Previous, Skip, Next, Submit (`<button>`)):
- `variant?: Button variant` = "outline" (Previous, Skip), "default" (Next, Submit). Button style.
- `size?: Button size` = "default". Button size. 44px tall below 640px regardless.
- `children?: React.ReactNode` = "Previous", "Skip", "Next", "Submit". The label.

### Message scroller

- Level: Organism
- Category: Layout
- Status: Experimental
- Import: `@oration/canon/components/message-scroller`
- Exports: `MessageScroller`, `MessageScrollerViewport`, `MessageScrollerContent`, `MessageScrollerButton`
- Docs: /design/components/message-scroller

Message scroller is the scroll container for a conversation. It opens at the newest message, starts each new turn near the top so the reply has room to stream in, holds the reader's place when older messages load above, and shows a button back to the end once they've scrolled away. It wraps the headless `@shadcn/react` message scroller and isn't used in the product yet. The mistake it replaces is an `overflow-y-auto` div with a scroll-to-bottom effect, which drags the reader down every time a token arrives.

When to use:
- For any transcript that grows: a copilot thread, a supplier conversation, an agent's call log.
- When replies stream in and the view should follow only while the reader is already at the end.
- When older history loads above and the reader's place has to hold still.
- When something needs to jump to a message, such as a search hit or a citation, through `useMessageScroller`.

When not to use:
- For a scrolling panel that isn't a conversation. Use /design/components/scroll-area instead.
- For the whole assistant thread with its composer and message parts. It uses a scroller inside. Use /design/components/thread instead.
- For a call transcript with speakers and timecodes. Use /design/components/live-transcript instead.
- For a record's history of events in time order. Use /design/components/timeline instead.

Rules:
- The Scroll Edge Rule: The viewport fades its bottom edge, so a transcript clipped below shows that there's more.
- The One Filled Button Rule: The scroll button is secondary. The composer's Send is the filled button beside a conversation.

Anatomy:
- Viewport: The scrolling region: a focusable `role="region"` labelled Messages by default, with a thin scrollbar, a stable gutter and a bottom fade.
- Item: One row: a message, a date marker or a load-more row. `messageId` makes it a jump target; `scrollAnchor` marks a turn boundary.
- Scroll button: A 28px secondary icon button centered 16px from the bottom (or top for `direction="start"`). Slides in when there's content to scroll toward.
- Content: `role="log"` with `aria-relevant="additions"`, a column with 24px between rows, at least the viewport's height.
- Root: The frame: a relative flex column that fills its parent and clips. It mirrors the viewport's scroll attributes.
- Provider: `MessageScrollerProvider` renders nothing. It owns the scroll state, the behavior props and the hooks' context.

States:
- Pending scroll: The viewport is invisible until its opening position is applied, so it never flashes the oldest messages first.
- At the end: The end button is inactive: 95% scale, shifted down, transparent and out of the tab order.
- Scrolled away: With content below, the button scales and fades in over 200ms. `data-scrollable` lists `start`, `end` or both.
- Following: With `autoScroll`, the view stays at the live edge as content grows, until the reader scrolls.
- Autoscrolling: While the scroller is moving itself, `data-autoscrolling` is set and the scrollbar hides.

Behavior:
- `defaultScrollPosition` sets where it opens, once, on the first non-empty render: `"end"` (default), `"start"`, or `"last-anchor"`, which opens at the last anchored row and falls back to the end when the turn fits.
- `autoScroll` is off by default. On, it follows new content only while the reader is within `scrollEdgeThreshold` (8px) of the end; a wheel, touch or keyboard scroll releases it.
- A newly appended `scrollAnchor` row, usually the person's own message, is scrolled near the top with `scrollPreviousItemPeek` (64px) of the row before it showing, and a spacer below makes room for the reply.
- `preserveScrollOnPrepend` (on by default) keeps the first visible message where it is when older rows are added above.
- `useMessageScroller()` returns `scrollToEnd`, `scrollToStart` and `scrollToMessage(id, { align, behavior, scrollMargin })`. `useMessageScrollerScrollable()` returns `{ start, end }`, and `useMessageScrollerVisibility()` the current anchor and the visible message ids. All three must be called under the provider.
- The scroll button scrolls smoothly toward its edge. It is inert and leaves the tab order when there is nothing to scroll toward.
- Items use `content-visibility: auto` with a 10rem placeholder size, so a long transcript only lays out the rows on screen.
- The root fills its parent. Give the parent a height, such as `flex-1 min-h-0` in a column or a fixed height.

Do and don't:
- Do: Mark the person's messages as `scrollAnchor`, so a new question starts near the top and the answer streams in below it.
- Don't: Scroll to the very bottom on every token. The question scrolls out of view before the answer is done.
- Do: Let people scroll up to reread while a reply streams. `autoScroll` follows only while they're at the end.
- Don't: Force the view back to the end while someone is reading further up.
- Do: Give the scroller a bounded height from its layout.
- Don't: Put it in an auto-height container. It grows with the transcript and never scrolls.

Content:
- Name the viewport after the conversation: Conversation about INV-20417, not the default Messages.
- Date and system rows are short and in sentence case: Today, Priya Raman joined.
- A load-more row says what it loads: Load earlier messages. When there's nothing left: Start of conversation.

Accessibility:
- The viewport is a labelled region with `tabIndex={0}`, so keyboard users can focus it and scroll with the usual keys. Give it a specific `aria-label`.
- Content is a `role="log"` that announces added rows. Set `aria-busy` on it while a reply streams, so it isn't read out word by word.
- The scroll button is icon-only with a visually hidden Scroll to end (or Scroll to start). When inactive it is inert and out of the tab order.
- Scrolling the transcript never moves focus.
- Tab: Focuses the viewport, then the scroll button when it shows.
- ↑ + ↓: Scrolls the focused viewport a line.
- Page Up + Page Down: Scrolls a page. Space also pages down.
- Home + End: Jumps to the start or the end.
- Enter: On the scroll button, jumps to its edge.

Known gaps (follow the system, not the gap):
- Not used anywhere in the product yet, and marked experimental. Thread and the transcripts don't use it.
- The floating scroll button draws its edge with a CSS border and has no lift. The Hairline-and-Lift Rule asks a raised control for one composite shadow.
- The button leaves over 400ms and enters over 200ms, so it leaves slower than it comes, and neither transition is behind `motion-safe`.
- The scroll button is icon-only without a tooltip, and its hidden label is fixed English unless you pass `children`.

API `MessageScrollerProvider`:
- `autoScroll?: boolean` = false. Follow new content while the reader is at the end.
- `defaultScrollPosition?: "start" | "end" | "last-anchor"` = "end". Where it opens, applied once.
- `scrollEdgeThreshold?: number` = 8. Pixels from an edge that still count as at it.
- `scrollMargin?: number` = 0. Margin on the aligned edge for jumps and visibility.
- `scrollPreviousItemPeek?: number` = 64. How much of the previous row stays visible above a new anchor.
- `children?: React.ReactNode`. The scroller and anything that calls the hooks.

API `MessageScroller` (extends @shadcn/react MessageScroller.Root (`<div>`)):

API `MessageScrollerViewport` (extends @shadcn/react MessageScroller.Viewport (`<div>`)):
- `preserveScrollOnPrepend?: boolean` = true. Hold the first visible row when rows are added above.
- `aria-label?: string` = "Messages". Names the region.
- `role?: string` = "region". Landmark role.
- `tabIndex?: number` = 0. Keeps it keyboard-scrollable.

API `MessageScrollerContent` (extends @shadcn/react MessageScroller.Content (`<div>`)):
- `role?: string` = "log". Live-region role.
- `aria-relevant?: string` = "additions". What gets announced.
- `aria-busy?: boolean`. Set while a reply streams.
- `spacerClassName?: string`. Classes for the spacer that makes room under anchors.

API `MessageScrollerItem` (extends @shadcn/react MessageScroller.Item (`<div>`)):
- `messageId?: string`. Stable id for `scrollToMessage`, visibility and prepend holding.
- `scrollAnchor?: boolean` = false. Marks a turn boundary that new turns anchor to.

API `MessageScrollerButton` (extends @shadcn/react MessageScroller.Button (`<button>`)):
- `direction?: "start" | "end"` = "end". Which edge it scrolls toward, and where it sits.
- `behavior?: ScrollBehavior` = "smooth". Native scroll behavior.
- `variant?: Button variant` = "secondary". Button style.
- `size?: Button size` = "icon-sm". Button size.
- `children?: React.ReactNode`. Replaces the arrow and its hidden label.
- `render?: React.ReactElement | render function`. Custom element to render.

API `useMessageScroller`:
- `scrollToEnd?: (options?: { align?, behavior?, scrollMargin? }) => boolean`. Scrolls to the newest row.
- `scrollToStart?: (options?) => boolean`. Scrolls to the top.
- `scrollToMessage?: (messageId: string, options?) => boolean`. Scrolls to a mounted row, aligned to `start` by default.

API `useMessageScrollerScrollable / useMessageScrollerVisibility`:
- `useMessageScrollerScrollable()?: { start: boolean; end: boolean }`. Whether there's content above or below.
- `useMessageScrollerVisibility()?: { currentAnchorId: string | null; visibleMessageIds: string[] }`. The current turn and the rows on screen.

### Thread

- Level: Organism
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/thread`
- Exports: `Thread`, `ThreadViewport`, `ThreadMessages`, `ThreadWelcome`, `ThreadSuggestions`, `ThreadScrollToBottom`
- Docs: /design/components/thread

Thread is the frame of a conversation with Copilot: a column that holds a scrolling viewport of messages, a welcome with suggested prompts when it's empty, a scroll-to-latest button and the prompt bar below. It keeps the newest message in view while a response streams and lets go as soon as the reader scrolls up. Copilot is the one chat surface in Oration, so Thread belongs in the Copilot panel, the web-call chat tab and the two approved exceptions (the Knowledge base query and the Contact Center assist panel), not in a new panel on every page. The common mistake is giving it no bounded height: it needs a fixed-height or `flex-1 min-h-0` parent to scroll.

When to use:
- For the Copilot panel: the conversation Maya Okafor has with Copilot across the CRM, with the composer pinned below.
- For a test chat with an agent, such as the chat tab of a web call with Nora.
- For the approved scoped assistants: the Knowledge base AI query and the Contact Center assist panel.
- When a response streams in and the view should follow it until the reader scrolls away.
- For the empty state of a conversation: a greeting, one line on what Copilot can see and three or four suggested prompts.

When not to use:
- To add a chat box to a record page or settings page. Open Copilot with the record attached instead. Use /design/patterns/ai-assistance instead.
- For a live call transcript, where turns come from two speakers and nobody types. Use /design/components/live-transcript instead.
- For a one-shot summary on a list or detail page. Stream it in place with its sources. Use /design/components/streaming-text instead.
- For a scrolling list that only needs to stick to its bottom, without messages or suggestions. Use /design/components/message-scroller instead.
- For a ticket's conversation with a customer, which is a record timeline, not a chat with Copilot. Use /design/components/timeline instead.

Rules:
- One chat surface: Copilot is reachable everywhere and is the only chat panel. Pages hand it context (a record, a filter, a selection) instead of growing their own. The Knowledge base query and the Contact Center assist panel are the two exceptions.
- The One Filled Button Rule: Send, in the prompt bar, is the thread's one filled button. Suggestions are outlined chips or list rows, message actions are ghost icons, and an approval card below a message is quiet unless it's the latest proposal.
- The Quiet Indigo Rule: Nothing in the thread is indigo except Send and the focus ring. The assistant mark is a neutral Well Gray tile and the user's bubble is Well Gray, not a colored bubble.

Anatomy:
- Thread: The root column. It owns the stick-to-bottom state and `isRunning`, and sets `data-running` while a response streams. Give it a bounded height.
- Viewport: The scrolling region, with a stable scrollbar gutter and contained overscroll. Its inner column caps at `max-w-3xl` and pads 16px; panels override that with `contentClassName`.
- Messages: A `role="log"` list named Conversation, 24px between turns, marked busy while a response streams.
- Scroll to latest: A round 28px outline button that springs in 12px above the bottom edge once the reader scrolls more than 48px up.
- Composer slot: Whatever follows the viewport inside Thread, usually a `PromptBar` in a `shrink-0` wrapper with 12px padding.

States:
- Loading: `ChatPanelSkeleton` stands in for the panel: two user bubbles, an assistant turn and the composer, with a screen-reader Loading conversation.
- Empty: `ThreadWelcome` centers vertically in the viewport with an optional icon, a 16px title, a 13px description capped at 42ch and suggestions.
- Conversation: Messages stack 24px apart. The viewport is pinned to the bottom on mount.
- Running: With `isRunning`, the root gets `data-running` and the message log gets `aria-busy`, so screen readers wait for the finished answer. The viewport keeps following the growing text.
- Scrolled up: Following stops the moment the reader scrolls up, and the scroll-to-latest button appears. Scrolling back within 48px of the bottom, or pressing the button, resumes following.
- Suggestion hover and focus: A Well Gray highlight glides between suggestions with the pointer (fluid hover). Keyboard focus draws a 3px Focus Indigo ring at 40%.

Behavior:
- Stick to bottom is a `ResizeObserver` on the content and the viewport: while pinned, any growth sets `scrollTop` to the bottom. An upward scroll of more than 1px unpins it; coming back within 48px re-pins it.
- `autoScroll={false}` turns following off, for a thread opened at an older message. The scroll-to-latest button still works.
- The scroll-to-latest button scrolls smoothly, or jumps under reduced motion. It enters on `spring.moderate` (160ms, no bounce) from 8px below at 0.96 scale and leaves in 120ms.
- `ThreadViewport` renders `ThreadScrollToBottom` for you. Pass `scrollButton={false}` to drop it, or render `ThreadScrollToBottom` yourself inside a positioned ancestor.
- `ThreadWelcome` only renders suggestions when both `suggestions` and `onSelect` are passed. Extra content, such as recent chats, goes in `children` below them.
- `ThreadSuggestions` calls `onSelect(prompt, suggestion)`. Copilot sends the prompt straight away; use the same prompt as the label unless the label needs to be shorter.
- Every part reads context from `Thread` and throws if rendered outside it. `useThread()` exposes `isAtBottom`, `scrollToBottom()` and `isRunning` to custom parts.

Do and don't:
- Do: Suggest prompts that use what Copilot can see: Why is INV-20931 on hold? Draft a remittance reply to Halcyon.
- Don't: Offer generic starters such as Ask me anything or What can you do? They teach nothing about the page.
- Do: Send people to Copilot with the record attached: a quiet Ask Copilot action on the supplier header.
- Don't: Embed a second chat box in the page. Two chat surfaces split the history and the approvals.
- Do: Give the thread a bounded parent (`h-[30rem]`, or `flex-1 min-h-0` in a panel) so the viewport scrolls and the composer stays put.
- Don't: Drop it into a page section with no height. The viewport never scrolls, stick to bottom does nothing and the composer slides off screen.

Content:
- Welcome title: a short question, What can I help with? The default is How can I help?
- Welcome description: one sentence on what Copilot can see right now and how to add more, such as I can see Northwind Freight. Type @ to add another record, and / for commands.
- Suggestions: three or four, phrased as the person would type them, specific to the page: Summarize Northwind Freight's open invoices, not Summarize.
- In the list layout, a suggestion's description says what it will produce: A table of invoices past terms.
- Follow-up chips after an answer stay under six words: Draft the reply, Show the payment run.

Accessibility:
- The message list is a `role="log"` named Conversation. New finished messages are announced politely; while `isRunning` is true the log is `aria-busy`, so fragments of a streaming answer aren't read out.
- Suggestions are real buttons in a group named Suggested prompts, reachable with Tab.
- The scroll-to-latest button is named Scroll to latest message. It is icon-only and has no tooltip today (see known gaps).
- The viewport isn't focusable on its own; keyboard users reach messages through their action buttons, and the composer keeps focus while they type.
- Under reduced motion the scroll-to-latest jump is instant and the button's translate and scale are dropped by the app's motion config.
- `ChatPanelSkeleton` is `aria-hidden` apart from a `role="status"` Loading conversation.
- Tab: Moves through suggestions, message actions, the scroll-to-latest button and the composer.
- Enter: Sends the focused suggestion.
- Space: Sends the focused suggestion.

Known gaps (follow the system, not the gap):
- `ChatPanelSkeleton` isn't used anywhere in the app. The Copilot panel opens without a loading state.
- The scroll-to-latest button is icon-only with an `aria-label` but no tooltip, unlike every other icon button in the suite.
- `ThreadWelcome` always renders its title as an `h2`, with no way to change the level for panels whose own heading is an `h2`.
- There are three stick-to-bottom implementations: this one (48px threshold), Live transcript's (24px) and Message scroller. They behave slightly differently when you scroll back down.
- `ThreadViewport` centers its content at `max-w-3xl` by default, which suits a full page; every product call site overrides it with `max-w-none`.

API `Thread` (extends Nothing. Only the props below are read.):
- `children: React.ReactNode`. Usually a `ThreadViewport` and the composer.
- `isRunning?: boolean` = false. A response is streaming. Sets `data-running` and `aria-busy` on the log.
- `autoScroll?: boolean` = true. Follow new content while the reader is at the bottom.
- `className?: string`. Merged onto the root, which is `relative flex h-full min-h-0 flex-col`.

API `ThreadViewport`:
- `children: React.ReactNode`. `ThreadMessages` or `ThreadWelcome`.
- `scrollButton?: boolean` = true. Render the scroll-to-latest button.
- `className?: string`. Merged onto the outer wrapper.
- `contentClassName?: string`. Merged onto the inner column (`max-w-3xl px-4 py-4 gap-6`). Panels pass `max-w-none`.

API `ThreadMessages`:
- `children: React.ReactNode`. `UserMessage` and `AssistantMessage` turns.
- `className?: string`. Merged onto the log.

API `ThreadWelcome`:
- `title?: string` = "How can I help?". Rendered as an `h2`.
- `description?: React.ReactNode`. One sentence on what Copilot can see.
- `icon?: React.ReactNode`. Shown above the title in Slate Meta.
- `suggestions?: ThreadSuggestion[]`. Rendered only together with `onSelect`.
- `onSelect?: (prompt: string, suggestion: ThreadSuggestion) => void`. Called when a suggestion is picked.
- `suggestionsLayout?: "chips" | "list"` = "chips". Passed to `ThreadSuggestions`.
- `children?: React.ReactNode`. Below the suggestions, e.g. recent chats.
- `className?: string`. Merged onto the root.

API `ThreadSuggestions`:
- `suggestions: { label: string; prompt: string; icon?: React.ReactNode; description?: string }[]`. The `ThreadSuggestion` type. `prompt` is also the React key, so keep prompts unique. `description` shows in the list layout only.
- `onSelect: (prompt: string, suggestion: ThreadSuggestion) => void`. Called with the prompt and the whole suggestion.
- `layout?: "chips" | "list"` = "chips". Chips are 32px outlined pills that wrap; list rows are at least 36px and stack.
- `className?: string`. Merged onto the group.

API `ThreadScrollToBottom`:
- `className?: string`. Merged onto the absolutely positioned wrapper (`bottom-3 left-1/2`).

API `ChatPanelSkeleton`:
- `className?: string`. Merged onto the root.

API `useThread`:
- `returns?: { scrollRef; contentRef; isAtBottom: boolean; scrollToBottom: (behavior?: ScrollBehavior) => void; isRunning: boolean }`. The refs belong to the viewport; don't reattach them.

### AI message

- Level: Organism
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/message`
- Exports: `UserMessage`, `AssistantMessage`, `MessageActions`, `BranchPicker`, `MessageError`
- Docs: /design/components/ai-message

AI message draws the two sides of a conversation with Copilot or a test agent. `UserMessage` is a right-aligned Well Gray bubble; `AssistantMessage` is an avatar beside plain, bubble-free content, with `MessageActions` (copy, regenerate, helpful, not helpful), a `BranchPicker` for regenerated versions and an inline `MessageError` with Retry. Assistant content is the document, not a chat bubble, so it holds streamed text, tool chips, plans and approval cards at full width. The common mistake is decorating it: no indigo bubbles, no colored assistant tile, and no actions while it is still streaming.

When to use:
- For every turn inside a `Thread`: the person's prompt as `UserMessage`, Copilot's answer as `AssistantMessage`.
- For a test chat with an agent such as Nora, with the agent's avatar and persona name on each answer.
- When an answer can be copied, regenerated or rated, through `MessageActions`.
- When a regenerated answer should keep its earlier versions one click away, through `BranchPicker`.
- When a response fails part way, to show the failure and a Retry where the answer would have been.

When not to use:
- For a live call transcript between Nora and a supplier. Use /design/components/live-transcript instead.
- For a customer conversation on a ticket or in the Contact Center inbox. Use /design/components/bubble instead.
- For a one-off generated summary on a record page, outside a conversation. Use /design/components/streaming-text instead.
- For a single tool call inside an answer. Use /design/components/tool-chip instead.
- For a failure that blocks the whole panel, such as Copilot being unavailable. Use /design/components/alert instead.

Rules:
- The Quiet Indigo Rule: Neither side is indigo. The user bubble is Well Gray, the assistant mark is a neutral tile with a sparkles icon, and message actions are ghost icons in Slate Meta. Indigo in a thread belongs to Send and the focus ring.
- The Tint Well Rule: The user bubble and the error are tints (Well Gray and a 10% Signal Red), not bordered cards. Anything inside an assistant answer that needs a region, such as sources or a field list, uses a 70% Well Gray well.
- The Label-Beside-Color Rule: An error is a red icon plus a sentence that says what failed. A pressed rating fills its thumb and sets `aria-pressed`, so it reads without color.

Anatomy:
- Attachments: Optional chips above the user bubble, right-aligned: mentioned records, the command used, attached files.
- User bubble: Well Gray, 12px corners, 8px by 12px padding, 14px text with preserved line breaks, at most 85% of the thread's width.
- Assistant avatar: A 24px neutral tile with a sparkles icon by default. Pass an `AgentAvatar` for a named agent, or `null` to drop the column.
- Name: Optional 12px Slate Meta at weight 500, such as Nora. Without it the content nudges down 2px to line up with the avatar.
- Content: 14px reading text at a relaxed line height, no bubble. Holds streamed text, tool chips, plans and cards.
- Message actions: A toolbar of 24px ghost icon buttons with tooltips: Copy, Regenerate, Helpful, Not helpful, then anything passed as children.
- Branch picker: Previous and next version buttons around a tabular 2/3 counter. Hidden when there is one version.

States:
- Streaming: `status="streaming"` sets `aria-busy` and hides the actions until the answer finishes.
- Done: Actions appear, on hover or always, per `actionsVisibility`.
- Error: `status="error"` renders the `error` slot, usually a `MessageError`: a 10% red tint with an alert icon, a title, an optional description and an outline Retry.
- Actions hidden: With `actionsVisibility="hover"`, pointer devices that can hover see actions only while the turn is hovered or has focus inside it. Touch devices always see them.
- Action hover: Ghost icon buttons fill Well Gray and the icon turns from Slate Meta to ink over 150ms.
- Action focus visible: Indigo border and a 3px Focus Indigo ring at 40%.
- Copied: Copy swaps to a Ledger Green check and its name to Copied for 1.6 seconds.
- Rated: The chosen thumb fills with ink and sets `aria-pressed`. Pressing it again clears the rating.
- First or last version: The branch picker disables Previous on the first version and Next on the last.

Behavior:
- Actions never render while `status` is `streaming`, so nobody copies or rates half an answer.
- Copy writes `content` to the clipboard and confirms with a check for 1.6 seconds. Omit `content` to hide Copy.
- Rating raises a toast, Marked as helpful or Marked as not helpful, with Undo. Not helpful adds This answer goes to review so future answers improve. Clearing a rating raises no toast.
- `feedback` and `onFeedback` make the rating controlled. Leave `feedback` undefined and the component keeps its own state.
- Regenerate only renders when `onRegenerate` is passed. The app adds a version, streams it, and passes the new `index` and `count` to `BranchPicker`.
- `BranchPicker` takes a zero-based `index`, renders nothing when `count` is 1 or less, and announces Version 2 of 3 politely when the page changes.
- Children of `MessageActions` render after the built-in buttons, which is where `BranchPicker` and any extra action go.
- The hover reveal is a 150ms opacity fade keyed to `group-hover/message` and `group-focus-within/message`, so Tab reveals the actions too.

Do and don't:
- Do: Draw the assistant as plain text beside a neutral avatar, and the person's turn as a Well Gray bubble.
- Don't: Put either side in an indigo bubble. It spends the accent on decoration and makes long answers hard to read.
- Do: Put a failure where the answer would have been, say what failed, and offer Retry.
- Don't: Print a red Something went wrong with no way forward, or leave the turn blank and raise a toast.
- Do: Show actions always on the latest answer and on hover for earlier ones.
- Don't: Pin a full action row under every message. The thread turns into a column of icons.

Content:
- User messages are the person's words, verbatim. Don't rewrite or trim them.
- Assistant answers lead with the answer: Yes. INV-20931 is scheduled for Tuesday's ACH run. Then the supporting detail.
- Name things the way Cedarline does: invoice and payment IDs exactly (INV-20931, PMT-58213), supplier names in full, amounts with cents.
- `MessageError` titles say what didn't happen: Couldn't finish this response (the default), Couldn't reach the ERP. The description says why, in plain words, and never blames the person.
- `retryLabel` stays a verb: Retry, Try again, Reconnect.
- Agent names on `AssistantMessage` are the persona the caller hears, such as Nora, not the internal agent name.

Accessibility:
- Messages render inside the thread's `role="log"`. A streaming assistant turn is `aria-busy`, so assistive tech waits for the finished text.
- Every action is an icon button with an `aria-label` and a tooltip with the same words: Copy (then Copied), Regenerate, Helpful, Not helpful, Previous version, Next version.
- Ratings expose `aria-pressed`. The thumbs fill as well as darken, so the pressed state reads without color.
- The branch picker is a group named Response versions with a polite Version 2 of 3 announcement; the visible 2/3 is hidden from screen readers.
- `MessageError` is `role="alert"`, so the failure is announced as soon as it appears.
- The default assistant avatar is `aria-hidden`; give the turn a `name` when the speaker matters.
- Hidden actions are only transparent, not removed, so keyboard users can still Tab to them and focus reveals them.
- Tab: Moves through each action in order, revealing hidden actions.
- Enter: Activates the focused action.
- Space: Activates the focused action.

Known gaps (follow the system, not the gap):
- `MessageError` isn't used anywhere in the app. When a Copilot turn is stopped, the app writes its own one-line note instead.
- `UserMessage`'s `actions` slot isn't used in the app, so there is no edit-and-resend for a prompt.
- Copy shows Copied even when the clipboard write fails; the error is swallowed.
- Actions are hidden only while streaming. In the error state they render beside the error, so Copy and the ratings act on an answer that doesn't exist. Pass `actions` only once the turn is done.
- `MessageActions` is `role="toolbar"` but has no arrow-key navigation. Each button is its own Tab stop, which a toolbar role doesn't lead people to expect.
- `AssistantAvatar` and the `MessageStatus` and `MessageFeedback` types are exported but not listed in the registry.

API `UserMessage` (extends Nothing. Only the props below are read.):
- `children: React.ReactNode`. The message text. Line breaks are kept.
- `attachments?: React.ReactNode`. Rendered above the bubble, e.g. mention chips.
- `actions?: React.ReactNode`. Rendered below the bubble and revealed on hover or focus.
- `className?: string`. Merged onto the root.

API `AssistantMessage` (extends Nothing. Only the props below are read.):
- `children?: React.ReactNode`. The answer and anything inside it.
- `avatar?: React.ReactNode | null`. Replaces the default tile. `null` removes the avatar column.
- `name?: string`. Speaker name above the content.
- `status?: "streaming" | "done" | "error"` = "done". Streaming hides actions; error renders `error`.
- `actions?: React.ReactNode`. Usually `MessageActions`. Hidden while streaming.
- `error?: React.ReactNode`. Rendered only when `status` is `error`. Usually `MessageError`.
- `actionsVisibility?: "hover" | "always"` = "hover". Use `always` on the latest turn.
- `className?: string`. Merged onto the root.

API `MessageActions`:
- `content?: string`. Plain text to copy. Omit to hide Copy.
- `onRegenerate?: () => void`. Shows Regenerate.
- `feedback?: "up" | "down" | null`. Controlled rating. Leave undefined for uncontrolled.
- `onFeedback?: (value: "up" | "down" | null) => void`. Called on every change, including Undo.
- `children?: React.ReactNode`. Extra actions after the built-ins, e.g. `BranchPicker`.
- `className?: string`. Merged onto the toolbar.

API `BranchPicker`:
- `index: number`. Zero-based current version.
- `count: number`. Number of versions. Renders nothing at 1 or less.
- `onPrev: () => void`. Previous version.
- `onNext: () => void`. Next version.
- `className?: string`. Merged onto the group.

API `MessageError`:
- `title?: string` = "Couldn't finish this response". What didn't happen.
- `description?: React.ReactNode`. Why, in plain words.
- `onRetry?: () => void`. Shows an outline Retry button.
- `retryLabel?: string` = "Retry". The retry button's label.
- `className?: string`. Merged onto the alert.

API `AssistantAvatar`:
- `className?: string`. Merged onto the tile.

### Prompt bar

- Level: Organism
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/prompt-bar`
- Exports: `PromptBar`
- Docs: /design/components/prompt-bar

Prompt bar is the composer under a Copilot or agent conversation: an autosizing textarea with `@` mentions that attach records, `/` commands, a model picker, attachments, dictation and a round Send that turns into Stop while a response runs. Mentions, the command and files become removable chips above the text and travel with the submit as structured details, so the answer is grounded in the right supplier or invoice. Send is the view's one filled button, which is why nothing else near the composer should be filled. The common mistake is wiring it up without `mentions` or a specific placeholder, which leaves people guessing what Copilot can see.

When to use:
- As the composer of the Copilot panel, at `md`, with mentions, commands, models and attachments.
- As the single-line composer of a side panel at `sm`, such as the Contact Center assist panel or a web-call chat with Nora.
- For a one-shot natural-language request that starts a generation, such as describing a report to build.
- Whenever people should be able to pull a supplier, invoice, ticket or agent into the prompt with `@`.

When not to use:
- For a long prompt or agent instructions that people edit like a document, with variables. Use /design/components/prompt-editor instead.
- To generate the value of one form field, such as a tool description. Use /design/components/ai-generate-button instead.
- For a plain multi-line form field such as a note on a supplier. Use /design/components/textarea instead.
- For searching or filtering a list. Use /design/components/search-field instead.
- For a command palette that runs actions without a conversation. Use /design/components/command instead.

Rules:
- The One Filled Button Rule: Send is a filled indigo button, so the composer's view can't have another one. Attach, Add context, the model picker and Dictate are ghost buttons in Slate Meta.
- The Quiet Indigo Rule: Indigo appears on Send, on the live dot beside Listening while dictating, and on the focus ring. Chips are Well Gray.
- The Hairline-and-Lift Rule: The bar is a card surface, `rounded-xl bg-card shadow-border`, with no CSS border. Focus adds a soft ring around the whole bar instead of a border on the textarea.

Anatomy:
- Chips row: Appears once there is a command, a mention or a file: 24px Well Gray chips with an icon, a label, optional meta and a remove button.
- Textarea: Starts at one line and grows to `maxHeight` (240px), then scrolls. 16px text below 768px so mobile browsers don't zoom, 14px above.
- Attach: A 28px ghost icon button, shown when `onAttach` is passed. At `sm` it sits before the text.
- Add context: Inserts `@` at the caret and opens the mention menu. `md` only, when `mentions` is passed.
- Model picker: An extra-small ghost button with the current model and a chevron, opening a radio menu. `md` only, when `models` is passed.
- Dictate: A ghost mic button that swaps to a check while listening. On by default.
- Send: A 28px round filled button with an up arrow, disabled until there is something to send. Becomes Stop, a filled square, while `isRunning`.

States:
- Empty: Placeholder in Slate Meta, Send disabled.
- Focused: Keyboard focus in the textarea draws a 3px Focus Indigo ring at 20% around the whole bar.
- Ready: Send enables once there is text, a command or an attachment, and no file is still uploading.
- Menu open: Typing `@` (or `/` at the very start) opens a popover above the bar (`menuSide="top"`) labelled Add context or Commands, with the first match highlighted. No matches shows No matching records or No matching commands.
- With chips: Picked mentions, the command and attachments sit in a row above the text. The command can only be picked once.
- Uploading: An attachment with `uploading` shimmers its name, shows Uploading and keeps Send disabled.
- Listening: The textarea is replaced by a row: an indigo pulsing dot and Listening, an ink waveform, an elapsed clock and a cancel button. The mic becomes a check that inserts the text.
- Running: Send becomes Stop generating, enabled when `onStop` is passed. Pressing Enter does nothing until it finishes.
- Disabled: The whole bar dims to 60%. The textarea, Attach, Add context, Dictate and Send are disabled; the model picker is not (see known gaps).

Behavior:
- `@` opens the mention menu anywhere after a space or at the start; `/` opens commands only as the first character, and only until a command is picked. Both menus filter by label or id as you type.
- The mention menu shows up to eight matches and leaves out records already picked. Commands aren't capped.
- Picking an item removes the typed trigger and query from the text and adds a chip. Focus stays in the textarea throughout; the menu is driven with `aria-activedescendant`.
- Enter sends, Shift+Enter adds a line. Enter or Tab picks the highlighted menu item instead while a menu is open. IME composition is respected.
- Backspace with the caret at the very start removes the last mention chip, then the command.
- On submit, `onSubmit(text, { mentions, command, model, attachments })` receives trimmed text, then the bar clears its text, mentions and command. Attachments belong to you: clear them in `onSubmit`.
- `value` with `onValueChange` (or its alias `onChange`) makes the text controlled, which is how Copilot drops an edit draft into the composer. `model` with `onModelChange` controls the model the same way.
- Dictation is simulated: the mic shows the listening row, and the check inserts `dictationText` after the current text. Escape or the X cancels without inserting.
- `onAttach` is only a callback; the bar has no file input. You add `PromptAttachment` items, flip `uploading` off when they finish, and remove them in `onRemoveAttachment`.
- The menus open without animation because typing opens them. The model picker is a dropdown menu and animates like one.

Do and don't:
- Do: Write a placeholder that says what Copilot can see: Ask about Northwind Freight.
- Don't: Use filler such as Type your message here. It's the one line that tells people what to ask.
- Do: Let Send be the only filled button around the composer.
- Don't: Add a filled Ask AI or Generate button beside it. Two filled buttons compete, and Enter already sends.

Content:
- Placeholder: Ask about plus what's in context, such as Ask about Northwind Freight or Ask about policy, payments or this supplier. Default Ask anything.
- `label` is the textarea's accessible name and should name the recipient: Message Copilot, Message Nora. Default Message.
- Mention labels are the record's name as people see it in the CRM: Northwind Freight, INV-20931, TCK-1184 Short payment on INV-20877. Use `description` for the kind: Supplier, Invoice, Voice agent.
- Command labels are the bare command, such as summarize or create-ticket. The chip and the welcome copy add the slash.
- Command descriptions say what comes back: Open a ticket with fields filled in.
- Attachment `meta` is the size, 182 KB. While uploading it reads Uploading.

Accessibility:
- The textarea is named by `label` and described by a hidden hint that lists what works: Type @ to add context. Type / at the start for commands. Enter sends, Shift+Enter adds a new line.
- While a menu is open the textarea sets `aria-controls` and `aria-activedescendant`; the menu is a `role="listbox"` of options with `aria-selected`.
- Every icon button has a name and a tooltip: Attach files, Add context (with an @ key hint), Dictate, Insert dictation, Cancel dictation, Send, Stop generating. The model picker reads Model: Auto.
- Chip remove buttons are named Remove Northwind Freight, and focus returns to the textarea after a removal.
- Dictate sets `aria-pressed` while listening, and Listening is a `role="status"`.
- Text is 16px below 768px so iOS doesn't zoom on focus.
- @: Opens the mention menu at the caret.
- /: As the first character, opens the command menu.
- ↓ + ↑: Moves the highlight in an open menu, wrapping.
- Enter: Picks the highlighted item, or sends when no menu is open.
- Tab: Picks the highlighted item while a menu is open.
- Shift + Enter: Adds a new line.
- Esc: Closes the menu, or cancels dictation.
- Backspace: At the start of the text, removes the last chip.

Known gaps (follow the system, not the gap):
- `dictationText` defaults to product copy (Draft a follow-up to Priya about the revised pricing.), and `dictation` defaults to on, so any prompt bar that forgets either shows a mic that inserts that sentence.
- Dictation and attachments are simulated: there is no speech recognition and no file input.
- Focus draws a 3px ring at 20% and no indigo border, softer than the field focus in DESIGN.md (indigo border plus a 3px ring at 50%). Disabled dims to 60% rather than the system's 50%.
- The app's Copilot command labels start with `/` (/summarize), and the chip adds a slash icon, so the chip reads as two slashes.
- The menus are positioned inside the form, not portaled. A parent with `overflow-hidden` clips them.
- At `sm` there is no model picker and no Add context button; mentions still work by typing `@`.
- `disabled` doesn't reach the model picker, which stays clickable on a dimmed bar.

API `PromptBar` (extends Nothing. Only the props below are read.):
- `value?: string`. Controlled text.
- `defaultValue?: string` = "". Initial text when uncontrolled.
- `onValueChange?: (value: string) => void`. Called on every text change. `onChange` is an alias.
- `onSubmit?: (text: string, details: PromptSubmitDetails) => void`. Trimmed text plus `{ mentions, command, model, attachments }`.
- `onStop?: () => void`. Enables Stop while running.
- `isRunning?: boolean` = false. Turns Send into Stop and blocks sending.
- `placeholder?: string` = "Ask anything". Say what Copilot can see.
- `label?: string` = "Message". Accessible name of the textarea.
- `mentions?: { id: string; label: string; description?: string; meta?: string; icon?: React.ReactNode }[]`. Enables `@` and the Add context button.
- `commands?: { id: string; label: string; description?: string; meta?: string; icon?: React.ReactNode }[]`. Enables `/` at the start.
- `models?: { id: string; label: string; description?: string }[]`. Shows the model picker at `md`. Defaults to the first.
- `model?: string`. Controlled model id.
- `onModelChange?: (id: string) => void`. Called when the model changes.
- `attachments?: { id: string; name: string; meta?: string; uploading?: boolean; icon?: React.ReactNode }[]`. Files to show as chips. You own this list.
- `onAttach?: () => void`. Shows Attach files.
- `onRemoveAttachment?: (id: string) => void`. Shows a remove button on each file chip.
- `dictation?: boolean` = true. Shows the mic.
- `dictationText?: string` = "Draft a follow-up to Priya about the revised pricing.". What the simulated dictation inserts.
- `size?: "sm" | "md"` = "md". `md` has a toolbar row; `sm` is one line for side panels.
- `menuSide?: "top" | "bottom"` = "top". Where the menus and model picker open.
- `maxHeight?: number` = 240. Pixels the textarea grows to before scrolling.
- `autoFocus?: boolean`. Focuses the textarea on mount.
- `disabled?: boolean`. Dims the bar and disables the textarea and its buttons.
- `className?: string`. Merged onto the form.

### Approval card

- Level: Organism
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/approval-card`
- Exports: `ApprovalCard`
- Docs: /design/components/approval-card

Approval card is how Copilot and agents act in Oration: every change they propose (update a supplier record, send a remittance email, open a ticket) arrives as a card with what will change, any question it needs answered, and Approve, Edit and Skip. Nothing happens until a person approves, and once they do the card collapses to a one-line receipt with Undo. In a stack of proposals only the focused one carries the filled button; the rest are `emphasis="quiet"`. The common mistake is describing the change in prose instead of showing the fields, before and after.

When to use:
- Whenever Copilot or an agent wants to change data or contact someone: update a record, send an email, reassign a ticket, create an agent.
- When the change has fields worth checking before it runs, such as a supplier's remittance email changing from one inbox to another.
- When the action needs one or two choices from a short list first, such as the ticket's priority and assignee.
- On the Home approvals column and inside Copilot answers, one card per proposed action.

When not to use:
- For a suggestion the person may want to explore but that changes nothing by itself. Use /design/components/recommendation-card instead.
- For a destructive action a person starts themselves, such as deleting a supplier. Use /design/components/confirm-dialog instead.
- For showing a change that already happened. Use /design/components/diff instead.
- For a multi-step plan the agent will carry out after one approval. Show the plan as a task list under the card. Use /design/components/task-list instead.
- For a form with more than a couple of questions or any free text. Use /design/components/form-dialog instead.

Rules:
- The One Filled Button Rule: In a stack of proposals, only the focused one shows a filled Approve. Every other card passes `emphasis="quiet"` and its Approve is outline. When the focused card resolves, the next pending card takes the fill.
- The Tint Well Rule: Fields sit in a 70% Well Gray well with 10px corners inside the card, not in a nested bordered card. Custom content (an email preview, a plan) follows the same rule.
- Every mutation can be undone: Approve and Skip both collapse to a receipt with Undo, and focus moves to Undo so keyboard users can reverse straight away.
- The Label-Beside-Color Rule: Receipts say Approved or Skipped in words beside the green check or the slashed circle.

Anatomy:
- Icon tile: Optional 28px Well Gray tile with a 16px Slate Meta icon for the kind of effect: mail, ticket, record. Never indigo.
- Title: An `h3` at 14px, weight 600: the action, verb first.
- Description: Optional 13px Slate Meta: why the change is proposed.
- Field well: Each field's label in 12px Slate Meta, then the old value struck through, an arrow and the new value. No old value shows a dash read as Empty.
- Footnote: Optional 12px Slate Meta at the start of the footer: the scope, such as Updates 1 supplier record.
- Skip: Ghost, small. Shown when `onSkip` is passed.
- Edit: Outline, small. Shown when `onEdit` is passed.
- Approve: Small and last. Filled at `emphasis="primary"`, outline at `quiet`. Its label is `approveLabel`.
- Receipt: After a decision: a 44px row with a status icon, Approved or Skipped, the title truncated, and a ghost Undo.

States:
- Pending, primary: The full proposal with a filled Approve.
- Pending, quiet: The same proposal with an outline Approve, for every card but the focused one.
- Option selected: A chosen question option takes a 6% indigo tint with a 22% indigo inset ring. Others fill Well Gray on hover.
- Invalid: Approve with an unanswered question shows Choose an option to continue. in red under it and focuses its first option. Nothing is approved.
- Approved: Collapses to a receipt with a Ledger Green check and Approved.
- Skipped: Collapses to a receipt with a Faint Slate slashed circle and Skipped.
- Undone: Undo returns the card to pending, with the answers kept, and focus returns to Approve.

Behavior:
- Approve validates questions first. If one has no answer, it marks every unanswered one invalid and focuses the first; otherwise it calls `onApprove(answers)` with `{ [questionId]: option }` and moves to approved.
- Skip calls `onSkip` and moves to skipped. Undo calls `onUndo` and moves back to pending.
- Edit only calls `onEdit`; the card stays pending. Copilot uses it to drop a draft into the composer so the person can describe the change they want.
- Status is uncontrolled by default (`defaultStatus`). Pass `status` to control it, which Copilot does so a receipt survives re-renders. A controlled card only moves when you update `status` in the callbacks.
- The card springs between heights on `spring.moderate` (160ms, no bounce) while the proposal and the receipt cross-fade, the receipt leaving in 120ms.
- If focus was inside the card when it resolved, focus moves to Undo; after Undo, to Approve. Focus elsewhere on the page is left alone.
- A visually hidden `role="status"` announces Approved: Update remittance email for Northwind Freight or Skipped: ….
- Question defaults come from `defaultValue` and are read once, on mount.

Do and don't:
- Do: In a stack, fill only the focused proposal's Approve and keep the rest quiet.
- Don't: Give every card in the stack a filled Approve. The eye can't find the next decision.
- Do: Title the card with the action and label Approve with the effect: Send remittance email, Create ticket.
- Don't: Ask Are you sure? and confirm with OK. People approve what they can read, and the label is the last thing they read.
- Do: Show the fields that change, old value struck through and new value beside it.
- Don't: Describe the change in a paragraph. A changed bank account or email hides in prose.

Content:
- Title: the action, verb first, naming the record: Update remittance email for Northwind Freight, Open a ticket for Halcyon's short payment.
- Description: why, from the evidence: Aisha asked on today's call to send remittances to the new AP inbox.
- Field labels match the record's attribute names: Remittance email, Payment terms, Assignee.
- Question labels are short questions or nouns: Priority, Who should own it? Options are one or two words each.
- `approveLabel`: the effect, verb first, such as Update supplier, Send email, Create ticket. Default Approve.
- Footnote: the scope in plain words, Updates 1 supplier record, Emails ap@halcyon.example.

Accessibility:
- The title is an `h3`, so the card shows up in a screen reader's headings list inside a Copilot answer.
- Each question is a `fieldset` with a `legend`. Options are native radio inputs (visually hidden inside their labels), so arrow keys move between them and the group is announced as one.
- An invalid question links its error with `aria-describedby`, and Approve moves focus to the question's first option.
- After a decision, focus moves to Undo when it was inside the card, and a hidden status line announces the outcome.
- Under reduced motion the app's motion config drops transforms, but the height spring and the cross-fade still run (see known gaps).
- Tab: Moves through options, Skip, Edit and Approve.
- ← + →: Moves between a question's options and selects.
- Space: Selects the focused option, or presses the focused button.
- Enter: Presses the focused button.

Known gaps (follow the system, not the gap):
- Under reduced motion the height spring and the cross-fade still run; DESIGN.md says disclosures snap. The app's `MotionConfig` only drops transforms.
- There is no failed or running status. If the approved action fails (the ERP rejects the update), the card still reads Approved; Copilot shows progress in a task list below instead.
- The receipt always shows Undo, even without `onUndo`. A controlled card without `onUndo` shows an Undo that does nothing.
- Edit has no editing mode of its own. Every caller has to provide one; Copilot moves a sentence into the composer.
- Questions only take a single choice from chips; there's no free-text answer.
- The title is always an `h3`, whatever the surrounding heading levels.

API `ApprovalCard` (extends Nothing. Only the props below are read.):
- `title: string`. The action, verb first. Also shown in the receipt.
- `description?: React.ReactNode`. Why it's proposed.
- `fields?: { label: string; before?: React.ReactNode; after: React.ReactNode }[]`. Rendered as a stacked diff in a tint well.
- `questions?: { id: string; label: string; options: string[]; defaultValue?: string }[]`. Single-choice questions that must be answered before Approve.
- `children?: React.ReactNode`. Custom content after the fields, e.g. an email preview.
- `icon?: React.ReactNode`. Shown in a 28px tile.
- `footnote?: React.ReactNode`. Quiet scope note in the footer.
- `onApprove?: (answers: Record<string, string>) => void`. Called after questions validate.
- `onEdit?: () => void`. Shows Edit. Doesn't change status.
- `onSkip?: () => void`. Shows Skip.
- `onUndo?: () => void`. Called by the receipt's Undo.
- `status?: "pending" | "approved" | "skipped"`. Controlled status.
- `defaultStatus?: "pending" | "approved" | "skipped"` = "pending". Initial status when uncontrolled.
- `approveLabel?: string` = "Approve". Name the effect.
- `emphasis?: "primary" | "quiet"` = "primary". `quiet` makes Approve outline, for every card but the focused one in a stack.
- `className?: string`. Merged onto the card.

### Recommendation card

- Level: Organism
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/recommendation-card`
- Exports: `RecommendationCard`, `ConfidenceMeter`
- Docs: /design/components/recommendation-card

Recommendation card proposes a next step and shows its working: a title that names the step, the rationale in plain words, a `ConfidenceMeter` (High confidence 86%), the expected impact in a tint well, optional sources and the actions to take it. It powers the Contact Center's next best action and Copilot's suggestions. Unlike an approval card it changes nothing by itself; the person decides whether and how to act. The common mistake is coloring confidence: it is ink, with a word beside it, never green or indigo.

When to use:
- For the next best action in the Contact Center assist panel: Email the ACH trace to Northwind Freight.
- Inside a Copilot answer, when the answer ends in a suggestion the person can follow up on.
- When the suggestion is uncertain enough that how sure the model is, and why, should be visible.
- When there is a concrete impact to weigh, such as a late fee avoided or a repeat call saved.

When not to use:
- For an action Copilot will perform once approved, with fields that change. Use /design/components/approval-card instead.
- For a finding with a metric and a trend, such as calls getting shorter. Use /design/components/insight-card instead.
- For the sources of an answer on their own. Use /design/components/source-cards instead.
- For a measured value such as credits used or talk ratio. Use /design/components/meter instead.
- For a system notice that needs attention, such as an expired W-9. Use /design/components/alert instead.

Rules:
- The Ink Fill Rule: Confidence is a magnitude, not a verdict, so its meter is Ink 65 on a Well Gray track. It is never indigo, and never green, amber or red.
- The Label-Beside-Color Rule: The meter always travels with a word (High, Medium or Low confidence) and the percentage in tabular figures, so it reads in grayscale.
- The Tint Well Rule: The impact sits in a 70% Well Gray well inside the card, and sources are tint-well cards, never nested bordered cards.
- The One Filled Button Rule: At most one filled button in `actions`. In the assist panel and in Copilot, where the view already has a primary action, use outline and ghost.

Anatomy:
- Icon tile: Optional 28px Well Gray tile with a 16px Slate Meta icon.
- Title: An `h3` at 14px, weight 600: the step, verb first.
- Confidence meter: Top right: the band word in 12px Slate Meta, a 48px by 4px ink meter and the percentage in 12px medium tabular figures. Wraps under the title when space is short.
- Rationale: 13px Slate Meta: the evidence behind the step.
- Impact well: A structured impact puts its label at the left in Slate Meta and its value at the right in medium tabular figures. Any other node renders as is in the well.
- Sources: Optional numbered source cards in a sideways-scrolling row.
- Actions: Buttons in a wrapping row with 6px gaps.

States:
- High confidence: 80% and above.
- Medium confidence: 55% to 79%.
- Low confidence: Below 55%. Values outside 0 to 1 are clamped.
- Acted on: The card has no built-in state. The assist panel swaps its actions for a green check and Done, and offers Undo in the toast.
- Dismissed: Also the caller's job: the assist panel removes the card on Not now.
- Source hover and focus: Linked source cards fill Well Gray on hover and draw a 3px Focus Indigo ring at 40% on focus.

Behavior:
- It's a static `<article>`; only the buttons you pass in `actions` and linked sources are interactive.
- `confidence` is 0 to 1. The meter rounds it to a whole percentage, and `confidenceLabel(value)` picks the band at 0.8 and 0.55.
- `impact` as `{ label, value }` renders the two-column well. Pass any other node for a custom well, or leave it out.
- `sources` renders `SourceCards` in the row layout, numbered from 1.
- The header wraps: on a narrow card the confidence meter drops under the title instead of squeezing it.

Do and don't:
- Do: Show confidence in ink with its band word and percentage.
- Don't: Color it green for sure and red for unsure. Confidence isn't good or bad news, and color alone doesn't say how sure.
- Do: Write the rationale from the evidence: Northwind called three times since Friday and asked for the trace each time.
- Don't: Write a rationale that only restates the model: AI thinks this is the best next step for this customer.

Content:
- Title: the step, verb first, with the object: Email the ACH trace to Northwind Freight, Offer the early-payment discount explanation.
- Rationale: one or two sentences of evidence: what was said, what the record shows. Name invoices and payments by ID.
- Impact label: a verb or short noun, Avoids, Recovers, Saves. Value: the measured effect, a fourth call this week, $760.00 in disputed discount.
- Actions: the step as a verb phrase, Send trace and remittance, plus a quiet Not now.

Accessibility:
- The card is an `<article>` with an `h3` title, so it's reachable by heading.
- The confidence meter is `role="meter"` named Confidence, with the value out of 100. The band word and percentage are visible text beside it.
- Source cards that link are anchors; external ones say (opens in a new tab) to screen readers.
- Keyboard reaches only the actions and linked sources, in reading order.

Known gaps (follow the system, not the gap):
- The bands are fixed at 0.8 and 0.55; a page can't tune them for a model that runs hot or cold.
- There's no built-in done, dismissed or loading state. The assist panel hand-rolls Done and Not now, and Copilot passes a single outline action.
- The title is always an `h3`.
- `confidenceLabel` is exported but not listed in the registry.

API `RecommendationCard` (extends Nothing. Only the props below are read.):
- `title: string`. The step, verb first.
- `rationale: React.ReactNode`. The evidence.
- `confidence: number`. 0 to 1.
- `impact?: { label: string; value: React.ReactNode } | React.ReactNode`. Structured for the two-column well, or any node.
- `actions?: React.ReactNode`. Buttons. At most one filled.
- `icon?: React.ReactNode`. Shown in a 28px tile.
- `sources?: { id: string; title: string; snippet: string; kind: "doc" | "url" | "record" | "transcript"; href?: string; score?: number; meta?: string }[]`. Rendered as a source card row.
- `className?: string`. Merged onto the article.

API `ConfidenceMeter`:
- `value: number`. 0 to 1, clamped.
- `className?: string`. Merged onto the wrapper.

API `confidenceLabel`:
- `value: number`. 0 to 1.
- `returns?: "High confidence" | "Medium confidence" | "Low confidence"`. High at 0.8 and above, medium at 0.55 and above.

### Insight card

- Level: Organism
- Category: AI
- Status: Beta
- Import: `@oration/canon/components/ai/insight-card`
- Exports: `InsightCard`
- Docs: /design/components/insight-card

Insight card reports one finding the model surfaced from Cedarline's data: a title that states the finding, what it's based on, an optional metric in a row with its change, an optional small chart, the explanation, its sources and what to do next. It fills the Agents home What changed this week, ticket report insights, campaign rails and Copilot answers. The metric is a 20px figure beside its label, not a hero number, so a row of insight cards never turns into a metric mosaic. The common mistake is titling it with a metric name instead of the finding.

When to use:
- For a weekly finding on a home or overview page: Texting the remittance link shortens calls.
- Beside an analytics chart, to say in words what moved and why.
- Inside a Copilot answer to an analysis question, when there's one metric worth naming.
- When the finding needs its evidence: calls, records or documents it came from.

When not to use:
- For a next step with a confidence level. Use /design/components/recommendation-card instead.
- For a row of headline metrics at the top of a page. Use /design/components/inline-stat-strip instead.
- For one metric with its label and change and no explanation. Use /design/components/stat instead.
- For a trend that deserves axes, a legend and a tooltip. Use /design/components/chart instead.
- For a generated summary of one record or conversation. Use /design/components/streaming-text instead.

Rules:
- No hero metrics: DESIGN.md refuses hero-metric card grids. The insight's metric is a 20px figure on the same line as its label and delta, and the card's job is the sentence, not the number.
- The Tabular Figures Rule: The metric value and delta are set in tabular figures so cards side by side line up.
- The Ink Fill Rule: Charts inside the card are ink, such as an area `MiniChart` in its default tone. Only the delta turns semantic, because better or worse is a verdict.
- The Quiet Indigo Rule: The sparkles mark is Slate Meta. Nothing in the card is indigo.

Anatomy:
- Mark: A 16px Slate Meta icon, sparkles by default. Decorative.
- Title: An `h3` at 14px, weight 600: the finding as a sentence.
- Meta: Optional 12px Slate Meta: what it's based on.
- Metric: Optional: the value at 20px, weight 600, tabular; its label in 13px Slate Meta; then the delta.
- Delta: 12px medium tabular with an up-right or down-right arrow. Ledger Green when the direction is good, Signal Red when it isn't.
- Chart: Optional, full width. Usually a 40px area `MiniChart`.
- Summary: 13px ink at 85%: what happened and why.
- Sources: Optional numbered source cards in a sideways-scrolling row.
- Actions: Buttons in a wrapping row, usually outline.

States:
- Good change: The delta moves in `goodDirection`: green, with the arrow in that direction.
- Bad change: The delta moves against it: red.
- No metric: Leave out `metric` and the card is title, summary, sources and actions.
- Loading, empty, error: Not built in. Pages wrap the cards in `DataState` with a `SkeletonCard` per card, an empty state that teaches, and a retry.

Behavior:
- It's a static `<article>`; only actions and linked sources are interactive.
- A numeric `delta` is a fraction: `-0.18` renders 18% with a down arrow. A string is shown as written without its sign, such as +6 pts as 6 pts with an up arrow.
- Direction comes from the sign. `goodDirection` (default `up`) decides the color only; the arrow always shows the direction.
- `chart` renders full width between the metric and the summary. Size the chart to its container, such as `className="h-10 w-full"`.
- `sources` renders `SourceCards` in the row layout.

Do and don't:
- Do: Title the card with the finding: Texting the remittance link shortens calls.
- Don't: Title it with the metric: Average call duration. The reader has to work out what changed and whether it matters.
- Do: Keep the metric on one line with its label and change, and let the summary explain it.
- Don't: Build a grid of big numbers with tiny labels and trend chips. It's the hero-metric mosaic the system refuses.

Content:
- Title: the finding as a sentence in sentence case, with the cause if known: Spanish line containment rose after the numbers coaching.
- Meta: the base and the window: Based on 1,422 remittance calls this week, Since Sep 2, 894 calls.
- Metric label: lowercase noun phrase that reads after the value: 41 s shorter average call, 74% containment.
- Summary: two sentences at most. What changed, why, and what isn't done yet.
- Actions: verbs that lead somewhere: Create coaching, Compare calls.

Accessibility:
- The card is an `<article>` with an `h3`, reachable by heading.
- The delta adds a hidden Up or Down before its figure, so the direction is read out. Whether that's good isn't announced (see known gaps).
- The mark is `aria-hidden`.
- Give a `MiniChart` an `ariaLabel` that names the series and window, such as Average call length, 14-day trend.

Known gaps (follow the system, not the gap):
- Whether a delta is good or bad is shown by color only. The arrow and the hidden Up or Down give the direction, not the judgment.
- A string delta loses its sign in the text (+6 pts shows as 6 pts); only the arrow keeps it.
- The summary is ink at 85% (`text-foreground/85`), an alpha that isn't one of the named text tokens.
- No loading, empty or error state. Every page wraps the cards in `DataState` itself.
- The title is always an `h3`.

API `InsightCard` (extends Nothing. Only the props below are read.):
- `title: string`. The finding as a sentence.
- `summary: React.ReactNode`. What happened and why.
- `metric?: { label: string; value: React.ReactNode; delta?: number | string; goodDirection?: "up" | "down" }`. One metric in a row. A numeric delta is a fraction; `goodDirection` defaults to `up`.
- `chart?: React.ReactNode`. Usually a `MiniChart`.
- `sources?: Source[]`. Rendered as a source card row. See Source cards.
- `actions?: React.ReactNode`. Buttons.
- `meta?: React.ReactNode`. What it's based on.
- `icon?: React.ReactNode`. Replaces the sparkles mark.
- `className?: string`. Merged onto the article.

### Selection actions

- Level: Organism
- Category: AI
- Status: Experimental
- Import: `@oration/canon/components/ai/selection-actions`
- Exports: `SelectionActions`
- Docs: /design/components/selection-actions

Selection actions is a floating AI toolbar that appears over selected text inside whatever it wraps: a textarea, an input, a contenteditable or plain read-only text. It offers Rewrite, Shorten, Expand, Change tone, Translate and Ask, previews the result as a word diff, and only changes the text when the person accepts. In editable fields the replacement goes through the browser's own editing, so native undo still works. It's experimental and not used in the app yet; the common mistake would be wrapping a whole page in it, so every selected invoice number pops an AI toolbar.

When to use:
- Around long-form text people write for suppliers: a remittance email draft, a ticket reply, a campaign message.
- Around read-only generated text that people may want to tighten before copying, such as a call summary, with `onApply` to store the change.
- When the edit is local to a passage. Rewriting the whole field from a description is a different job.

When not to use:
- To generate or rewrite a whole field from a short instruction. Use /design/components/ai-generate-button instead.
- For editing an agent's prompt, where the editor has its own inline AI. Use /design/components/prompt-editor instead.
- For a conversation about the text. Send it to Copilot instead. Use /design/components/thread instead.
- Around tables, IDs, amounts or form fields with short values.
- For a toolbar of formatting controls on a selection. Use /design/components/toolbar instead.

Rules:
- Preview, then accept: Nothing changes until the person accepts. Rewrite, Shorten, tone changes and custom edits show a word diff against the selection; Expand and Translate show the new text.
- The One Filled Button Rule: Inside the floating layer the only filled buttons are Accept (or Copy) on a result and Send instruction in Ask. The toolbar items are quiet text buttons.
- The Tint Well Rule: The result sits in a 70% Well Gray well inside the popover surface.

Anatomy:
- Floating surface: Popover White, 12px corners, 4px padding and the overlay shadow, fixed 8px above the selection (below it when there's no room) and kept 8px inside the viewport.
- Actions: 28px text buttons with a 14px icon in Slate Meta: Rewrite, Shorten and Expand by default. A fluid Well Gray highlight follows the pointer and the arrow keys.
- Tone: A menu of tones. Hidden when `tones` is empty.
- Translate: A menu of languages. Hidden when `languages` is empty.
- Ask: Opens a one-line instruction field, Tell AI how to change this…, with a filled send button. Hidden with `allowAsk={false}`.
- Result: The action's name, then the diff or new text in a tint well, up to 192px tall before it scrolls.
- Try again: A ghost icon button that reruns the same request.
- Discard and Accept: Ghost Discard and a filled Accept. Accept reads Copy when the text can't be replaced.

States:
- Closed: No selection, or the selection is outside the container.
- Menu: Text is selected: the toolbar springs in from 0.97 scale over 80ms. Screen readers hear AI actions available. Press Command J. once.
- Ask: The toolbar becomes the instruction field, focused.
- Pending: A pixel-grid loader and a shimmering label, such as Rewriting…, with Cancel.
- Result: The preview with Try again, Discard and Accept. Accept is focused.
- Error: A red alert icon, Couldn't finish that edit., Try again (focused) and Discard.
- Item hover and focus: The fluid highlight sits under the item and its text turns ink; keyboard focus adds a 2px Focus Indigo ring at 50%.

Behavior:
- It listens for selections inside `children` (wrapped in a div) or inside the element at `containerRef`. Selecting with the pointer, Shift and the arrow keys, or ⌘A all open it.
- With text selected, ⌘J (Ctrl+J elsewhere) opens the toolbar and moves focus to its first item. Arrow Left and Right, Home and End move between items.
- Escape closes the menu, steps back from Ask to the menu, or discards a pending or finished result and restores the selection.
- `onAction(actionId, selectedText, options)` runs the request. Return a string or a Promise of one; a rejected Promise shows the error state. A synchronous result waits `simulateMs` (700ms) so the pending state is visible.
- `options` carries `tone` for Change tone, `language` for Translate and `prompt` for Ask. Their action ids are `tone`, `translate` and `ask`.
- Accept in a textarea or input replaces the selection through `execCommand("insertText")`, so ⌘Z undoes it, and raises Selection replaced with Undo. In a contenteditable it replaces the range. In read-only text it calls `onApply(newText, selection)`; without `onApply` it copies the result and toasts Copied to clipboard.
- Clicking outside closes it. It follows the selection when the page scrolls or resizes. A newer request cancels an older one still in flight.
- The layer is portaled to the body and exits in 60ms.

Do and don't:
- Do: Wrap the passage people write, such as the reply body, and point `containerRef` at it.
- Don't: Wrap the whole page. Selecting an invoice number or an amount shouldn't open an AI toolbar.
- Do: Return the edited passage only, so the diff shows exactly what changed.
- Don't: Return the whole document or a chatty reply such as Sure, here's a shorter version. It replaces the selection as written.
- Do: Pass `onApply` for read-only text you can update, so Accept means accept.
- Don't: Leave read-only text without `onApply` when people expect the change to stick. Accept quietly becomes Copy.

Content:
- Action labels are single verbs or short verb phrases: Rewrite, Shorten, Fix grammar, Make formal.
- `pendingLabel` is the verb in progress with an ellipsis: Rewriting…, Fixing grammar…. The default is Working on it….
- Tone and language options are single words in sentence case: Professional, Friendly, Spanish.
- Results should read as the person's own text, in the same voice and person, with IDs and amounts unchanged.

Accessibility:
- The toolbar is `role="toolbar"` named Edit selection with AI, with arrow-key movement between items.
- Opening is announced once per selection through a polite live region: AI actions available. Press Command J. (Control J off Apple platforms).
- Focus moves into the layer when it matters: the first item on ⌘J, the field in Ask, Accept on a result, Try again on an error, and Cancel while pending if focus was already inside.
- The pending row is `role="status"`, the error is `role="alert"`, and the result is a group named Suggested edit.
- Pointer presses inside the layer don't steal the selection, so the text stays highlighted while you choose.
- Discard and Escape restore the original selection, so keyboard users land back where they were.
- ⌘ + J: With text selected, opens the toolbar and focuses it. Ctrl+J off Apple platforms.
- ← + →: Moves between toolbar items.
- Home: First item.
- End: Last item.
- Enter: Runs the focused action, or sends the Ask instruction.
- Esc: Closes, steps back from Ask, or discards and restores the selection.

Known gaps (follow the system, not the gap):
- It isn't used anywhere in the app. Fields get `AIGenerateButton` and the prompt editor has its own inline AI.
- The result's Try again is an icon button with an `aria-label` but no tooltip.
- Only field replacements get an Undo toast. Contenteditable relies on native undo, and `onApply` gets none, so callers must offer their own.
- Accept on read-only text without `onApply` silently becomes Copy.
- Replacement uses `document.execCommand("insertText")`, which is deprecated, with `setRangeText` as the fallback.
- The panels it renders (`SelectionToolbar`, `SelectionResult` and the rest in `selection-panels`) are exported but undocumented; this page renders them statically only to show the anatomy and states.
- Not checked: how it competes with the native selection menu on iOS and Android.

API `SelectionActions` (extends Nothing. Only the props below are read.):
- `onAction: (actionId: string, selectedText: string, options: { language?: string; tone?: string; prompt?: string }) => Promise<string> | string`. Produces the replacement text.
- `children?: React.ReactNode`. Content to watch, wrapped in a div. Omit when using `containerRef`.
- `containerRef?: React.RefObject<HTMLElement | null>`. Watch an existing element instead of wrapping children.
- `actions?: { id: string; label: string; pendingLabel?: string; icon?: React.ReactNode; diff?: boolean }[]` = Rewrite, Shorten, Expand. `diff` previews the result as a word diff.
- `languages?: string[]` = Spanish, French, German, Portuguese, Japanese, Hindi. Pass `[]` to hide Translate.
- `tones?: string[]` = Professional, Friendly, Direct, Confident, Empathetic. Pass `[]` to hide Change tone.
- `allowAsk?: boolean` = true. Shows Ask.
- `onApply?: (newText: string, range: CapturedSelection) => void`. Called on Accept. Required to replace read-only text.
- `simulateMs?: number` = 700. How long a synchronous `onAction` appears to work.
- `className?: string`. Merged onto the wrapper div when using `children`.

### Latency timeline

- Level: Organism
- Category: Voice
- Status: Beta
- Import: `@oration/canon/components/voice/latency-timeline`
- Exports: `LatencyTimeline`, `formatMs`, `percentile`
- Docs: /design/components/latency-timeline

Latency timeline charts how long a voice agent such as Nora took to answer, turn by turn: each bar is one turn's end-to-end latency, stacked into speech-to-text, LLM and text-to-speech in ink steps, against a dashed target and budget line. A summary above gives p50, p95 and the last turn with a status label, and hovering or arrowing through turns opens a readout with first-byte time (TTFB) and each stage in milliseconds. It's how people find the slow turn in a supplier call and jump to it. The common mistake is coloring bars by threshold; the bars stay ink and the status label carries the verdict.

When to use:
- On a call's detail page, beside the transcript, so a click on a slow turn jumps playback there.
- In the metrics tab of a live web call with Nora, with bars growing in as she answers.
- When people tune an agent's speed and need to see which stage (STT, LLM or TTS) dominates.
- As a sparkline in a narrow panel, such as a web call's metrics tab, where only the shape of end-to-end latency matters.

When not to use:
- For a single latency figure in a table cell or a list row. Use /design/components/latency-sparkline instead.
- For latency across many calls over days or weeks, with axes and a legend. Use /design/components/chart instead.
- For a percentage or count with a label, such as containment rate. Use /design/components/stat instead.
- For the words of the turns themselves. Use /design/components/live-transcript instead.
- For a generic small trend that isn't per-turn latency. Use /design/components/mini-chart instead.

Rules:
- The Ink Fill Rule: Bars are magnitudes, so they're ink: STT, LLM and TTS stack from lighter to darker, with the remainder faintest. Thresholds are dashed lines, not bar colors.
- The Label-Beside-Color Rule: The verdict on the last turn, and on any turn in the readout, is a status label with words: On target, Slow or Over budget.
- The Tabular Figures Rule: Every number (p50, p95, the axis labels, the readout) is set in tabular figures, in milliseconds with a thousands separator: 1,310 ms.

Anatomy:
- Summary: p50, p95 and Last: a 12px Slate Meta label above a 14px medium value. A dash until the first turn.
- Status: The last turn's verdict as a status label, right-aligned.
- Bars: One per turn, at most 16px wide with 2px gaps and 3px top corners: STT, LLM, TTS and the remainder stacked bottom to top.
- Target line: Dashed ink at 20% at `thresholds.good` (800 ms by default).
- Budget line: Dashed Signal Red at 45% at `thresholds.warn` (1,200 ms by default).
- Axis labels: Target and Budget with their values in 11px Slate Meta, in a 48px column on the right.
- Legend: 11px swatches for STT, LLM, TTS and Other. Bars only.
- Readout: On hover or focus: a 176px popover card with the turn number, speaker, end to end, first byte, each stage and its status. It stays inside the plot's edges.

States:
- Empty: A Well Gray well reads Latency shows up after the first turn. The summary shows dashes.
- On target: Last turn at or under `good`: a green dot and On target.
- Slow: Over `good`, at or under `warn`: an amber dot and Slow.
- Over budget: Over `warn`: a red dot and Over budget.
- Turn active: Hovering or arrowing to a turn fills its column Well Gray and opens the readout. In the sparkline, a point marks the turn.
- Focus visible: The plot draws a 2px Focus Indigo ring at 50% with a 2px offset.
- New turn: A turn that arrives after mount grows up from the baseline on `spring.moderate`. Turns present on mount don't animate.

Behavior:
- The scale runs from 0 to the larger of 115% of `warn` and the slowest visible turn, so the budget line is always in view.
- Only the last `maxTurns` (40) are drawn. The summary's p50, p95 and Last use every turn passed in.
- Each bar's segments are `sttMs`, `llmMs` and `ttsMs`, with whatever remains of `e2eMs` as Other. Leave out `llmMs` or `ttsMs` and that segment and its readout row disappear.
- Focusing the plot selects the last turn. Arrow Left and Right step through turns, Home and End jump to the first and last, Escape clears, and Enter or Space calls `onTurnSelect`. Each step is announced politely.
- Click a turn to call `onTurnSelect(turn)`, which the call detail page uses to seek the recording.
- In the sparkline variant, the pointer's x position picks the nearest turn. There's no legend, since there are no segments.
- The readout enters on `spring.fast` from 2px below and leaves in 60ms.

Do and don't:
- Do: Keep bars in ink and let the status label and the budget line say what's slow.
- Don't: Color each bar green, amber or red. The chart turns into a traffic light, and the stage breakdown disappears.
- Do: Set `thresholds` to the agent's real budget, and use the same values in any table beside it.
- Don't: Leave the defaults on an agent whose budget is different. A Slow label people can't trust is worse than none.
- Do: Judge a call by p95 and the slow turns, and click through to hear them.
- Don't: Judge it by the average. One 2-second pause is what the supplier remembers.

Content:
- Stage names are the industry abbreviations, STT, LLM and TTS, explained once in an `InfoTip` beside the section title, along with TTFB.
- Values are milliseconds with a thousands separator and a space: 1,310 ms.
- Pass `speaker` so the readout can say Agent or Caller.
- If the section has a title, call it Latency and describe the base: 14 agent turns.

Accessibility:
- The plot is a focusable `role="group"` named Latency by turn, 14 turns. Use the arrow keys to inspect a turn.
- Each turn is announced in a polite live region as it's selected: Turn 5, 1,310 ms end to end, first byte 780 ms, STT 240 ms, LLM 760 ms, TTS 190 ms, Over budget.
- The readout card, bars, lines and axis labels are `aria-hidden`; the live region carries the same information.
- Statuses are words beside dots. Stages differ by lightness only, and the legend and readout name them.
- Under reduced motion the app's motion config drops the grow-in and the readout's translate.
- Tab: Focuses the plot and selects the last turn.
- ← + →: Previous or next turn.
- Home: First turn.
- End: Last turn.
- Enter: Calls `onTurnSelect` for the selected turn.
- Space: Calls `onTurnSelect` for the selected turn.
- Esc: Clears the selection.

Known gaps (follow the system, not the gap):
- Segments use ink at 30, 55, 80 and 12%, not the system's ink steps (80, 65, 45, 25, 15).
- `ttfbMs` is required but only appears in the readout; nothing plots it.
- The plot's focus ring is 2px at 50% with an offset, not the 3px ring at 40% the rest of the suite uses.
- Nearest-rank p95 equals the slowest turn on short calls (under 20 turns), which can read as harsher than expected.
- `latencyStatus` is exported but not listed in the registry.
- The Target and Budget axis labels always render, in a fixed 48px column, and there's no prop to hide them. Below about 96px of `height` they overlap, so the chart can't shrink into a table row.

API `LatencyTimeline` (extends Nothing. Only the props below are read.):
- `turns: { id: string; index: number; e2eMs: number; ttfbMs: number; sttMs: number; llmMs?: number; ttsMs?: number; speaker?: "agent" | "user" }[]`. One entry per turn, in order. `index` is the 1-based turn number shown in the readout.
- `thresholds?: { good: number; warn: number }` = { good: 800, warn: 1200 }. Target and budget in ms.
- `variant?: "bars" | "sparkline"` = "bars". Stacked bars, or an end-to-end line.
- `height?: number` = 96. Plot height in px.
- `maxTurns?: number` = 40. How many recent turns to draw.
- `showSummary?: boolean` = true. p50, p95, Last and status.
- `showLegend?: boolean` = true. Stage legend, bars only.
- `onTurnSelect?: (turn: LatencyTurn) => void`. Click, Enter or Space on a turn.
- `className?: string`. Merged onto the root.

API `formatMs`:
- `ms: number`. Rounded to a whole number.
- `returns?: string`. 1,310 ms.

API `percentile`:
- `values: number[]`. Any order. Returns 0 when empty.
- `p: number`. 0 to 100.

API `latencyStatus`:
- `ms: number`. End-to-end latency.
- `t: { good: number; warn: number }`. Thresholds.
- `returns?: { tone: StatusTone; label: "On target" | "Slow" | "Over budget" }`. For a `StatusLabel`.

### Live transcript

- Level: Organism
- Category: Voice
- Status: Beta
- Import: `@oration/canon/components/voice/live-transcript`
- Exports: `LiveTranscript`
- Docs: /design/components/live-transcript

Live transcript shows a voice call as it happens: each turn under its speaker's name, with the flow node that handled it, its latency and a timestamp, plus centered system lines for events such as a transfer. Words still being recognised or spoken render as interim text, muted, italic and shimmering, and settle into ink when final. It keeps the newest turn in view until the reader scrolls up, then offers Jump to latest. It's the transcript tab of a web call with Nora; the common mistake is giving it no bounded height, so it can't scroll.

When to use:
- In the transcript tab of a live web call with Nora, beside the call controls.
- When someone testing a flow needs to see which node produced each turn.
- When interim recognition matters, such as checking how Nora hears invoice numbers as a supplier says them.
- For short system events within the call: call started, transferred to accounts payable, call ended.

When not to use:
- For a chat with Copilot or an agent that people type into. Use /design/components/thread instead.
- For a finished call's recording and transcript on its detail page, with playback. Use /design/components/timeline instead.
- For per-turn latency as a chart. Use /design/components/latency-timeline instead.
- For a single tool call an agent made during the turn. Use /design/components/tool-chip instead.
- For a customer conversation in the Contact Center inbox. Use /design/components/bubble instead.

Rules:
- The Quiet Indigo Rule: Indigo appears only as the small pulsing dot beside the agent's name while the agent is speaking, a live state that travels with a label (the name). Everything else is ink, Slate Meta and Well Gray.
- The Tabular Figures Rule: Timestamps and latencies are tabular, so the right-hand column doesn't wobble as turns arrive.
- The Tint Well Rule: Flow-node tags are small 70% Well Gray chips, and the empty state is a Well Gray well.

Anatomy:
- Speaker: 12px ink at weight 500: `agentName` or `userName`.
- Flow-node tag: A 20px Well Gray chip with a workflow icon and the node's name in 11px Slate Meta.
- Latency: The turn's end-to-end latency in 12px tabular Slate Meta: 640 ms.
- Timestamp: Seconds since the call started, as 0:11 or 1:02:15, or a preformatted string.
- Turn text: 14px ink at a relaxed line height. Long words wrap.
- Interim text: Muted, italic and shimmering until final. An agent's interim turn adds a pulsing indigo dot before the name.
- System line: A centered 12px Slate Meta line between hairlines, with an optional node tag and time.

States:
- Empty: A Well Gray well with `emptyState`, by default The transcript starts when someone speaks.
- Final turn: Ink text, announced politely to screen readers.
- Interim turn: Muted, italic, shimmering, with a hidden (still speaking). The list is `aria-busy` while any turn is interim.
- Agent speaking: An interim agent turn shows the pulsing indigo dot before the name.
- Interrupted: `metrics.interrupted` adds Interrupted in Slate Meta on the header line.
- Scrolled up: Following stops, and an outline Jump to latest button fades in 8px above the bottom.
- Focus visible: The scroll region is focusable and draws a 2px Focus Indigo ring at 50%.
- New turn: Turns that arrive after mount fade up 4px on `spring.moderate`. Turns present on mount don't animate.

Behavior:
- Pass the whole list of turns on every update; update a turn in place (same `id`) to move it from interim to final.
- While the reader is within 24px of the bottom, growth keeps the newest turn in view. Scrolling up stops it; Jump to latest scrolls back smoothly, or jumps under reduced motion.
- `autoScroll={false}` turns following off entirely.
- Each turn that becomes final is announced once in a polite live region, as Nora: OS-4471 was paid by ACH on Friday. System lines are announced as their text.
- `at` as a number is seconds since the call started; as a string it's shown as written.
- Interim text changes color over 200ms when it settles. The shimmer stops under reduced motion.
- It doesn't size itself. Give it a bounded height such as `h-80`, or `flex-1 min-h-0` inside a flex column.

Do and don't:
- Do: Label turns with the node name people see on the flow canvas: Payment status.
- Don't: Show internal node IDs such as node_7f3a2c. Nobody can match them to the canvas.
- Do: Name both sides: the persona the supplier hears, and the caller when you know them.
- Don't: Leave the defaults Agent and Caller when the agent is Nora and the caller is a known supplier contact.
- Do: Give it a bounded height so it scrolls and keeps the latest turn in view.
- Don't: Let it grow with the page. The newest turn ends up below the fold and auto-scroll does nothing.

Content:
- `agentName` is the persona, Nora. `userName` is the caller's name when known, Aisha Bello, or You in a test call.
- Node labels match the canvas exactly, in sentence case: Identify supplier, Payment status, Transfer to AP.
- System lines are short past-tense events: Call started, Transferred to accounts payable, Call ended.
- `emptyState` says when the transcript will start: The transcript starts when Nora picks up.
- Transcribed text stays as recognised. Don't correct it after the fact; that's what makes the transcript useful for tuning.

Accessibility:
- The scroll region is a focusable `role="region"` named Live transcript, so keyboard users can scroll it with the arrow keys.
- Final turns are announced through a polite live region with the speaker's name. Interim text isn't announced, and the list is `aria-busy` while any turn is interim.
- Interim turns carry a hidden (still speaking) so the state doesn't rely on italics or color.
- Latency has a hidden Latency label before the figure.
- Jump to latest is a text button, reachable with Tab whenever it's shown.
- Under reduced motion the shimmer stops, the jump is instant, and the app's motion config drops the fade-up translate.
- Tab: Focuses the transcript region, then Jump to latest when shown.
- ↑ + ↓: Scrolls the focused region.
- Enter: Activates Jump to latest.

Known gaps (follow the system, not the gap):
- `metrics.ttfbMs` is accepted but never shown.
- Timestamps render in `<time>` without a `dateTime` attribute.
- Only agent interim turns get the speaking dot; a caller's interim turn has no live marker beyond the shimmer.
- The registry describes it as two-sided, but turns are one left-aligned column with speaker names, not two sides.
- The call detail page in Agent history uses its own transcript panel, not this component, so the two transcripts look and behave differently.
- It has its own stick-to-bottom logic (24px threshold) and a text Jump to latest, while Thread uses 48px and an icon-only button.
- The region's focus ring is 2px at 50%, not the 3px ring at 40% used elsewhere.

API `LiveTranscript` (extends Nothing. Only the props below are read.):
- `turns: { id: string; speaker: "agent" | "user" | "system"; text: string; interim?: boolean; at?: number | string; nodeLabel?: string; metrics?: { e2eMs?: number; ttfbMs?: number; interrupted?: boolean } }[]`. Every turn so far, in order.
- `agentName?: string` = "Agent". Shown on agent turns.
- `userName?: string` = "Caller". Shown on user turns.
- `autoScroll?: boolean` = true. Keep the latest turn in view.
- `emptyState?: React.ReactNode` = "The transcript starts when someone speaks.". Shown before the first turn.
- `className?: string`. Merged onto the root. Give it a bounded height.

API `formatAt`:
- `at: number | string`. Seconds, or a preformatted string.
- `returns?: string`. 0:11, 12:04 or 1:02:15.

## Utilities

### Fluid hover

- Level: Utility
- Category: Utilities
- Status: Stable
- Import: `@oration/canon/hooks/use-fluid-hover`
- Exports: `useFluidHover`, `FluidHoverHighlight`
- Docs: /design/components/fluid-hover

Fluid hover draws one highlight per list that glides to the item under the pointer, instead of every row blinking its own hover fill on and off. `useFluidHover` measures the items and tracks the nearest one; `FluidHoverHighlight` paints it. It runs the settings nav, ticket and queue lists, copilot history, menus and tab strips. Most bugs come from skipping the container contract: the container is `relative isolate`, takes `ref` and the spread `handlers`, marks items with `data-fluid-item`, and renders the highlight as its first child.

When to use:
- Vertical lists and navigation (`axis: "y"`): settings nav, record lists, inbox and queue rows, copilot history.
- Horizontal strips (`axis: "x"`): view tabs, filter pills, a row of toolbar toggles.
- Small grids of tiles (`axis: "xy"`): an integrations picker, a quick-actions grid, template cards.
- Lists that already mark a current item, with `isItemQuiet` so the hover yields to the stronger fill.
- Anywhere the gaps between items should still be clickable: a click in the gap goes to the nearest item.

When not to use:
- Reorderable lists. Item rects change mid-drag, so the highlight chases rows that are moving. Use the sortable list and its own drag affordance. Use /design/components/sortable-list instead.
- Menus that are mostly destructive or irreversible actions. A glide makes sweeping across rows feel light; keep the plain menu highlight and confirm the action. Use /design/components/confirm-dialog instead.
- Dense data grids and tables. Rows fill Row Mist on hover one at a time, and a highlight gliding across 36px rows reads as noise. Use /design/components/data-grid instead.
- A single control. Buttons and icon actions have their own hover fill. Use /design/components/button instead.
- Dropdown, context and command menus. They already highlight the active item with Base UI's keyboard-aware state. Use /design/components/dropdown-menu instead.

Rules:
- The Quiet Indigo Rule: The highlight is a neutral fill (`bg-accent` by default, Well Gray tints in practice). Indigo is spent on selection and focus, so a hover is never indigo.
- Motion grammar: The glide uses `spring.fast` (80ms, no bounce) and the fade-out uses `exit.fast` (60ms), so leaving is quicker than arriving. Under reduced motion the highlight jumps and only fades.

Anatomy:
- Container: `relative isolate`, takes `ref` and `{...handlers}`. The hook marks it `data-fluid-container` so nested lists keep their own items.
- Highlight: `FluidHoverHighlight`, rendered as the container's first child: absolute, `-z-10` behind the items, `rounded-lg bg-accent`, `aria-hidden`.
- Item: Any element marked `data-fluid-item`, usually a button or a link. Disabled items are skipped.
- Lit item: The item under the pointer gets `data-fluid-active` while lit, so its text can darken with `data-fluid-active:text-foreground`.

States:
- Rest: Nothing is lit. The highlight stays mounted at the last position with opacity 0.
- Entering: Each pointer entry starts a new session: the highlight appears at the nearest item without travelling from where the last visit ended, fading in on `spring.fast`.
- Gliding: Moving between items animates position and size on `spring.fast`, or on the `transition` you pass.
- Focus visible: Keyboard focus lights the focused item. Pointer focus doesn't, so a click doesn't leave a stray highlight.
- Yielding: When `isItemQuiet` returns true for the item (for example the current page), the highlight fades out instead of painting over its fill.
- Disabled item: Skipped when finding the nearest item. By default an item is disabled with `disabled`, `data-disabled` or `aria-disabled="true"`.
- Leaving: Pointer leave fades the highlight out on `exit.fast` (60ms) in place.
- Hidden: `hidden` fades it out while something else owns the list, such as an open row menu.
- Reduced motion: No travel: the highlight jumps between items and fades.

Behavior:
- Items are found by `itemSelector` (`[data-fluid-item]`), so rows need no index bookkeeping. Only items whose closest `[data-fluid-container]` is this container count, so nested lists don't steal each other's rows.
- Rects are measured on pointer entry, on resize (ResizeObserver) and on DOM changes inside the container (MutationObserver), and include the container's scroll offset, so a scrolling container works.
- The nearest item is found by axis: `y` uses vertical distance only, so the pointer in the side gutter still lights the row; `x` uses horizontal distance; `xy` uses straight-line distance.
- `gapClick` (on by default) sends a click in the gap between items to the nearest item. Pass `{ maxDistance }` to stop clicks far from any item from counting.
- Touch pointers are ignored. A tap activates the item and never leaves a highlight behind.
- `isItemQuiet` is re-checked when any `data-active` attribute in the container changes, so mark the current item with `data-active` and test for it.
- `setActiveIndex(index)` lights an item from code (for example the row under a keyboard cursor) and `remeasure()` refreshes rects after a layout change the observers can't see.

Do and don't:
- Do: Keep the highlight neutral. It says where the pointer is, nothing more.
- Don't: Tint the highlight indigo. It reads as a selection and competes with the real one.
- Do: Mark the current item `data-active` and pass `isItemQuiet` so the hover yields to it.
- Don't: Let the hover paint over the current item, so two fills fight on the same row.
- Do: Use it for calm, scannable lists: navigation, records, views and tiles.
- Don't: Put it on a menu of Delete, Void and Remove actions, where sweeping across rows should feel deliberate.

Content:
- The highlight carries no meaning on its own. Selection needs its own fill and `aria-current` or `aria-selected`.
- Keep each item to one line of primary text with optional meta below, so items are similar heights and the glide stays smooth.
- Don't add a second hover fill to the items (`hover:bg-muted`). Change text color on hover or `data-fluid-active` instead.

Accessibility:
- The highlight is `aria-hidden` and `pointer-events-none`; it never takes focus or clicks.
- Items must be real buttons or links so they are focusable and activate with Enter or Space.
- Keep each item's own `focus-visible` ring. The highlight follows keyboard focus but isn't a focus indicator by itself.
- Express the current item with `aria-current` (navigation) or `aria-selected` (tabs and listboxes), not with the highlight.
- Reduced motion is handled: the highlight jumps instead of travelling.
- Tab: Moves focus to the next item. The highlight follows focus-visible.
- Enter: Activates the focused item.
- Space: Activates the focused item when it's a button.

Known gaps (follow the system, not the gap):
- Product call sites restyle the highlight at least six ways (`rounded-md bg-accent`, `rounded-lg bg-muted`, `rounded-lg bg-muted/70`, `bg-muted/70`, `rounded-md`, and the settings nav's `rounded-md bg-accent/60`), so the default `rounded-lg bg-accent` isn't the de facto look. Match the corners of the items and pick one fill per surface.
- `isItemQuiet` is only re-checked when a `data-active` attribute changes. Quiet logic that reads another attribute, such as `aria-selected`, updates on the next pointer move instead.
- `setActiveIndex` is a new function on every render, so it can't sit in an effect's dependency list without re-running the effect each render.

API `useFluidHover`:
- `axis?: "x" | "y" | "xy"` = "y". How distance to an item is measured: `y` for lists and menus, `x` for strips and tabs, `xy` for grids.
- `itemSelector?: string` = "[data-fluid-item]". How items are found inside the container.
- `isItemDisabled?: (el: HTMLElement) => boolean` = disabled, data-disabled or aria-disabled. Items that return true are never lit.
- `isItemQuiet?: (el: HTMLElement) => boolean`. Items that already carry a stronger highlight. The hover yields on them; gap clicks still reach them.
- `gapClick?: boolean | { maxDistance?: number }` = true. A click in the gap between items goes to the nearest item, optionally only within `maxDistance` px.

API `Returns`:
- `ref?: (node: T | null) => (() => void) | undefined`. Callback ref for the container. Sets up the observers and cleans them up.
- `handlers?: { onPointerEnter, onPointerMove, onPointerLeave, onFocus, onBlur, onClick }`. Spread on the container.
- `activeIndex?: number | null`. Index of the lit item, or null.
- `activeRect?: ItemRect | null`. `{ top, left, width, height }` of the lit item, relative to the container.
- `session?: number`. Increments on each pointer entry, so the highlight knows to appear in place rather than travel.
- `remeasure?: () => void`. Re-reads item rects.
- `setActiveIndex?: (index: number | null) => void`. Measures, then lights the item at `index` (or clears).

API `FluidHoverHighlight` (extends Nothing; only these props):
- `hover: Pick<FluidHover, "activeRect" | "session">`. The hook's return value.
- `hidden?: boolean` = false. Fades the highlight out while something else owns the list.
- `className?: string`. Merged after `rounded-lg bg-accent`, to change the fill or corners.
- `transition?: Transition` = spring.fast. Motion transition for the glide. Opacity always uses the fast tier.

### Springs

- Level: Utility
- Category: Utilities
- Status: Stable
- Import: `@oration/canon/lib/springs`
- Exports: `spring`, `exit`, `exitFallbackMs`
- Docs: /design/components/springs

`spring` holds the three motion tiers every Motion-driven component uses: fast (80ms), moderate (160ms) and slow (240ms with a 0.12 bounce). `exit` holds the matching leave tweens, one notch quicker, on the house ease-out, and `exitFallbackMs` turns a tier into a safety timer for deferred unmounts. Pass them straight to Motion's `transition`. The usual mistake is writing a one-off duration or curve inline, or reusing the enter spring for the exit.

When to use:
- Any Motion `transition` for an enter, move or resize: popups, panels, highlights, the save bar, layout and `layoutId` moves.
- `spring.fast` for small, frequent movement: hover highlights, fades, chips, checkmarks.
- `spring.moderate` for short travel that must land exactly: dropdowns, tab indicators, drawers, merged selection fills. It is the most used tier.
- `spring.slow` for larger surfaces with more travel: the save bar, the floating action bar, sheets entering from an edge.
- `exit.*` in an `exit` prop, and `exitFallbackMs(tier)` for a timer that force-unmounts when an exit animation stalls.

When not to use:
- CSS hover and color changes. Those are `transition-colors duration-150` on the house ease-out, not Motion. Use /design/foundations/motion instead.
- Continuous loops such as spinners, shimmer and marching edges. They are linear CSS keyframes. Use /design/components/spinner instead.
- Meter and progress fills, which are allowed to run longer than 320ms. Use /design/components/meter instead.
- Counting a number up or down. Use /design/components/animated-number instead.
- Revealing generated text over time. Use /design/components/use-simulated-stream instead.

Rules:
- Motion grammar: Every transition uses cubic-bezier(0.23, 1, 0.32, 1). Only transform, opacity, filter, clip-path and disclosure height animate. Exits are faster than enters, lists that exist on load don't animate in, and no state change runs past 320ms except meter fills.
- Reduced motion: Under reduced motion, scale, translate and blur are zeroed, sheets only fade and disclosures snap. The tiers don't do this for you: check `useReducedMotion()` and drop the transform.

Anatomy:
- type: `"spring"` for `spring.*`, `"tween"` for `exit.*`.
- duration: Seconds. For springs it's the perceived duration Motion solves for: 0.08, 0.16 and 0.24.
- bounce: 0 for fast and moderate (critically damped, lands exactly), 0.12 for slow (a small overshoot).
- exit: `spring.*.exit.duration` is the leave time: 0.06, 0.12 and 0.16. `exit.*` wraps it as a tween with the house ease.

Behavior:
- The springs are defined by duration and bounce, not stiffness and damping, so the tier names map to how long a move feels.
- Pass enter tiers to `transition` and exit tiers inside the exit target: `exit={{ opacity: 0, transition: exit.moderate }}`.
- Each `spring.*` object carries a nested `exit` key. Passed whole as `transition`, Motion treats it as an override for a value named `exit` and ignores it, so the leave time is never applied for you. Use `exit.*`.
- `exitFallbackMs(tier)` is the tier's exit duration in ms plus 100: 160 for fast, 220 for moderate and 260 for slow. Use it for the timer that unmounts a portal if `onAnimationComplete` never fires in a throttled tab.
- `SpringSpeed` is the union of tier names (`"fast" | "moderate" | "slow"`) for components that take a speed prop.

Do and don't:
- Do: Pass a tier: `transition={spring.moderate}` in, `exit.moderate` out.
- Don't: Write one-off timings such as `{ duration: 0.6, ease: "easeInOut" }`. They drift from every other component and leave slowly.
- Do: Leave on the matching `exit.*` tween, one notch quicker than the enter.
- Don't: Reuse the enter spring for the exit, so a bouncing panel lingers after the person has moved on.
- Do: Zero translate and scale under `useReducedMotion()` and keep the opacity change.
- Don't: Let a slide or scale play for everyone because the tier is short.

Content:
- In specs and reviews, name the tier (moderate spring, fast exit) rather than a millisecond value, so the intent survives a retune.
- When a component takes a speed prop, type it as `SpringSpeed` and default to `"moderate"`.

Accessibility:
- The tiers don't read the reduced-motion preference. Each component checks `useReducedMotion()` and swaps movement for a fade.
- All tiers settle within 240ms, inside the 320ms ceiling, so motion never delays input.
- Motion never carries meaning on its own: a panel that slides in also has a title, and a selection that glides also changes `aria-selected` or `aria-current`.
- Popups that stay mounted during their exit should not trap focus or block clicks once they start leaving.

Known gaps (follow the system, not the gap):
- `exitFallbackMs` is exported, but nothing in packages/canon or apps/web calls it yet.
- Six files, including Segmented control and the record view tabs, hard-code `{ type: "spring", duration: 0.3, bounce: 0 }` instead of a tier, and DESIGN.md describes view tabs on that 0.3s spring. 0.3s isn't on the ladder.
- DESIGN.md quotes CSS timings (150ms hovers, 200 to 250ms disclosure, dialogs in over 200ms and out in 140ms) that don't map one to one onto the 80, 160 and 240ms tiers. For Motion-driven components the tiers are the source.

API `spring`:
- `fast?: { type: "spring"; duration: 0.08; bounce: 0; exit: { duration: 0.06 } }`. Small, frequent movement: highlights, fades, chips.
- `moderate?: { type: "spring"; duration: 0.16; bounce: 0; exit: { duration: 0.12 } }`. Short travel that lands exactly: dropdowns, tabs, drawers, selection fills.
- `slow?: { type: "spring"; duration: 0.24; bounce: 0.12; exit: { duration: 0.16 } }`. Larger surfaces with more travel: the save bar, the action bar.

API `exit`:
- `fast?: { type: "tween"; duration: 0.06; ease: [0.23, 1, 0.32, 1] }`. Pairs with `spring.fast`.
- `moderate?: { type: "tween"; duration: 0.12; ease: [0.23, 1, 0.32, 1] }`. Pairs with `spring.moderate`.
- `slow?: { type: "tween"; duration: 0.16; ease: [0.23, 1, 0.32, 1] }`. Pairs with `spring.slow`.

API `exitFallbackMs`:
- `tier: { exit: { duration: number } }`. A `spring.*` tier.
- `Returns?: number`. The exit duration in ms plus a 100ms buffer: 160, 220 or 260.

API `SpringSpeed`:
- `SpringSpeed?: "fast" | "moderate" | "slow"`. `keyof typeof spring`.

### Mock query

- Level: Utility
- Category: Utilities
- Status: Stable
- Import: `@oration/canon/hooks/use-mock-query`
- Exports: `useMockQuery`
- Docs: /design/components/use-mock-query

`useMockQuery` stands in for a network read over static mock data, so every data component owns real loading, error and retry states before there is a backend. It returns `{ status, data, error, retry }`, which is exactly what `DataState` renders. Keys behave like a warm cache: once a key resolves it stays resolved for the session until `replayLoading()`. The usual mistakes are sharing one key between two data sets and hand-rolling the three states instead of passing the query to `DataState`.

When to use:
- Any list, table, card or panel that reads mock data: pass the result to `DataState` with a skeleton that matches the layout.
- To design an error state in place with `fail: true`, and its recovery with `retry`.
- To hold a query in loading until a prerequisite exists, such as a selected supplier, with `enabled`.
- To give a heavy view a longer wait than the 250 to 850ms default with `delay`.

When not to use:
- Saving or other writes. Show progress on the control that started it. Use /design/components/pending-button instead.
- Tracking edits against a saved baseline. Use /design/components/use-dirty-form instead.
- Revealing model output over time. Use /design/components/use-simulated-stream instead.
- Changing latency or failures for the whole prototype. That's the demo settings, not a per-component option. Use /design/components/demo-data instead.
- Local UI state such as open, selected or expanded. That's `useState`, and it should never show a skeleton.

Rules:
- Every data component owns its states: Never gate a whole page on loading. Each component that shows data draws loading, empty and error at component level, with a skeleton that matches its final layout. Errors say what failed and offer Retry; they never blame the user.

States:
- Loading: From mount until the wait elapses, and indefinitely while `enabled` is false. `data` is undefined.
- Success: `data` is `load()`, re-read on every render. Warm keys and instant latency start here with no loading frame.
- Error: `error` is `Error("The request timed out.")`. Happens on every attempt with `fail`, or on the first attempt when the Simulate errors demo setting is on.
- Retrying: `retry()` starts a new attempt: back to loading, then settles again.
- Empty: Not a status of the hook. `DataState` shows it when `isEmpty(data)` is true.

Behavior:
- The default wait is 250 to 850ms, derived from a hash of the key, so a given view always loads in the same time. It's multiplied by the demo latency: 0 for Instant, 1 for Realistic, 3 for Slow.
- With Instant latency and nothing failing, the status is success on the first render, so there is no skeleton flash.
- A key that resolved stays resolved for the session: remounting or navigating back renders data immediately. `replayLoading()` forgets every key at once.
- With the Simulate errors setting on, only the first attempt fails, so the error and its recovery can both be reviewed. `fail: true` fails every attempt, including retries.
- Warm keys ignore the Simulate errors setting until loading is replayed, because a cached key never makes a new attempt.
- `data` calls `load()` on every render once settled. Keep `load` cheap; reading a store inside it keeps live data current.
- Timers are cleared on unmount, and changing the key, `fail` or `enabled` starts over.

Do and don't:
- Do: Give each data set its own namespaced key: `"ap.suppliers"`, `"ap.remittances"`, `"ap.w9.northwind"`.
- Don't: Reuse a generic key such as `"list"`. The second component inherits the first one's warm cache and never shows its own loading state.
- Do: Pass the query to `DataState` with a skeleton shaped like the content.
- Don't: Branch on `status` by hand and show a centered spinner, with no error or empty state.
- Do: Use `fail: true` while building, to design the error state where it will appear.
- Don't: Ship a data view that has only ever been seen in its success state.

Content:
- Error titles name what failed: Couldn't load suppliers, not Error or Something went wrong.
- The description comes from the error and how to recover: The request timed out. Try again in a moment. `DataState` builds it for you.
- Empty titles say what isn't there in this view (No exceptions in this run) and the description says why or what to do next.
- Keys are dotted, lowercase and scoped by area: `cc.callbacks`, `ap.payment-runs`.

Accessibility:
- The hook draws nothing. `DataState` sets `aria-busy` while loading, adds a visually hidden Loading label, and announces errors through a polite status region.
- Retry is a real button, so the recovery path works from the keyboard.
- Slow latency stretches every busy period; check that skeletons don't trap focus or shift the layout when they resolve.

Known gaps (follow the system, not the gap):
- Every failure is the same timeout error, so error copy for other cases (no permission, not found, rate limited) can't be exercised through the hook.
- Turning on Simulate errors has no visible effect on warm data until someone also runs Replay loading states, which reads as a broken switch.

API `useMockQuery`:
- `key: string`. Identifies the data set. Drives the warm cache and the default delay.
- `load: () => T`. Returns the mock data. Called on every render once settled.
- `options.delay?: number` = 250 to 850, stable per key. Base wait in ms, before the demo latency multiplier.
- `options.fail?: boolean` = false. Fail every attempt, to show the error state in place.
- `options.enabled?: boolean` = true. While false the query stays in loading and never settles.

API `Returns`:
- `status?: "loading" | "error" | "success"`. Where the simulated request is.
- `data?: T | undefined`. `load()` while successful, otherwise undefined.
- `error?: Error | null`. The timeout error while failed, otherwise null.
- `retry?: () => void`. Starts a new attempt. Stable across renders.

### Demo controls

- Level: Utility
- Category: Utilities
- Status: Beta
- Import: `@oration/canon/lib/demo-data`
- Exports: `useDemoSettings`, `setDemoSettings`, `replayLoading`
- Docs: /design/components/demo-data

Demo controls are the prototype's switches for the mock data layer: a latency setting that scales every `useMockQuery` wait, a failure switch that fails each first attempt, and `replayLoading()`, which forgets the warm cache so loading shows again. People reach them from the user menu under Demo controls; code reads them with `useDemoSettings()`. Settings persist per browser in localStorage. They exist for reviewing states, so product logic should never branch on them.

When to use:
- Reviewing a page's loading states: set latency to Slow, then Replay loading states.
- Reviewing error and recovery: turn on Simulate errors and replay; every first attempt fails and Retry succeeds.
- Recording a walkthrough or demo where nothing should flash: set latency to Instant.
- Building a control for these settings somewhere else, such as a docs panel, with `setDemoSettings` and `replayLoading`.

When not to use:
- Showing one component's error state while building it. Pass `fail: true` to that query instead of failing the whole prototype. Use /design/components/use-mock-query instead.
- Slowing down one heavy view. Use the query's `delay`. Use /design/components/use-mock-query instead.
- Product behavior. Don't hide a skeleton, skip a confirmation or change copy because latency is Instant.
- Simulating permissions or roles. The same submenu has View as role for that, backed by the access store. Use /design/patterns/permissions instead.

Anatomy:
- Demo controls submenu: In the user menu, with a flask icon. It also holds View as role, Auth scenarios and End my session, which are separate tools.
- Latency: A radio group: Instant (0x), Realistic (1x, the default) and Slow (3x).
- Simulate errors: A checkbox item. Fails the first attempt of every query.
- Replay loading states: Calls `replayLoading()` and confirms with a Loading states replayed toast.

States:
- Realistic: The default. Each query waits its own delay, 250 to 850ms unless set.
- Instant: Waits are zero. Queries that aren't failing render data on the first frame.
- Slow: Every wait is tripled.
- Simulate errors: The first attempt of each query fails with a timeout; Retry succeeds.
- Replayed: Every mounted query goes back to loading and resolves again; queries mounted later load fresh.

Behavior:
- Settings live in a module-level store read through `useSyncExternalStore`, so every component in the tab sees a change at once.
- On the server and during hydration the snapshot is the default (Realistic, no failures). The stored value is read from localStorage (`oration:demo-settings`) on first client read.
- `setDemoSettings(patch)` merges a partial, writes localStorage and notifies subscribers. In private mode the write fails quietly and the setting lasts for the session.
- `replayLoading()` bumps a cache epoch. Every key resolved before it counts as cold again.
- Turning on Simulate errors doesn't touch keys that are already warm; replay loading afterwards to see the errors.
- Other tabs don't pick up a change until they reload; there is no `storage` event listener.

Do and don't:
- Do: Review every new data view at Slow and with Simulate errors before calling it done.
- Don't: Only ever look at a view on a warm cache, where loading and error never appear.
- Do: Read the settings only inside the mock data layer.
- Don't: Branch product code on `useDemoSettings()`, for example hiding a skeleton when latency is Instant.
- Do: Replay loading after changing the failure switch, so warm views make a new attempt.
- Don't: Flip Simulate errors and conclude the error state is broken because nothing changed.

Content:
- The submenu is labeled Demo controls so nobody mistakes it for a product setting. Keep that word in any new control built on these settings.
- Labels are sentence case and literal: Latency, Instant, Realistic, Slow, Simulate errors, Replay loading states.
- Confirm a replay with a toast in the past tense: Loading states replayed.

Accessibility:
- In the user menu the latency choices are menu radio items and Simulate errors is a menu checkbox item, so their checked state is announced.
- Slow latency stretches every `aria-busy` period. It's the setting to check that skeletons and focus behave while data is pending.
- Replaying loading doesn't move focus. Content under the pointer or focus is swapped for a skeleton and back.
- Enter: Opens the user menu from its trigger, or chooses the focused item.
- ArrowRight: Opens the Demo controls submenu from its row.
- ArrowLeft: Closes the submenu and returns to the user menu.
- Esc: Closes the menu.

Known gaps (follow the system, not the gap):
- Nothing on screen says when latency is Slow or errors are simulated, so a reviewer who forgot the setting can file a slow or failing page as a bug.
- Settings don't sync across tabs: a second tab keeps the old values until it reloads.

API `useDemoSettings`:

API `Returns`:
- `latency?: "instant" | "realistic" | "slow"` = "realistic". Scales every simulated wait by 0, 1 or 3.
- `failures?: boolean` = false. When true, the first attempt of each query fails.

API `setDemoSettings`:
- `patch: Partial<DemoSettings>`. Merged into the current settings, saved to localStorage and broadcast.

API `replayLoading`:

API `Also exported`:
- `getDemoSettings?: () => DemoSettings`. The current settings outside React.
- `useCacheEpoch?: () => number`. Re-renders when `replayLoading()` runs.
- `getCacheEpoch?: () => number`. The current epoch outside React.
- `LATENCY_MULTIPLIER?: Record<DemoLatency, number>`. `{ instant: 0, realistic: 1, slow: 3 }`.
- `DemoLatency, DemoSettings?: type`. `"instant" | "realistic" | "slow"` and `{ latency: DemoLatency; failures: boolean }`.

### Dirty form

- Level: Utility
- Category: Utilities
- Status: Stable
- Import: `@oration/canon/hooks/use-dirty-form`
- Exports: `useDirtyForm`, `changedKeys`
- Docs: /design/components/use-dirty-form

`useDirtyForm` keeps a form's values next to the last saved baseline and reports which fields differ, which is the count the save bar shows. It owns `values`, `set`, `reset`, `save` and `saving`, compares field by field, and only moves the baseline when `onSave` resolves. Settings pages, agent config and record detail forms are built on it. The usual mistakes are counting edits instead of differences, so a field typed back to its saved value still reads as changed, and loading data with `setValues`, which marks every field dirty.

When to use:
- Settings pages and config panels that save explicitly through the save bar.
- Record detail forms where several fields change before one save.
- Anywhere a 3 unsaved changes count, Discard and ⌘S should just work.
- `changedKeys(saved, values)` on its own, to diff two snapshots for an audit line or a confirmation summary.

When not to use:
- Settings that apply the moment they change. Toggle them and confirm with a toast. Use /design/components/switch instead.
- A short form in a dialog with one submit button. Use /design/components/form-dialog instead.
- Editing a single value in place, such as a record name. Use /design/components/editable-text instead.
- Validation. The hook doesn't validate; show errors on the field. Use /design/components/field instead.

States:
- Clean: `values` equal `saved`. `isDirty` is false and the save bar is hidden.
- Dirty: One or more fields differ. `dirtyKeys` lists them and `dirtyCount` feeds the save bar's count.
- Saving: `saving` is true while `onSave` runs. The save bar shows a spinner and disables Discard.
- Saved: `onSave` resolved: the baseline becomes the values that were saved and the form is clean.
- Save failed: `onSave` threw or rejected: `save()` returns false, the baseline stays and the form stays dirty.
- Discarded: `reset()` puts `values` back to `saved`.

Behavior:
- `initial` is read once, on mount. To load or reload data later, call `replace(next)`, which sets both the values and the baseline so nothing reads as changed.
- `set(key, value)` updates one field and accepts an updater: `set("approvers", (list) => [...list, "Jordan Lee"])`. `setValues` replaces the whole object.
- Dirty means different, not touched. Primitives compare with `Object.is`; objects and arrays compare by `JSON.stringify`.
- `save()` snapshots the values when it starts. Edits made while saving stay dirty against the new baseline.
- `onSave` is read from a ref, so it can close over fresh state without re-creating the hook.
- It has no opinion about leaving the page or shortcuts; `SaveBar` adds ⌘S (Ctrl+S) and the before-unload warning.

Do and don't:
- Do: Pass `dirtyCount` to the save bar's `changes`, so editing a field back to its saved value takes it out of the count.
- Don't: Track a touched flag and show Unsaved changes after the person has undone their edit.
- Do: Throw or reject from `onSave` when the save fails, and toast what went wrong. The form stays dirty and the bar stays up.
- Don't: Catch the error inside `onSave`. The baseline moves, the bar leaves, and nothing was saved.
- Do: Call `replace(data)` after loading or syncing values.
- Don't: Call `setValues(data)` after loading, which marks every loaded field as an unsaved change.

Content:
- The save bar counts changes: 1 unsaved change, 3 unsaved changes. Use `message` only when the count would mislead.
- Keep Save changes and Discard as the labels; name the object only when a page has two save bars.
- Confirm a save with a short success toast, Changes saved. On failure say what failed and keep the edits: Couldn't save changes with the reason.

Accessibility:
- The hook renders nothing. `SaveBar` is a region named Unsaved changes whose count is a polite live region, so the change is announced without moving focus.
- Don't move focus to the save bar when the form becomes dirty; people are still typing.
- Keep Save enabled while dirty and report problems after the attempt, rather than disabling it silently.
- ⌘ + S: Saves while the save bar is showing (Ctrl+S on Windows and Linux).

Known gaps (follow the system, not the gap):
- Objects compare by `JSON.stringify`, so the same fields in a different key order read as changed, and Dates, Maps and Sets don't compare reliably. Keep form values to plain JSON.
- A new `initial` after mount is ignored without warning; forgetting `replace()` leaves the form showing stale values.

API `useDirtyForm`:
- `initial: T`. Starting values and baseline. Read once on mount.
- `options.onSave?: (values: T) => void | Promise<void>`. Runs on save with the snapshot. Throw or reject to keep the form dirty.

API `Returns`:
- `values?: T`. Current values.
- `saved?: T`. The last saved baseline.
- `set?: <K extends keyof T>(key: K, value: T[K] | ((current: T[K]) => T[K])) => void`. Update one field.
- `setValues?: Dispatch<SetStateAction<T>>`. Replace all values. The baseline doesn't move.
- `reset?: () => void`. Discard: values back to the baseline.
- `replace?: (next: T) => void`. Set values and baseline together, after loading data.
- `save?: () => Promise<boolean>`. Runs `onSave`; resolves true and moves the baseline on success, false on failure.
- `saving?: boolean`. True while `onSave` runs.
- `dirtyKeys?: Array<keyof T>`. Fields that differ from the baseline.
- `dirtyCount?: number`. `dirtyKeys.length`, for the save bar.
- `isDirty?: boolean`. True when any field differs.

API `changedKeys`:
- `saved: T`. The baseline snapshot.
- `values: T`. The snapshot to compare. Keys present in either are checked.

### Simulated stream

- Level: Utility
- Category: Utilities
- Status: Beta
- Import: `@oration/canon/hooks/use-simulated-stream`
- Exports: `useSimulatedStream`
- Docs: /design/components/use-simulated-stream

`useSimulatedStream` reveals a string over time on one animation-frame loop, whole words at a time, so mock answers read like a model streaming tokens. It returns the visible `output` plus `done`, `progress`, `restart` and `skip`, and it powers `StreamingText`, copilot answers and call wrap-up summaries. Under reduced motion the full text shows at once. The usual mistake is streaming text people need immediately, such as an error, a label or a value they're about to act on.

When to use:
- Mock model output in copilot and agent answers, when `StreamingText` doesn't fit the layout.
- Generated summaries and drafts: call wrap-ups, a reply draft, an invoice exception explanation.
- Driving a custom renderer (markdown, citations, a caret) from `output`.
- Text that arrives in chunks: when `text` grows by appending, the reveal continues instead of starting over.

When not to use:
- A standard streamed answer with caret, citations and follow-ups. The component already wraps this hook. Use /design/components/streaming-text instead.
- Content that is loading. Show a skeleton, then the content. Use /design/components/skeleton instead.
- Errors, toasts, labels and status text. They appear whole. Use /design/components/toast instead.
- Numbers that change. Use /design/components/animated-number instead.
- A typing effect on headings or marketing copy. Streaming signals generated output and nothing else.

Rules:
- Reduced motion: Under reduced motion, movement stops: the hook shows the full text on the first frame and reports `done`, so `onDone` still fires.

States:
- Waiting: `start` is false: `output` is empty and `progress` is 0.
- Streaming: `output` grows word by word at `speed` characters per second; `progress` runs from 0 to 1.
- Done: All text is visible, `done` is true and `onDone` has fired once for this run.
- Skipped: `skip()` shows the rest at once. It clears when the text changes or on `restart()`.
- Continuing: `text` grew by appending: the reveal carries on from where it was.
- Reduced motion: Full text immediately, `done` true.

Behavior:
- One `requestAnimationFrame` loop per hook. Each frame works out how many characters `speed` allows, then extends to the next space or newline, so a word is never cut in half.
- When `text` changes and still starts with what's already shown, the reveal continues from there. Any other change starts over from the first character.
- Setting `start` to false resets the output to empty; setting it back to true streams from the beginning.
- `restart()` replays from the first character and clears a skip. `skip()` reveals everything at once.
- `onDone` fires once per run and text, read from a ref, so an inline callback doesn't restart the stream.
- `progress` is 1 for empty text, so a progress bar never sits at zero on nothing.

Do and don't:
- Do: Stream long generated prose: answers, summaries, drafts.
- Don't: Stream short UI strings, such as an error message or a button label, which people need whole.
- Do: Offer Show full answer (`skip`) on long answers and keep the rest of the screen usable while it streams.
- Don't: Block input until the stream finishes.
- Do: Mark the answer `aria-busy` while streaming, so assistive tech reads it once it's done.
- Don't: Put `aria-live` on the streaming text, which announces every word as it lands.

Content:
- Streamed text is the answer itself. Don't prefix it with Thinking… or Typing…; the caret is the only streaming indicator.
- Lead with the answer and its figures: Northwind Freight has 14 open invoices totaling $42,180.00.
- Label the controls Show full answer and Regenerate, not Skip or Retry.

Accessibility:
- Set `aria-busy` on the answer while `done` is false, and drop it when the stream ends.
- Never put a live region on the element that streams. Announce completion once if the answer appears away from focus.
- The caret (`StreamCaret`) is `aria-hidden`.
- Reduced motion is handled in the hook; the text appears whole.

Known gaps (follow the system, not the gap):
- The registry describes it as streaming character by character; the code reveals whole words.
- Accessibility is left to the caller: the hook doesn't set `aria-busy` or announce completion, so each call site has to remember to.

API `useSimulatedStream`:
- `text: string`. The full text. Appending to it continues the reveal; replacing it starts over.
- `speed?: number` = 40. Characters per second. Words are revealed whole. Copilot answers use 150.
- `start?: boolean` = true. While false, output is empty and the stream waits.
- `onDone?: () => void`. Called once when the whole text is visible.

API `Returns`:
- `output?: string`. The visible part of `text`.
- `done?: boolean`. True when everything is visible and `start` is true.
- `progress?: number`. 0 to 1.
- `restart?: () => void`. Stream again from the first character.
- `skip?: () => void`. Show the rest of the text now.

### Overflow fade

- Level: Utility
- Category: Utilities
- Status: Beta
- Import: `@oration/canon/hooks/use-overflow-fade`
- Exports: `useOverflowFade`
- Docs: /design/components/use-overflow-fade

`useOverflowFade` is the hook behind The Scroll Edge Rule for horizontal rows. It returns a callback ref that marks a scroller with `data-overflow-start` and `data-overflow-end` while content is clipped on that side, and the `[data-overflow-fade]` styles in globals.css fade that edge over 2rem. It also scrolls the selected item fully into view. Scrollable tabs, code snippet tabs and record view tabs use it. The usual mistake is attaching the ref without the `data-overflow-fade` attribute, which tracks the overflow but draws no fade.

When to use:
- Horizontal tab and view rows that can outgrow their container: record tabs, view tabs, settings sub-tabs.
- Scrolling strips of chips or filters in a toolbar.
- Language tabs above a code sample.
- Any row where the selected item must stay in view as the selection changes.

When not to use:
- Tabs from the Tabs component. `TabsList scrollable` already applies the hook and the attribute. Use /design/components/tabs instead.
- Vertical scrolling regions. The fade styles are horizontal only. Use /design/components/scroll-area instead.
- A data grid's pinned columns, which show their edge with a shadow once the grid scrolls sideways. Use /design/components/data-grid instead.
- Slides of content that page one at a time. Use /design/components/carousel instead.
- A row of three or four items with room to wrap. Let it wrap instead of scrolling.

Rules:
- The Scroll Edge Rule: Clipped content shows its edge. Horizontal tab and view rows fade the clipped side over 2rem, and the last pinned grid column casts its edge shadow only once the grid scrolls sideways.

Anatomy:
- Scroller: The element that takes the ref: `overflow-x-auto no-scrollbar` plus the `data-overflow-fade` attribute.
- Start fade: Drawn while `data-overflow-start` is set, once the row has scrolled more than 1px.
- End fade: Drawn while `data-overflow-end` is set, until the row reaches its last pixel. Both set means a fade on each side.
- Selected item: Matched by `[aria-selected="true"]` by default. Scrolled to sit 24px inside the edge.

States:
- Fits: Nothing is clipped: no attributes, no fade.
- Clipped at the end: At the start of a long row: the right edge fades.
- Clipped at the start: Scrolled to the end: the left edge fades.
- Clipped on both sides: Scrolled partway: both edges fade.
- Selection changed: The newly selected item scrolls into view smoothly, or instantly under reduced motion.

Behavior:
- On attach, the selected item is scrolled into view instantly, then the edges are measured.
- Edges update on scroll (a passive listener) and on resize (ResizeObserver), with a 1px tolerance so subpixel widths don't leave a stray fade.
- A MutationObserver watches the subtree for added or removed items and for `aria-selected` changes, then reveals the selection again.
- The reveal leaves 24px between the selected item and the edge it was hidden behind.
- The fade is a CSS `mask-image`, so it works on any background and doesn't add elements or block clicks.
- The ref returns a cleanup function (React 19 callback ref cleanup), so observers and listeners go away with the element.

Do and don't:
- Do: Put `data-overflow-fade` on the same element as the ref.
- Don't: Attach the ref alone. The attributes are tracked, but the row ends in a hard cut through a label.
- Do: Let the hook fade only the side that is clipped.
- Don't: Mask both edges permanently, so short rows fade labels that aren't clipped at all.
- Do: Hide the native scrollbar with `no-scrollbar` and let the fade say there is more.
- Don't: Leave a scrollbar under a row of tabs, where it reads as a second, unrelated control.

Content:
- Keep tab and view labels to one or two words, so more of the row fits before it has to scroll.
- Counts trail the label in 12px Slate Meta tabular figures: Awaiting approval 37.
- Don't truncate labels with an ellipsis inside a scrolling row; let the row scroll.

Accessibility:
- The fade is visual only. Clipped items stay in the accessibility tree and in the tab order.
- Focusing a clipped item scrolls it into view natively; selecting it with the keyboard runs the hook's reveal too.
- Use real tab semantics (`role="tablist"`, `role="tab"`, `aria-selected`) with arrow-key movement, or the Tabs component, which does it for you.
- Reduced motion is respected: the reveal jumps instead of scrolling smoothly.
- ArrowLeft + ArrowRight: In a tablist, moves the selection; the hook scrolls the new tab into view.
- Tab: Moves focus into and out of the row.

Known gaps (follow the system, not the gap):
- The MutationObserver only watches `aria-selected`. A custom `selectedSelector` such as `[data-active]` is revealed on attach, but not when that attribute moves to another item.
- The reveal inset is 24px but the fade is 32px, so the selected item's outer edge still sits inside the gradient at about 75% opacity.
- The record view tabs use `role="tab"` buttons without arrow-key movement or `tabIndex` roving, so the tablist semantics are incomplete.
- It assumes left to right: start means the left edge, and it reads `scrollLeft` as positive. In a right-to-left row, where `scrollLeft` runs negative, the attributes and fades come out wrong.

API `useOverflowFade`:
- `selectedSelector?: string` = '[aria-selected="true"]'. Finds the item to keep in view. Matched on attach and whenever `aria-selected` or the item list changes.

API `Returns`:
- `ref?: (node: T | null) => (() => void) | undefined`. Pass to the scroller's `ref`. Sets up and cleans up the observers.

API `Data attributes`:
- `data-overflow-fade: attribute`. Set by you. Opts the element into the fade styles.
- `data-overflow-start?: attribute`. Set by the hook while content is clipped on the left.
- `data-overflow-end?: attribute`. Set by the hook while content is clipped on the right.

### Mobile breakpoint

- Level: Utility
- Category: Utilities
- Status: Beta
- Import: `@oration/canon/hooks/use-mobile`
- Exports: `useIsMobile`
- Docs: /design/components/use-mobile

`useIsMobile` reports whether the viewport is narrower than 768px, the suite's tablet breakpoint, and updates when it crosses. The Sidebar uses it to become a sheet, and the copilot panel, contact center workspace, macros view and web call widget use it to change structure. It returns `false` on the server and on the first client render, so it can only change what renders after hydration. Anything CSS can express belongs in an `md:` class instead.

When to use:
- Swapping structure that CSS can't: a side panel becomes a sheet, a docked rail becomes a drawer.
- Choosing a different overlay or interaction on phones, such as a bottom sheet instead of a popover.
- Deciding a default, such as starting a panel collapsed below 768px.

When not to use:
- Spacing, columns, font sizes or visibility. Use `md:` and `max-md:` classes, which apply before hydration with no flash. Use /design/foundations/responsive instead.
- Other breakpoints (640 or 1024px). The hook is fixed at 768px; use CSS or a `matchMedia` of your own. Use /design/foundations/layout instead.
- Detecting touch. Width says nothing about input; use `(pointer: coarse)` or `(hover: none)`.
- Rendering on the server. It's always `false` there.
- The app sidebar. It already switches to a sheet below 768px. Use /design/components/sidebar instead.

Rules:
- Breakpoints: Breakpoints are 640, 768 and 1024px. `useIsMobile` is the 768px one, and the only one with a hook.

States:
- Server and first render: `false`, whatever the device. The real value arrives in an effect after hydration.
- Desktop: `false` at 768px and wider.
- Mobile: `true` below 768px.
- Crossing: Resizing, rotating or zooming across 768px re-renders with the new value.

Behavior:
- Listens to `matchMedia("(max-width: 767px)")` and reads `window.innerWidth` when it changes, so it measures the viewport, not the component's container.
- Browser zoom changes the CSS viewport width: a desktop user at 200% zoom on a 1280px window gets the mobile structure.
- Every component that calls it adds its own listener; there is no shared store.

Do and don't:
- Do: Use `md:` classes for anything visual: padding, columns, hidden labels.
- Don't: Branch JSX on `useIsMobile()` for styling. Phones render the desktop layout first and then jump.
- Do: Use the hook to swap a structure, such as a side panel for a sheet, and keep the same title and actions in both.
- Don't: Show different content or fewer actions on mobile. People expect the same record at both sizes.

Content:
- When a panel becomes a sheet, keep its title, description and action labels identical, so the content reads the same at both sizes.
- The trigger that opens the mobile sheet names what it opens: Supplier details, not More.

Accessibility:
- A structure swap remounts content. Don't swap while a person is typing or has focus inside the panel, or focus is lost.
- Zoomed desktop users get the mobile layout, so it has to be complete, not a reduced version.
- Touch layouts keep hit areas at 32px or more, per the control sizes for touch surfaces.
- Sheets that replace panels need a title (`SheetTitle`) so the dialog has a name.

Known gaps (follow the system, not the gap):
- It returns `false` until mounted, so on phones every caller renders its desktop structure first and swaps after hydration.
- The 768px breakpoint isn't exported and there is no hook for 640 or 1024px, so the copilot panel defines its own `useWideScreen` alongside it.

API `useIsMobile`:

API `Returns`:
- `isMobile?: boolean`. True when `window.innerWidth` is below 768. False on the server and before the first effect.

### Size context

- Level: Utility
- Category: Utilities
- Status: Experimental
- Import: `@oration/canon/lib/size-context`
- Exports: `SizeProvider`, `useSize`, `sizeMap`, `typeScale`
- Docs: /design/components/size-context

Size context lets a region choose one of two control densities, default or compact, and hands components the matching height, padding, gap, icon and text classes, plus a role-based type scale. `SizeProvider` sets it and `useSize` reads it. Today only Switch reads it, and nothing in apps/web renders a `SizeProvider`, so it is experimental. Its default step is a 36px control with 13px text, which disagrees with DESIGN.md's 32px control height.

When to use:
- Experimentally, to step a region's switches down to compact, such as a dense filter popover.
- Inside a new packages/canon control that should follow a region's density, through `useSize(props.size)`.
- To read type sizes as numbers with `useTypeScale` where classes can't reach, such as chart or canvas labels.

When not to use:
- Making buttons smaller. Button doesn't read the context; pass `size="sm"`. Use /design/components/button instead.
- A dense toolbar. Toolbars use 28px controls directly. Use /design/components/toolbar instead.
- Table and grid density. Rows have their own 32, 36 and 44px densities. Use /design/components/data-grid instead.
- Picking a font size for a block of text. Use the type ramp classes. Use /design/foundations/typography instead.

Rules:
- Control heights: Controls are 32px (28px in toolbars, 36px large). Size context's default is 36px and its compact is 28px, so its default step is the suite's large.
- The Thirteen-Fourteen Rule: Dense UI is 13px, reading text is 14px, meta is 12px. 11px is for footnotes only, and nothing is set smaller. The compact column steps body to 12px and caption to 11px, below this ramp.

States:
- No provider: `useSize()` resolves to the default step.
- Default: `h-9` (36px) controls, `text-[13px]`, `px-3`, `gap-2`, 16px icons.
- Compact: `h-7` (28px) controls, `text-[12px]`, `px-2.5`, `gap-1`, 14px icons.
- Controlled: With `size`, the provider ignores `setSize` so a region stays pinned.
- Overridden: A component's own `size` prop beats the provider: explicit prop, then provider, then default.

Behavior:
- Resolution order everywhere: the component's explicit size, then the nearest `SizeProvider`, then `"default"`.
- `SizeProvider` is uncontrolled with `defaultSize`, or controlled with `size`. A controlled provider ignores `setSize` so a background write can't surface later.
- `useSizeContext()` returns `{ size, setSize, classes }` and throws outside a provider; `useSize` and `useSizeVariant` never throw.
- Switch maps its legacy `size="sm"` to compact, and reads the provider when `size` is omitted. Its label row uses the context's `px`, `gap` and `text`.
- `classes.control` is one height for bounded controls and for list and menu rows, so a popup row lines up with the trigger that opened it.

Do and don't:
- Do: Size dense regions explicitly today: Button `size="sm"`, 28px toolbar controls, Switch `size="compact"`.
- Don't: Wrap a region in `SizeProvider size="compact"` and expect it to shrink. Only Switch responds; buttons and inputs stay 32px.
- Do: Take text sizes from the type ramp: 13px dense, 14px reading, 12px meta.
- Don't: Use the compact caption (11px) for descriptions or errors. 11px is for footnotes only.

Accessibility:
- Compact controls are 28px: fine for pointer surfaces, too small as the only size on touch, where controls stay at 32px or more.
- The compact switch track is 28 by 16px. Keep its label, which widens the hit area to the whole row.
- Compact text steps to 12px body and 11px captions; check contrast and legibility before using it for anything people read closely.

Known gaps (follow the system, not the gap):
- The default control is 36px (`h-9`), but DESIGN.md sets controls at 32px, with 28px for toolbars and 36px for large. Default here is the suite's large.
- Nothing in apps/web renders a `SizeProvider`, and only Switch reads `useSize`, so the context has no effect anywhere in the product today.
- The compact step sets body at 12px and captions at 11px, below The Thirteen-Fourteen Rule.
- `typeScale.display` is 28px, but DESIGN.md's Display role is 24px and reserved for the Home greeting.
- Text classes are arbitrary values (`text-[13px]`, `text-[12px]`) rather than the `text-13` and `text-xs` ramp steps.

API `SizeProvider` (extends Nothing; only these props):
- `children: ReactNode`. The region.
- `size?: "default" | "compact"`. Controlled: pins the region. `setSize` is ignored.
- `defaultSize?: "default" | "compact"` = "default". Uncontrolled starting size.

API `useSize`:
- `override?: "default" | "compact" | null`. A component's own `size` prop, which wins over the provider.

API `Returns`:
- `variant?: "default" | "compact"`. The resolved step.
- `control?: string`. `"h-9"` or `"h-7"`.
- `controlHeight?: number`. 36 or 28.
- `segmentItem?: string`. `"h-7"` or `"h-6"`.
- `segmentPad?: string`. `"p-1"` or `"p-0.5"`.
- `text?: string`. `"text-[13px]"` or `"text-[12px]"`.
- `px?: string`. `"px-3"` or `"px-2.5"`.
- `itemPx?: string`. `"px-2"` or `"px-1.5"`.
- `gap?: string`. `"gap-2"` or `"gap-1"`.
- `icon?: number`. 16 or 14 (px).

API `Other exports`:
- `useSizeVariant?: (override?: SizeVariant | null) => "default" | "compact"`. The resolved step only.
- `useSizeContext?: () => { size; setSize; classes }`. The provider's value. Throws outside a `SizeProvider`.
- `useTypeScale?: (override?: SizeVariant | null) => Record<TypeScaleRole, number>`. Pixel sizes for display, title, subtitle, body and caption.
- `sizeMap?: Record<SizeVariant, SizeClasses>`. Both steps, for reading outside React.
- `typeScale?: Record<TypeScaleRole, { default: number; compact: number }>`. display 28/24, title 16/15, subtitle 14/13, body 13/12, caption 12/11.
- `Types?: SizeVariant, SizeClasses, TypeScaleRole, TypeScaleStep`. Type exports.

### Class names

- Level: Utility
- Category: Utilities
- Status: Stable
- Import: `@oration/canon/lib/utils`
- Exports: `cn`
- Docs: /design/components/cn

`cn` joins class names and resolves Tailwind conflicts, so a component's defaults give way to the `className` a caller passes. The Canon version in `@oration/canon/lib/utils` is built with `createCn` and registers `text-13` and `text-2xs` as font sizes. Without that, the merge engine reads `text-13` as a text color: `cn("text-13", "text-foreground")` dropped the size, and `cn("text-sm", "text-13")` kept both. Components inside packages/canon still import the plain `cn` package, so they still have the bug.

When to use:
- Composing `className` in every component and demo: `cn("base classes", condition && "state class", className)`.
- Conditional classes, with falsy values, arrays and `{ class: boolean }` objects.
- Letting a caller override a default: put `className` last and the later class wins the conflict.

When not to use:
- A matrix of variants and sizes. Define it once with `cva`, as Button does with `buttonVariants`, and pass the result through `cn`. Use /design/components/button instead.
- Values that change at runtime, such as a width or a ratio. Set a CSS variable or `style`, as AspectRatio does with `--ratio`. Use /design/components/aspect-ratio instead.
- Toggling one class from a component's own state. A data attribute and a variant (`data-active:font-medium`) usually reads better.
- Importing `cn` from the `cn` package in apps/web. Use `@oration/canon/lib/utils`.

Rules:
- The Thirteen-Fourteen Rule: Dense UI is 13px, reading text is 14px, meta is 12px. 11px is for footnotes only. `text-13` is the most used size in the suite, so a merge that drops it breaks density everywhere it happens.

Behavior:
- Later classes win conflicts in the same group: `cn("px-2 py-1", "px-3")` is `py-1 px-3`.
- Falsy values are skipped, arrays are flattened and object keys are kept when their value is true.
- Canon's `cn` adds `13` and `2xs` to the `font-size` group, so `text-13` conflicts with `text-sm` (one size survives) and coexists with `text-foreground` (a size and a color).
- Arbitrary sizes such as `text-[13px]` are recognized as font sizes by both versions, which is why they are the safe override through packages/canon components.
- `text-2xs` was already treated as a size by the `cn` package (0.4.0); registering it is defensive. Only `text-13` was misread.

Do and don't:
- Do: Import `cn` from `@oration/canon/lib/utils` in app and docs code.
- Don't: Import it from the `cn` package, where `text-13` beside a text color silently drops the size.
- Do: Pass `text-[13px]` when shrinking a packages/canon component's `text-sm` through its `className`.
- Don't: Pass `text-13` to a packages/canon component. Its internal merge keeps `text-sm` and the label stays 14px.
- Do: Put the caller's `className` last: `cn(defaults, className)`.
- Don't: Put it first: `cn(className, defaults)`. The defaults win every conflict and overrides do nothing.

Accessibility:
- A dropped class is invisible in code review. After overriding focus, outline or ring classes, check the merged result still draws a visible focus indicator.
- A dropped `text-13` usually fails safe (text stays 14px), but a dropped color class can leave text at a contrast nobody chose.

Known gaps (follow the system, not the gap):
- 131 files in packages/canon import `cn` from the `cn` package, not from `@oration/canon/lib/utils`. Through their `className`, `text-13 text-muted-foreground` keeps the component's `text-sm` and drops the 13px. Use `text-[13px]` there until they switch.
- The comment in `lib/utils.ts` says both `text-13` and `text-2xs` read as colors before the change. With cn 0.4.0 only `text-13` did.

API `cn`:
- `...inputs?: ClassValue[]`. Strings, numbers, falsy values, arrays and `{ [className]: boolean }` objects.

API `Returns`:
- `className?: string`. The joined classes with conflicts resolved, later inputs winning.

### Scroll area

- Level: Utility
- Category: Layout
- Status: Experimental
- Import: `@oration/canon/components/scroll-area`
- Exports: `ScrollArea`, `ScrollBar`
- Docs: /design/components/scroll-area

ScrollArea wraps Base UI's scroll area: a viewport that scrolls natively, with a custom 10px vertical scrollbar whose thumb is drawn in `--border`. It gives a bounded panel, such as a long list in a popover or a fixed-height card, the same scrollbar in every browser and OS setting. Nothing in the product uses it yet; scrolling regions are plain `overflow-y-auto` with the thin global scrollbar. The usual mistake is giving it no height, so it never scrolls and the page grows instead.

When to use:
- A fixed-height list inside a card: an activity feed, recent remittances, a W-9 request log.
- A long list inside a popover or menu-like panel, such as a supplier picker.
- A region where the scrollbar must show regardless of the OS overlay-scrollbar setting.

When not to use:
- Page-level scrolling, sheets and dialogs. Let the document or the panel scroll natively.
- Horizontal tab and view rows. They hide the scrollbar and fade the clipped edge. Use /design/components/use-overflow-fade instead.
- Data grids with sticky headers and pinned columns. Use /design/components/data-grid instead.
- Chat threads that stick to the bottom as messages arrive. Use /design/components/message-scroller instead.
- The app sidebar. Use /design/components/sidebar instead.

Rules:
- The Scroll Edge Rule: Clipped content shows its edge. ScrollArea doesn't fade or shadow its edges on its own; Base UI sets `data-overflow-y-start` and `data-overflow-y-end` on the root if a region needs one.

Anatomy:
- Root: `relative`, takes `className` (give it the height). `data-slot="scroll-area"`.
- Viewport: Fills the root and scrolls natively. Corners inherit from the root. Focusable when it has overflow.
- Scrollbar: Vertical, 10px wide with 1px padding and a transparent left border. Unmounted when nothing overflows.
- Thumb: A `rounded-full bg-border` pill sized to the visible fraction. Drag it or click the track to jump.

States:
- Fits: No overflow: the scrollbar isn't rendered and the viewport leaves the tab order.
- Scrollable: The scrollbar and thumb show; the viewport is focusable.
- Hovering and scrolling: The scrollbar gets `data-hovering` and `data-scrolling`, but draws nothing different today.
- Focus visible: The viewport shows a 3px ring at 50% and a 1px outline when focused from the keyboard.

Behavior:
- Scrolling is native: wheel, trackpad, touch and keyboard all work, and scroll position survives re-renders.
- Thumb size and position come from CSS variables Base UI writes on each scroll. Clicking the track jumps there; dragging the thumb scrolls proportionally.
- The scrollbar sits at the inline end (`inset-inline-end`), so under an RTL direction it moves to the left.
- Children render inside the viewport. `ScrollArea` always adds one vertical `ScrollBar` and a corner.
- `overflowEdgeThreshold` sets how far content must scroll before the root's `data-overflow-*` edge attributes appear.

Do and don't:
- Do: Give the root a height or max height: `className="h-64"`.
- Don't: Leave it unsized. It grows with its content, never scrolls, and the page scrolls instead.
- Do: Keep native scrolling for pages, sheets and dialogs.
- Don't: Wrap a whole page in ScrollArea. Sticky headers, scroll restoration and find-in-page anchoring get harder for no gain.

Content:
- Give the region a heading or an accessible name so people know what scrolls: Activity on Northwind Freight.
- Put the most recent or most relevant items first, so the region is useful before anyone scrolls.

Accessibility:
- When content overflows, the viewport is in the tab order so keyboard users can scroll it; it has `role="presentation"`, so name the list inside it.
- The custom scrollbar is pointer-only. Keyboard and screen reader users scroll the viewport.
- The thumb is drawn in `--border` on a transparent track, a low-contrast affordance; don't rely on it as the only sign there is more.
- Tab: Focuses the viewport when it has overflow.
- ArrowUp + ArrowDown: Scrolls the focused viewport.
- PageUp + PageDown: Scrolls by a page.
- Home + End: Jumps to the top or bottom.

Known gaps (follow the system, not the gap):
- Not used in apps/web. Scrolling regions use `overflow-y-auto` with the global thin scrollbar in `--border-strong`, while ScrollArea's thumb is `--border`, so the two would look different side by side.
- The registry says the thumb widens on hover. The code doesn't: the track is always 10px and the thumb always `bg-border`.
- There's no way to add a horizontal scrollbar through `ScrollArea`: it renders only a vertical `ScrollBar`, and children land inside the viewport.
- The viewport focus ring is `ring-[3px] ring-ring/50` plus a 1px outline; Canon's focus ring elsewhere is `ring-3 ring-ring/40`.

API `ScrollArea` (extends Base UI `ScrollArea.Root` (`<div>`)):
- `className?: string`. Merged after `relative`. Set the height here.
- `children?: ReactNode`. Rendered inside the viewport.
- `overflowEdgeThreshold?: number | Partial<{ xStart; xEnd; yStart; yEnd }>` = 0. Pixels to scroll before the `data-overflow-*` edge attributes are set.

API `ScrollBar` (extends Base UI `ScrollArea.Scrollbar` (`<div>`)):
- `orientation?: "vertical" | "horizontal"` = "vertical". 10px wide when vertical, 10px tall when horizontal.
- `keepMounted?: boolean` = false. Keep the scrollbar in the DOM when nothing overflows.
- `className?: string`. Merged after the scrollbar classes.

### Aspect ratio

- Level: Utility
- Category: Layout
- Status: Experimental
- Import: `@oration/canon/components/aspect-ratio`
- Exports: `AspectRatio`
- Docs: /design/components/aspect-ratio

AspectRatio is a `<div>` that holds a width-to-height ratio with the CSS `aspect-ratio` property, so media and its placeholder keep their box while loading and the layout doesn't jump. Pass `ratio` as a number (`16 / 9`); it's set as `--ratio`. Nothing in the product uses it yet: the recording player, the meeting detail skeleton and Video facade use Tailwind's `aspect-video` directly, which does the same job for 16:9. The usual mistake is letting tall children stretch the box past its ratio.

When to use:
- Media with a known ratio that loads after the layout: recording thumbnails, receipt photos, document scans.
- A skeleton that must occupy exactly the space the media will.
- Ratios Tailwind doesn't name, such as a letter-size W-9 at `8.5 / 11` or a 4:3 receipt.
- A ratio that comes from data, such as an uploaded image's own width and height.

When not to use:
- A 16:9 video with a poster and a play button. The facade already holds the ratio and loads the player on demand. Use /design/components/video-facade instead.
- A fixed 16:9 or 1:1 box in your own markup. `aspect-video` or `aspect-square` is enough.
- People and company images. Use /design/components/avatar instead.
- Content-driven blocks such as cards of text, whose height should follow their content. Use /design/components/card instead.

Rules:
- The Tint Well Rule: Inside a card, a sub-region is a Well Gray tint at 70% with a 10px radius, never a second bordered or shadowed card. A media placeholder inside a card follows it: `rounded-[10px] bg-muted/70`.

Anatomy:
- Box: `relative aspect-(--ratio)`. Width comes from the parent; height follows from the ratio.
- Media: An absolutely positioned child (`absolute inset-0 size-full`), usually an image with `object-cover`, a video or a placeholder.
- Overlay: Optional controls or meta on top of the media, such as a play button or a timecode.

States:
- Loading: A skeleton or tint fills the box at its final size.
- Loaded: The media replaces the placeholder in place.
- Failed: Keep the box and show a quiet fallback inside it: an icon and one line, such as Preview unavailable.

Behavior:
- `ratio` is required and is width divided by height: `16 / 9`, `4 / 3`, `8.5 / 11`, `1`.
- The box takes the parent's width. Constrain it with the parent or a `max-w-*` class on the box.
- With `aspect-ratio`, content taller than the box makes it grow. Position children absolutely (`absolute inset-0`) or add `overflow-hidden` so the ratio holds.
- It's a server-safe component: no hooks, no `"use client"`.

Do and don't:
- Do: Reserve the media's box before it loads, with a placeholder at the final size.
- Don't: Let the media set its own height when it arrives, so everything below it jumps.
- Do: Fill the box with an absolutely positioned child and `object-cover`.
- Don't: Put flowing content inside it, which stretches the box past its ratio.

Content:
- Give images real alt text that says what's shown: Scanned W-9 from Orchard Street Supply, signed March 3, 2026. Decorative placeholders get `aria-hidden`.
- Captions and meta go below the frame, not over the media.
- A failed preview says what's missing and what still works: Preview unavailable. Download the PDF instead.

Accessibility:
- The box is a plain `<div>` with no role; the media inside carries the semantics (an `<img>` with `alt`, a `<video>` with controls and captions).
- Mark skeletons and decorative fills `aria-hidden`, and expose loading on the region with `aria-busy`.
- Controls laid over media need a visible focus ring against any frame, and a name: Play recording, not Play.

Known gaps (follow the system, not the gap):
- Not used in apps/web. The recording player, the meeting detail skeleton and Video facade hand-roll `aspect-video` instead.
- Props spread after `style`, so passing `style` drops `--ratio` and the box loses its ratio.

API `AspectRatio` (extends `<div>`):
- `ratio: number`. Width divided by height, e.g. `16 / 9`.
- `className?: string`. Merged after `relative aspect-(--ratio)`.
- `style?: CSSProperties`. Avoid passing it: it replaces the inline `--ratio` set from `ratio`.

### Direction provider

- Level: Utility
- Category: Utilities
- Status: Experimental
- Import: `@oration/canon/components/direction`
- Exports: `DirectionProvider`, `useDirection`
- Docs: /design/components/direction

DirectionProvider tells Base UI components which way text reads, so arrow-key navigation, logical popup sides (`inline-start`, `inline-end`) and scroll area scrollbars follow right-to-left languages. It's a straight re-export of Base UI's provider and `useDirection` hook. It doesn't set the `dir` attribute: put `dir="rtl"` on the same subtree so the browser's layout and logical classes (`ms-*`, `ps-*`, `start-*`, `text-start`) flip too. Oration ships in English only today and nothing renders it.

When to use:
- Wrapping the app, or a region, when it renders a right-to-left locale such as Arabic or Hebrew, alongside `dir="rtl"`.
- Previewing a component in RTL while building it, to check its keyboard and popup behavior.
- Inside a custom component that needs the direction for its own logic, such as which arrow key means next, through `useDirection()`.

When not to use:
- Flipping layout and spacing. That's the `dir` attribute plus logical classes, which work without the provider. Use /design/foundations/layout instead.
- A single paragraph of right-to-left text inside an English page, such as a supplier's note in Arabic. Set `dir="auto"` on that element.
- Mirroring an icon. Use `rtl:-scale-x-100` on direction-bearing icons only. Use /design/foundations/iconography instead.

States:
- Left to right: The default, `"ltr"`.
- Right to left: `"rtl"`: horizontal arrow keys swap in tabs, toolbars and radio groups, submenus open with ArrowLeft, `inline-*` popup sides flip, sliders run from the right, and scroll area scrollbars move to the left.

Behavior:
- `direction` defaults to `"ltr"`. Nested providers override outer ones for their subtree.
- Base UI reads it for keyboard navigation (in RTL, ArrowLeft moves to the next tab or item), for logical popup sides and alignment, and for scrollbar placement.
- Physical props don't flip: a popup with `side="right"` opens to the right in both directions. Use `side="inline-end"` for submenus and side panels that should follow reading direction.
- Popups portal to `<body>`, outside a `dir` set on a region, so their text runs left to right unless `dir` is on `<html>`. Set it on the document for a real RTL locale.
- `useDirection()` returns the nearest provider's direction, or `"ltr"` with none.

Do and don't:
- Do: Set `dir` and the provider together on the same root, ideally `<html dir>` plus a provider at the app root.
- Don't: Add the provider alone. Keyboard and popup logic flip while the layout stays left to right, so arrows and visuals disagree.
- Do: Use logical classes: `ms-2`, `ps-3`, `border-s`, `start-0`, `text-start`.
- Don't: Use physical ones (`ml-2`, `pl-3`, `border-l`, `left-0`, `text-left`) for anything that should follow reading direction. They stay put in RTL.

Content:
- Mirror icons that point along the reading direction (back, forward, next, reply, indent). Don't mirror logos, checkmarks, media controls, clocks or charts.
- Numbers, amounts, IDs and code stay left to right inside right-to-left text; wrap them in `<bdi>` or `dir="ltr"` when they sit next to RTL words.

Accessibility:
- Pair `dir` with the right `lang` on the same element so screen readers pick the right voice and reading order.
- Under RTL, arrow-key meaning flips in Base UI components; custom keyboard handling should read `useDirection()` and flip the same way.
- Focus order follows the DOM, which doesn't change with direction; keep the DOM in logical reading order.
- ArrowLeft: In a horizontal Base UI tab list or menu bar: previous item in LTR, next item in RTL.
- ArrowRight: Next item in LTR, previous item in RTL.

Known gaps (follow the system, not the gap):
- Not used anywhere: Oration has no right-to-left locale, so no component has been checked in RTL.
- 53 of 133 files in packages/canon/src/components use physical spacing or position classes (`ml-*`, `pl-*`, `left-*` and their pairs), which won't flip.
- `DropdownMenuSubContent` defaults to `side="right"` and the sub-trigger draws `ChevronRightIcon` with `ml-auto`, so submenus open and point the wrong way in RTL unless you pass `side="inline-end"`.
- `useOverflowFade` assumes left to right, so scrollable tab rows fade the wrong edges in RTL.

API `DirectionProvider` (extends Nothing; only these props):
- `direction?: "ltr" | "rtl"` = "ltr". The reading direction for Base UI components inside.
- `children?: ReactNode`. The subtree.

API `useDirection`:

API `Returns`:
- `direction?: "ltr" | "rtl"`. The nearest provider's direction, `"ltr"` without one.