# Loui DS: full documentation

> Loui DS is a dark, minimal, functional React design system (React 19, React Aria Components, CSS Modules, DTCG tokens) for internal tools, dashboards and apps. It is built to be operated by humans and AI agents.

Rules for generated UI:

- Use only components, hooks and tokens exported by the package; never write raw colors, px sizes, z-indexes or inline styles.
- One primary action per screen (`Button variant="primary"`), top right. The accent blue is for focus, selection and links only.
- Hierarchy comes from surface plus border; shadows only on overlays.
- Color never carries meaning alone: pair it with text or an icon with a name.
- Every interactive element needs an accessible name; icon-only controls require a `label`.
- Microcopy: English, sentence case, buttons are verb + object, no exclamation marks, no emoji. See content-rules.json.
- No user-visible string literals in components: use the message catalog and `DSProvider`.
- Money is integer minor units plus an ISO 4217 code; format dates, numbers and money with the provided utilities.
- Do not use `experimental` or `deprecated` components in recipes or generated code unless the user asks.

---

## Getting started

Browse every component live in Storybook: <https://xrazai.github.io/loUI/>. AI tools can load <https://xrazai.github.io/loUI/llms.txt> (see [Using with AI](./using-with-ai.md)).

### Requirements

- React 19 and React DOM 19 (peer dependencies). React 18 is not supported.
- An evergreen browser. Node 24 or later for tooling.
- A bundler that handles CSS imports and `woff2` assets (Vite, Next.js, webpack, esbuild).

### Install

```sh
pnpm add loui-ds react react-dom
```

`npm install loui-ds` and `yarn add loui-ds` work too. To upgrade, run `pnpm update loui-ds` and read the [release notes](https://github.com/xrazai/loUI/releases) first: before 1.0 a minor version may break. Every release also attaches the package tarball, if you need to install a version by URL.

`react-aria-components`, `react-stately` and `lucide-react` are regular dependencies of the package; you do not install them yourself.

### 1. Load the stylesheet once

Import the stylesheet once, at the root of your app, before any component renders:

```tsx
import 'loui-ds/styles.css';
```

It contains, in this layer order, `reset`, `tokens`, `base`, `components` and `utilities`. Because everything sits in named cascade layers, your own unlayered CSS always wins over the design system without specificity tricks.

The stylesheet sets the dark theme on the page (`bg-canvas` on `html`, `bg` and `text` on `body`, the Geist font), so you normally do not need your own reset.

### 2. Wrap the app in `DSProvider`

```tsx
import { DSProvider } from 'loui-ds';

export function Root({ children }: { children: React.ReactNode }) {
  return <DSProvider locale="en-US">{children}</DSProvider>;
}
```

| Prop       | Purpose                                                                                                          |
| ---------- | ---------------------------------------------------------------------------------------------------------------- |
| `locale`   | BCP 47 tag. Drives messages, number and date formatting, sorting, and the direction (RTL) of React Aria widgets. |
| `messages` | Overrides keyed by component, e.g. `{ Alert: { dismiss: 'Close' } }`. Applied over the built-in catalogs.        |
| `navigate` | Client-side navigation for `Link` and link-like components (your router's `navigate`).                           |
| `useHref`  | Maps a router path to a real `href` (needed for basename routing).                                               |

Without a provider everything still works in `en-US`; it just does not follow the user's locale. English is the default and `pt-BR` ships with the library. See `docs/architecture/i18n.md` for how messages resolve.

Client-side routing, for example with React Router:

```tsx
import { useNavigate, useHref } from 'react-router';

function Providers({ children }: { children: React.ReactNode }) {
  const navigate = useNavigate();
  return (
    <DSProvider navigate={navigate} useHref={useHref}>
      {children}
    </DSProvider>
  );
}
```

### 3. Use components

```tsx
import { Alert, Button } from 'loui-ds';

export function Example() {
  return (
    <>
      <Alert tone="warning" title="Low stock">
        3 boxes of notebooks are left. Reorder to avoid delays.
      </Alert>
      <Button variant="primary" onPress={() => console.log('created')}>
        Create order
      </Button>
    </>
  );
}
```

Use `onPress`, not `onClick`: it is the React Aria press event and works for mouse, touch, keyboard and screen readers.

### Fonts

Geist (UI) and Geist Mono (data) are self-hosted and ship inside the package: `styles.css` references `./fonts/*.woff2` relative to itself, and the build copies them to `dist/fonts`. Nothing is fetched from Google Fonts or a CDN at runtime. Your bundler resolves the font files when it processes `loui-ds/styles.css`; there is nothing to configure. Both families load with `font-display: swap` and a metric-matched fallback so the layout does not shift.

### Theming

Dark is the only theme. The semantic token layer (`--ds-bg`, `--ds-surface`, `--ds-text`, ...) can be overridden in your own CSS if you must; component code only reads semantic tokens. A `[data-theme="paper"]` scope provides the light surface for receipt and PDF previews. Forced-colors and reduced-motion modes are handled by the components.

### Server-side rendering

- Components never touch `window` or `document` while rendering or at import time, so they render on the server.
- IDs come from React `useId`; React Aria needs no `SSRProvider` with React 19.
- `useMediaQuery` returns its `defaultValue` (`false`) on the server and corrects after hydration. Prefer CSS media queries for styling.
- Import `loui-ds/styles.css` in the root layout so the first paint is already styled.

### Framework notes

**Vite.** Import the stylesheet in `main.tsx`; nothing else is needed.

**Next.js (App Router).** See [SSR and Next.js](#ssr-and-nextjs) below.

### SSR and Next.js

The package ships a `"use client"` directive **per module**: every file that uses hooks, React context or React Aria has it, and the entry points (`index.js`) and pure helpers do not. So a React Server Component (the default in the Next.js App Router) can import the design system directly, with no wrapper file:

```tsx
// app/layout.tsx (Server Component)
import 'loui-ds/styles.css';
import { DSProvider, ToastRegion } from 'loui-ds';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <DSProvider locale="en-US">
          {children}
          <ToastRegion />
        </DSProvider>
      </body>
    </html>
  );
}
```

```tsx
// app/page.tsx (Server Component): components are client references and render on the server too
import { Button, DataTable } from 'loui-ds';
```

Rules that follow from the React Server Components model, not from the library:

- Props that cross from a Server to a Client Component must be serializable. **Functions cannot**: `onPress`, `onChange`, render props such as `DataTable` column `render` or `Dialog` `footer={({ close }) => ...}`, and component values such as an `icon` prop. Put those in a file that starts with `'use client'` (a small component per interaction, see `examples/next-app/app/CreateOrderButton.tsx`).
- `DSProvider` takes plain props (`locale`, `messages`) and works in a Server layout; `navigate` and `useHref` are functions, so wrap the provider in a client component when you use client-side routing.
- Hooks (`useHotkeys`, `useToast`, ...) and the `toast` API only work in Client Components.
- Import the stylesheet once in the root layout. `dist/styles.css` and the Geist fonts need no `transpilePackages` or other `next.config` settings.

`sideEffects` in `package.json` lists only `**/*.css`, so bundlers drop unused components (importing `Button` alone costs about 12 kB brotli, enforced by `pnpm size` and `pnpm test:treeshake`). The packaging is verified on every pull request by building `examples/vite-app` and `examples/next-app` (Next.js 16, App Router, Turbopack) against a packed tarball: `pnpm examples:verify`.

### Next steps

- Read the [Principles](./principles.md) and the [Content guidelines](./content-guidelines.md) before building a screen.
- Browse the components in Storybook; each page lists props, variants, states and accessibility notes.
- Agents: start from [Using with AI](./using-with-ai.md).

---

## Principles

These rules apply to every screen built with Loui DS. They are short on purpose. When a case is not covered, choose the option that keeps the user's attention on one thing.

### Three rules

1. **One accent.** The blue accent (`--ds-accent`) is only for focus, selection, links and "open" states. Never use it for buttons or large fills.
2. **Ink for action.** The primary button is light on dark (`--ds-primary-bg`). Use **one primary action per screen**.
3. **Borders first.** Hierarchy comes from surface plus border. Shadows only on overlays: menus, toasts, dialogs and sheets.

### Clarity and focus

The system is designed for use that needs no effort of attention (the first product's owner has ADHD). Every new screen follows these rules.

1. **One main action per screen,** always at the top right, with a keyboard shortcut.
2. **The most important thing comes first and is largest.** Everything else is secondary text (`--ds-text-2`, `--ds-text-3`).
3. **Color only carries meaning, and is always accompanied by text.** Never signal status by color alone.
4. **Fixed positions.** The same element lives in the same place in every module, with no misalignments: a 4 px grid and fixed heights.
5. **Deleting always asks for confirmation** in a dialog: the title "Delete X?", the consequence in one sentence, a red button that names the action, and **initial focus on Cancel**. A toast with "Undo" follows. Reversible actions (mark, link, change status) never ask; they only offer "Undo".
6. **Lists are alphabetical by default** (locale-aware, accent-insensitive), including groups, columns and select options. Exceptions: tasks (by urgency) and dated records such as orders (newest first). Use `sortByText`.
7. **Visible progress.** Counters that go down, a day progress bar, a green check for done. Feedback is **subtle**: a 320 ms transition, no confetti.
8. **Save automatically** and show "Saved".
9. **Keyboard first.** `⌘K` for everything, and shortcuts on primary actions.

### Agents (AI features)

For products that put an AI agent in front of customers or money.

1. **Approve before sending.** Anything that goes to a customer or touches money goes through an approval queue. The default is to ask for approval.
2. **Autonomy per task,** never per whole agent. Low-star reviews (1 to 3 stars) always require approval.
3. **Undo, don't confirm.** Sending and discarding show a toast with Undo.
4. **The chat is for the owner,** not for the customer: to test, ask why and adjust. It reads the guidelines and the current data.
5. **Customer-facing replies** are short, factual, make no delivery-time or discount promises, and use no emoji.

### Visual foundations

The authoritative values are the design tokens (see the Tokens page). The summary:

- **Color.** A slightly warm neutral ramp from `#050506` to `#EDEDEA` (text is never pure white). Signals are pastel-bright so they keep contrast on dark: accent `#8AB4FF`, success `#5FD49A`, warning `#E9B65C`, danger `#F07A6E`. Soft backgrounds use `color-mix`.
- **Layers.** canvas, bg, surface, raised, hover. Move one layer at a time; do not skip layers.
- **Type.** Geist (400, 500, 600) for the interface, Geist Mono (400, 500) for data. Display and title use negative tracking.
- **Spacing.** A 4 px grid: 4, 8, 12, 16, 20, 24, 32, 48, 64. Card padding is 20; gaps of 8 to 16 inside components and 24 to 32 between sections.
- **Controls.** Heights 32, 40 (default) and 48. Buttons and inputs share the same height.
- **Radius.** 4 for chips, menu items and checkboxes; 6 for buttons and inputs; 10 for cards, menus and dialogs; pill for badges and switches.
- **Lines.** 1 px always. Subtle for internal dividers, regular for cards, strong for controls and overlays. Dashed means disabled or a total row.
- **Elevation.** Only `--ds-shadow-overlay` and `--ds-shadow-dialog`. No inner shadows, no glow, no blur.
- **States.** Hover is one surface step lighter. There is no press animation. Focus is an accent border plus a 3 px ring. A selected row has a raised background and a 2 px inset ink bar; the active tab has a 2 px ink underline. Disabled controls use reduced opacity and, for inputs, a dashed border.
- **Motion.** Minimal: 150 ms, `cubic-bezier(.2, 0, 0, 1)`, only color, opacity and position. Honor `prefers-reduced-motion`.
- **Backgrounds.** Flat. No gradients, textures or illustrations. Photos appear only in avatars and thumbnails.

### Iconography

- The icon set is **Lucide**, 1.5 px stroke, `currentColor`, **bundled** (never fetched from a CDN at runtime). Import icons from `loui-ds` (`PlusIcon`, `SearchIcon`, ...), not from `lucide-react`.
- Icons are decorative unless given a label. Icon-only controls use `IconButton`, which requires a `label`.
- No emoji. No filled or colored icons. Unicode glyphs (`+`, `×`, `⌘`) only inside labelled icon buttons.
- Outside the sidebar the system is text-first: actions use a label.

---

## Content guidelines

How the interface talks. These rules apply to every string in the UI: labels, buttons, titles, toasts, errors, empty states and confirmations. They are also available as data in `docs/ai/content-rules.json`.

### Tone

- **Direct, calm, technical without jargon.**
- Speak to "you", usually implied: "Select an order", not "Please select an order".
- State what happened and what to do. Do not blame the user and do not dramatize.

### Casing

- **Sentence case everywhere:** titles, buttons, tabs, menu items. "New order", not "New Order" or "NEW ORDER".
- Uppercase appears only in mono group captions, and it is applied with CSS, never typed.

### Buttons

- **A verb plus an object:** "Create order", "Mark as shipped", "Retry charge".
- Never a bare "OK", "Send" or "Submit".
- Destructive buttons name the action: "Delete order".

### Confirmations

Deleting always asks. The dialog names the object and the consequence in one sentence, the red button names the action, and initial focus is on Cancel.

> **Delete "Northwind Web"?**
> "Northwind Web" and its 14 environments will be removed. This can't be undone.
> [Cancel] [Delete project]

Reversible actions (mark, link, change status) do not ask. They happen and offer "Undo" in a toast.

### Toasts

Short and in the past tense: what just happened.

- "Order #1051 created"
- "3 items archived"

Not "Creating order", not "Success!", not "Order was successfully created".

### Empty states

Say what happened, then what to do.

- "No orders found. Try another filter or search term."

### Errors

Say how to fix the problem.

- "Enter a complete email address."

Not "Invalid email!". Link the message to its field (`aria-describedby`); the `Field` components do this for you.

### Punctuation and symbols

- **No emoji, no exclamation marks, no decorative ellipses.**
- The ellipsis character appears only on menu items that open something that needs more input: "Move to…".
- No "Loading..." or "Saving...". Use a spinner or skeleton, and state the result when it is done.

### Numbers, codes and shortcuts

- Numbers, codes, amounts and shortcuts are set in the mono font (Geist Mono): `ORD-1048`, `$1,240.00`, `⌘K`.
- **Never build currency, dates or numbers by hand.** Format them with `Intl` for the active locale through the provided utilities: `formatCurrency`, `formatDate`, `formatNumber`, `formatPercent`, `formatRelativeDays`.
- Money is an integer in minor units plus an ISO 4217 currency code (ADR-0006). `formatCurrency(124000, 'USD', locale)` renders `$1,240.00`.

### Lists

Alphabetical by default (locale-aware, accent-insensitive), including groups, columns and select options. Use `sortByText`. Exceptions: tasks (by urgency) and dated records (newest first).

### What belongs to the product, not to the design system

Domain vocabulary (for example, an ERP rule that sold units are always called "Quantity") belongs to the product's own guidelines. The design system's built-in strings stay generic.

### Built-in strings and translation

Components contain no user-visible string literals. Every built-in label and ARIA string lives in the component's message catalog (`<Name>.messages.ts`), is written in English following the rules above, and can be overridden per instance or through `DSProvider`. `pt-BR` ships with the library and follows the same tone.

---

## Accessibility

Accessibility is part of the definition of done for every component. The target is **WCAG 2.2 Level AA**, using the WAI-ARIA Authoring Practices patterns.

### Conformance target

- Real semantics first: native `<button>`, `<a>`, `<input>`, `<table>` where possible; ARIA only to fill gaps.
- Every interactive element has an accessible name. Icon-only controls require a `label` (enforced by the types).
- Errors, hints and descriptions are programmatically linked (`aria-describedby`, `aria-invalid`).
- Visible focus on every focusable element, including in `forced-colors` mode. Focus is never hidden behind sticky UI and is restored when overlays close.
- Contrast: 4.5:1 for text, 3:1 for UI boundaries and graphics. Every foreground and surface pairing is listed in `tokens.json` with its measured ratio and checked by a unit test.
- Color is never the only carrier of meaning.
- Targets are at least 24 by 24 CSS px (WCAG 2.5.8); default controls are 40 px.
- `prefers-reduced-motion`, `forced-colors` and `prefers-contrast` are respected; 200% text zoom and 320 px reflow are supported.
- Time-limited actions (such as an Undo toast) can be paused by hover or focus and reached by keyboard.

### Keyboard model

React Aria Components provides the behavior; each row becomes contract tests.

| Pattern          | Keys                                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Button, link     | `Enter`; button also `Space`                                                                                                                |
| Checkbox, switch | `Space` toggles                                                                                                                             |
| Radio group      | One tab stop (roving); arrow keys move and select, wrapping                                                                                 |
| Tabs             | Roving; `←` `→` move; `Home` `End`; `Tab` moves into the panel                                                                              |
| Menu             | Trigger opens with `Enter`, `Space` or `↓`; `↑` `↓`, `Home` `End`, typeahead; `Enter` or `Space` activates; `Esc` closes and restores focus |
| Combobox         | `↓` `↑` open and move; `Enter` selects; `Esc` closes, then clears                                                                           |
| Dialog, sheet    | Focus trapped; initial focus configurable (Cancel for destructive); `Esc` closes only the top layer; focus returns to trigger               |
| Popover, tooltip | `Esc` closes; tooltips show on focus and hover                                                                                              |
| Tag group        | One tab stop; arrow keys move; `Backspace` or `Delete` removes                                                                              |
| Toast, alert     | Announced through a live region; actions are focusable; auto-dismiss pauses on hover and focus                                              |

Application-level shortcuts use `useHotkey` (for example `Mod+K`); they ignore editable fields and IME composition so they never fight typing.

### How we test

Stories are the single source of states; the tests iterate over them.

| Layer             | Tool                                 | Guards                                                                |
| ----------------- | ------------------------------------ | --------------------------------------------------------------------- |
| Static            | `eslint-plugin-jsx-a11y` (strict)    | Role misuse, missing labels                                           |
| Component         | Vitest browser mode (Chromium)       | Props, states, events, controlled and uncontrolled, message overrides |
| Automated a11y    | axe-core through the Storybook addon | Structural WCAG violations on every story; a violation fails the test |
| Keyboard contract | Vitest and story `play` functions    | The keyboard table above                                              |
| Contrast          | Token unit test and browser checks   | Every token pair against its minimum ratio                            |
| Visual            | Screenshot baselines                 | Unintended appearance changes                                         |
| SSR               | Server render tests                  | No `window` access; hydration-safe                                    |
| Manual            | Screen reader checklist per release  | What automation cannot judge                                          |

Rules: a bug fix starts with a failing test; axe rules are never disabled globally; a scoped exception needs a comment with the reason and a task ID.

### Assistive technology

Automated checks cover structure and contrast. Manual screen reader testing (NVDA with Firefox and Chrome, VoiceOver with Safari, TalkBack) is planned per release against a checklist. No manual screen reader pass has been recorded yet, so treat that coverage as not yet performed.

### Known limitations

- Automated tests cannot judge reading order, announcement quality or whether labels make sense; those are reviewed by hand.
- jsdom cannot compute contrast or layout, so contrast and layout checks run in a real browser.
- Dark is the only theme. Contrast has been verified for it and for the `paper` scope; a new theme needs its own verification.

### Reporting an issue

Open an issue with the component, the browser and assistive technology, the steps, and what you expected. Accessibility bugs are treated as defects, not enhancements.

---

## Bundle size

How much JavaScript Loui DS adds to an app, where the rest comes from, and what to do about it.

### What a typical app ships

Measured on `examples/vite-app` (Vite 8, production build): an `AppShell` with `Sidebar`, `TopBar`, a `DataTable` with pagination, a `Dialog` with an `Input`, and toasts.

| Share of the bundle                                      | Before minification | Notes                                                                                                    |
| -------------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------- |
| `react-dom` + `react` + `scheduler`                      | ~550 kB             | Fixed cost of React 19.                                                                                  |
| `react-aria` + `react-aria-components` + `react-stately` | ~620 kB             | Behavior layer (ADR-0001): focus, keyboard, overlays, i18n. Includes translated strings for 30+ locales. |
| `loui-ds` (components, i18n, utilities)                  | ~90 kB              | Only the components the app imports; the package is tree-shakable (`sideEffects` lists CSS only).        |
| `lucide-react`                                           | ~10 kB              | Only the curated icons that are used.                                                                    |

Minified output: **531 kB (163 kB gzip)** without optimization, **489 kB (150 kB gzip)** with the locale plugin below. The design system's own code is under a tenth of the total; the rest is React and React Aria, which every app built on this system needs anyway.

### 1. Strip unused React Aria locales (recommended)

React Aria bundles its built-in strings (for example "Next month", "Dismiss") for every locale it supports. `@react-aria/optimize-locales-plugin` keeps only the locales your app serves. Use the same list you pass to `DSProvider`.

Vite:

```ts
// vite.config.ts
import optimizeLocales from '@react-aria/optimize-locales-plugin';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [{ ...optimizeLocales.vite({ locales: ['en-US', 'pt-BR'] }), enforce: 'pre' }, react()],
});
```

Next.js (webpack):

```ts
// next.config.ts
import optimizeLocales from '@react-aria/optimize-locales-plugin';
import type { NextConfig } from 'next';

const config: NextConfig = {
  webpack(webpackConfig) {
    webpackConfig.plugins.push(optimizeLocales.webpack({ locales: ['en-US', 'pt-BR'] }));
    return webpackConfig;
  },
};

export default config;
```

Saving in the example: 42 kB minified (14 kB gzip). A locale that is stripped falls back to English strings inside React Aria; Loui DS's own messages are unaffected (they come from its catalogs).

### 2. Import from the package root

Always `import { Button } from 'loui-ds'`. Bundlers drop what you do not use. Do not import from `loui-ds/dist/...` paths: they are not part of the public API and can duplicate modules.

### 3. Split heavy screens, not components

Lazy-load whole routes or rarely opened surfaces with `React.lazy` and `Suspense`, for example a settings page, a report with charts, or the command palette's command list. Splitting individual small components costs more in requests than it saves.

```tsx
const Reports = lazy(() => import('./routes/Reports'));
```

Keep `DSProvider`, `AppShell` and the toast region in the main chunk: they are on every screen.

### 4. Check before you ship

- `vite build` prints the size of each chunk; add `rollup-plugin-visualizer` (or Next's `@next/bundle-analyzer`) when a chunk grows unexpectedly.
- The design system itself is guarded by `size-limit` in its CI (`pnpm size`), so its own growth is reviewed per change.

---

## Color

Color in Loui DS is dark, flat and quiet. Hierarchy comes from five surface layers and three line weights; color itself is reserved for meaning. Use semantic tokens only (`--ds-surface`, `--ds-text-2`, `--ds-danger`); the primitive palette exists to define them. Every value, description and contrast ratio is listed on the Tokens page.

### Layers

Five surfaces build depth, from the darkest to the lightest. **Move one step at a time** and never skip a layer: a card sits on `bg`, something that floats sits on the card.

| Token                    | Use                                                                         |
| ------------------------ | --------------------------------------------------------------------------- |
| `--ds-bg-canvas`         | The page behind the app shell (the `html` element). Darkest layer.          |
| `--ds-bg`                | App background: body, top bar, main area.                                   |
| `--ds-surface`           | Cards, panels, table bodies and inputs at rest.                             |
| `--ds-surface-raised`    | Menus, popovers, selected rows, anything floating above a surface.          |
| `--ds-surface-hover`     | Hover state of controls and list items: one step above the resting surface. |
| `--ds-surface-row-hover` | Hover for table and list rows only. Subtler, so dense data stays calm.      |

### Lines

Borders do the work that shadows do elsewhere. Lines are always 1px. A dashed line means disabled or a total row.

| Token               | Use it for                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `--ds-line-subtle`  | Dividers inside a card or table (row separators). Decorative.                              |
| `--ds-line`         | The border of cards and containers.                                                        |
| `--ds-line-strong`  | The border of overlays: menus, popovers, dialogs.                                          |
| `--ds-line-control` | The boundary of form controls: input, select, textarea, checkbox, radio, combobox trigger. |

Form control boundaries must reach 3:1 against the surface (WCAG 1.4.11). `line` and `line-strong` do not, which is why controls have their own token.

### Text

| Token               | Use                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| `--ds-text`         | Primary text and icons. A warm off-white, never pure white. Anything the user must read.       |
| `--ds-text-2`       | Supporting text: descriptions, helper copy, inactive labels.                                   |
| `--ds-text-3`       | Tertiary text: metadata, placeholders, hints. Never the only carrier of essential information. |
| `--ds-text-inverse` | Text and icons on solid light or signal fills (primary button, selected calendar day).         |

All three text tokens pass 4.5:1 on every surface up to `surface-hover` (see the table below). The rule for `text-3` is about hierarchy, not contrast: the most important thing is `text`, supporting detail is `text-2`, and only metadata steps down to `text-3`. Do not use `text-3` on tinted or filled backgrounds; there is no contrast guarantee there.

`--ds-text-inverse` is measured on the fills it sits on, not on surfaces:

### Signals

One accent and three status colors. Each signal has a solid value for text and icons, and a soft tint for backgrounds.

- **Accent** (`--ds-accent`): focus, selection, links and "open" states. This is the only accent. **Never a button fill or a large area.** The primary button is light ink on dark (`--ds-primary-bg`), and there is one primary action per screen.
- **Success** (`--ds-success`): done, saved, healthy.
- **Warning** (`--ds-warning`): attention needed, nothing broken.
- **Danger** (`--ds-danger`): errors, invalid fields and destructive actions.

Success, warning and danger **always come with text** (a label, a message, an icon with a name). Color is never the only carrier of meaning.

### Soft tints

Soft tokens are the signal color at low opacity (14%, danger 10%), composited over the surface beneath. Use them as the background of badges, banners, selected items and invalid fields, with the solid signal as the text color. The ratio of a signal on its own tint is checked in the test suite.

### Paper

Receipt and PDF previews are the only light surface in the system. Scope them with `[data-theme="paper"]` and use `--ds-paper-*` tokens. `--ds-paper-rule` is decorative (below 3:1) and must never be a control boundary.

Inside the scope, `--ds-success`, `--ds-warning`, `--ds-danger` and `--ds-accent` are remapped to darker twins (`--ds-paper-success`, `--ds-paper-warning`, `--ds-paper-danger`, `--ds-paper-accent`), and their tints (`--ds-success-soft` and the others) are remapped with them, so badges, alerts and tinted buttons keep 4.5:1 on the paper. The `Components/Card` story `PaperReceipt` shows the scope.

### Contrast changes from the handoff

Three tokens were changed from the original design handoff so that every text and control pairing meets WCAG 2.2 AA (task TOK-004). The full record is in `docs/tokens/changes.md`.

| Token                             | Old           | New       | Why                                                                                                                                          |
| --------------------------------- | ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ds-text-3` (and `--ds-gray-7`) | `#7A7A82`     | `#86868E` | Was 3.86:1 on `surface-hover` and below 4.5:1 on `surface-raised`. Now 4.55:1 on `surface-hover`, so it passes on every surface up to there. |
| `--ds-line-control`               | did not exist | `#64646B` | Control boundaries need 3:1. `line-strong` is about 1.5:1. Now 3.35:1 on `bg`, 3.21:1 on `surface`, 3.02:1 on `surface-raised`.              |
| `--ds-paper-accent`               | `#B8603E`     | `#944A2D` | 5.7:1 on `paper`, 4.7:1 on its 14% tint (TOK-012); the original was below 4.5:1 for text.                                                    |

### Rules of thumb

- Use `text` for what must be read, `text-2` for support, `text-3` for metadata.
- Never use a raw hex value. If a color is missing, add a token.
- Backgrounds are flat: no gradients, textures or illustrations.
- A selected state combines a surface step with a non-color cue (an ink bar, a check), never color alone.

---

## Typography

Two typefaces, ten roles, one rule: nothing is smaller than 11.5px. Geist carries the interface; Geist Mono carries data. Both are self-hosted (no runtime fetch), with metric-matched fallback faces so text does not jump while fonts load.

### Typefaces

| Variable         | Face       | Weights       | Use                                                            |
| ---------------- | ---------- | ------------- | -------------------------------------------------------------- |
| `--ds-font-sans` | Geist      | 400, 500, 600 | Interface text: titles, body, labels, buttons.                 |
| `--ds-font-mono` | Geist Mono | 400, 500      | Data: numbers, codes, identifiers, dates, shortcuts, captions. |

Weight roles: **400** for body text, **500** for labels and mono captions (not for body paragraphs), **600** for display, title and heading. Do not add a heavier weight.

### The scale

Use a role, never a free size. The roles are the tokens `--ds-fs-*` (size), `--ds-lh-*` (line height) and `--ds-weight-*`. Sizes in px, line heights in px.

| Role    | Face     | Use it for                                                              |
| ------- | -------- | ----------------------------------------------------------------------- |
| display | sans 600 | One hero statement per view, at most.                                   |
| title   | sans 600 | Page and section titles.                                                |
| heading | sans 600 | Dialog titles, card headings.                                           |
| body    | sans 400 | Running text; the base size of the app.                                 |
| small   | sans 400 | Descriptions, helper text, table cells.                                 |
| label   | sans 500 | Field labels, chips, compact buttons.                                   |
| meta    | mono 400 | Dates, phone numbers, counts beside titles.                             |
| caption | mono 500 | Group captions. Uppercase by CSS, +8% tracking. The floor of the scale. |
| num     | mono 500 | Indicator figures (24px).                                               |
| num-lg  | mono 500 | Highlighted totals such as a balance (30px).                            |

### Tracking and case

- **Display** has -2% tracking (-0.68px) and **title** -1% (-0.22px). Tight tracking only works at large sizes: never apply it to body text.
- **Caption** has +8% tracking (0.92px) and is the only role set in uppercase. Uppercase is applied with CSS (`text-transform`), so write the source text in sentence case ("Order details", not "ORDER DETAILS"). Everywhere else, use sentence case too.
- Tracking tokens are in px because DTCG dimensions have no `em`. They are exact for the fixed size of each role.

### The 11.5px floor

`--ds-fs-caption` (11.5px) is the smallest font size in the system and it is enforced by a test. Do not use a smaller size, in CSS or in a chart, and do not scale text down with transforms. Use `meta` (12px) or `caption` for the smallest text; never invent an in-between.

### When to use mono

Use Geist Mono for anything that is data rather than prose, and turn on tabular figures so columns align.

- Numbers and amounts: `$1,240.00`, `3 / 12`.
- Codes and identifiers: `ORD-1048`, `SKU-0032`.
- Dates and phone numbers beside a title.
- Keyboard shortcuts: `Ctrl K`.
- Group captions.

Do not set sentences, labels or buttons in mono. Format amounts and dates with `Intl` (the `formatCurrency` helper), never by hand.

### Tabular numerals

`font-variant-numeric: tabular-nums` gives every digit the same width, so figures in a column line up and live counters do not jitter. The `mono` prop of `Text` turns it on; for custom elements use the `.ds-tabular-nums` utility class. Mono roles (`meta`, `num`, `num-lg`) should always have it on.

### Heading and Text

`Heading` separates the semantic level (`h1` to `h6`, the page outline) from the visual size (`display`, `title`, `heading`). Choose the level for structure and the size for design; keep levels sequential with one `h1` per page. `Text` sets size, line height, tone and an optional mono face, and the `as` prop picks the element.

Use `Heading` and `Text` instead of setting font properties by hand. Do not use a heading element only for its size.

---

## Spacing, sizing and radius

Everything sits on a 4px grid and has a fixed size, so the same element lives in the same place in every module. Use tokens, never raw pixels.

### Spacing scale

Nine steps. The unit is 4px; steps are named by their multiple (`--ds-space-3` is 3 x 4px = 12px).

| Variable        | Value | Use                                                      |
| --------------- | ----- | -------------------------------------------------------- |
| `--ds-space-1`  | 4px   | Icon-to-text gaps, tight padding.                        |
| `--ds-space-2`  | 8px   | Default gap between related elements inside a component. |
| `--ds-space-3`  | 12px  | Compact padding, gaps between form fields.               |
| `--ds-space-4`  | 16px  | Standard padding and gap between components.             |
| `--ds-space-5`  | 20px  | Card padding.                                            |
| `--ds-space-6`  | 24px  | Gap between sections of a page.                          |
| `--ds-space-8`  | 32px  | Large section separation.                                |
| `--ds-space-12` | 48px  | Page-level separation.                                   |
| `--ds-space-16` | 64px  | Hero and empty-state breathing room.                     |

Rules of thumb: card padding is 20px; gaps **inside** a component are 8 to 16px; gaps **between** sections are 24 to 32px. Do not mix steps in one group, and do not use values off the grid.

### Control heights

Controls come in three heights. The default is 40px. Pick one size per group of controls and do not mix them in a row.

| Token               | Value | Use                                    |
| ------------------- | ----- | -------------------------------------- |
| `--ds-control-h-sm` | 32px  | Dense toolbars and table filters.      |
| `--ds-control-h-md` | 40px  | Default: buttons, inputs, selects.     |
| `--ds-control-h-lg` | 48px  | Primary actions and touch-first forms. |

### Fixed layout sizes

| Token              | Value | Use                                                                     |
| ------------------ | ----- | ----------------------------------------------------------------------- |
| `--ds-item-h`      | 36px  | Menu items, navigation items, listbox options.                          |
| `--ds-row-h`       | 52px  | Table and list rows.                                                    |
| `--ds-row-h-dense` | 60px  | Rows with two lines of content. It is taller on purpose: it holds more. |
| `--ds-topbar-h`    | 64px  | The top bar.                                                            |
| `--ds-sidebar-w`   | 240px | The app sidebar.                                                        |

### Target size

No interactive element may be smaller than 24 x 24 CSS px (`--ds-target-min`, WCAG 2.5.8). Small visuals, such as the 18px checkbox box, reach the minimum through their label row or padding. Never shrink the clickable area to match a small icon.

### Radius

Radius follows the role of the element, so nested shapes look related.

| Token              | Value | Elements                                                       |
| ------------------ | ----- | -------------------------------------------------------------- |
| `--ds-radius-sm`   | 4px   | Chips, menu items, small marks.                                |
| `--ds-radius-md`   | 6px   | Buttons and inputs.                                            |
| `--ds-radius-lg`   | 10px  | Cards, menus, popovers, dialogs.                               |
| `--ds-radius-pill` | 999px | Badges and switches. Any very large value renders fully round. |

The checkbox box uses a component token (`--ds-checkbox-radius`, 5px). An inner element has a smaller radius than its container.

### Elevation

Hierarchy comes from surface plus border, not from shadow. There are **only two shadows, and only overlays use them**.

| Token                 | Use                                             |
| --------------------- | ----------------------------------------------- |
| `--ds-shadow-overlay` | Floating overlays: menus, popovers, toasts.     |
| `--ds-shadow-dialog`  | Dialogs and side sheets: the highest elevation. |

No inner shadows, no glow, no blur. Cards, panels and inline elements are flat. Dialogs use the `--ds-overlay` backdrop and sheets use the lighter `--ds-scrim`, both without blur.

---

## States and interaction

Every interactive element has the same small set of states, and they look the same everywhere. Feedback is subtle: no press animation, no bounce, no confetti.

### The states

| State    | What changes                                                                                                               | Notes                                                        |
| -------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Rest     | The base surface, a 1px line.                                                                                              |                                                              |
| Hover    | One surface step lighter (`surface` becomes `surface-hover`). The primary button dims to 88% brightness instead.           | Table rows use the subtler `surface-row-hover`.              |
| Focus    | Accent border plus a 3px ring (`--ds-focus-ring`).                                                                         | Shown for keyboard focus (`:focus-visible`). Always visible. |
| Pressed  | No visual change.                                                                                                          | There is no press animation by design.                       |
| Selected | Raised background plus a 2px ink bar on the left of a row; a 2px ink underline for the active tab; a check for checkboxes. | Never color alone.                                           |
| Disabled | Opacity 35% (`--ds-opacity-disabled`), no hover; inputs also get a dashed border.                                          | One value for every component.                               |
| Invalid  | Danger border and the danger ring (`--ds-focus-ring-danger`), with an error message in text.                               | The message says how to fix it.                              |
| Pending  | The label is replaced by a spinner at the same width. The control stays focusable.                                         | Not disabled: focus is never lost.                           |

States are CSS, not React state: components expose them as data attributes (`data-hovered`, `data-focus-visible`, `data-selected`, `data-disabled`, `data-invalid`), and styles never use inline overrides.

### Fields

Inputs, selects and other fields move through rest, focus, invalid and disabled. Tab into a field to see the focus ring; the other states are set by props.

### Selection controls

### Tabs and rows

An active tab has a 2px ink underline. A selected table row has a raised background and a 2px ink bar on its inline-start edge. Both also work in forced-colors mode.

### Focus

Focus is always visible. Buttons, fields, tabs and panels show an accent border or a 3px ring; table rows, headers and cells show a 2px accent outline inset in the cell. A transparent outline is kept so the focus indicator also appears in forced-colors (high contrast) mode. Focus is never hidden behind sticky UI, and it is restored to the trigger when an overlay closes.

### Keyboard model

Keyboard first: everything is reachable and operable without a pointer, `Tab` and `Shift+Tab` walk the page in reading order, and `Ctrl K` (Command K on Apple) opens the command palette. Each row below is also a contract test.

| Pattern                                | Keys                                                                                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Button / link                          | `Enter`; button also `Space`                                                                                                                            |
| Checkbox / switch                      | `Space` toggles (switch also `Enter` optional)                                                                                                          |
| Radio group / segmented / choice tiles | One tab stop (roving); `Left/Up` previous, `Right/Down` next (radio groups wrap; segmented controls stop at the ends); `Space` selects                  |
| Tabs                                   | Roving; `Left/Right` move; `Home/End`; automatic or manual activation as documented; `Tab` moves into the panel                                         |
| Menu                                   | Trigger `Enter/Space/Down` opens and focuses the first item; `Up/Down`, `Home/End`, typeahead; `Enter/Space` activates; `Esc` closes and restores focus |
| Combobox                               | `Down/Up` open and move (`aria-activedescendant`), `Enter` selects, `Esc` closes then clears, `Home/End` in the list                                    |
| Dialog / sheet                         | Focus trapped; initial focus configurable (Cancel for destructive); `Esc` closes **only the top layer**; focus returns to the trigger                   |
| Popover                                | `Esc` closes and restores focus; focus moves in only if interactive                                                                                     |
| Tooltip                                | Shows on focus and hover; `Esc` dismisses; content is hoverable                                                                                         |
| Accordion / disclosure                 | `Enter/Space` toggles; optional `Up/Down/Home/End` between headers                                                                                      |
| Slider                                 | Arrow keys step; `PageUp/PageDown` large step; `Home/End` min/max                                                                                       |
| Number field (stepper)                 | Textbox with `aria-roledescription="Number field"`; `Up/Down` step; `PageUp/PageDown` step; `Home/End` min/max; typing allowed                          |
| Calendar grid                          | Arrows move by day/week; `PageUp/PageDown` month; `Shift+PageUp/PageDown` year; `Home/End` first/last day of the month; `Enter/Space` selects           |
| Data table                             | Header buttons sort (`aria-sort`); row action via a real button or link; selection checkboxes are labelled                                              |
| Toast / alert                          | Announced through a live region; actions focusable; auto-dismiss pauses on hover and focus                                                              |

Sources: the WAI-ARIA Authoring Practices and React Aria. The same table is in the [accessibility guide](../guides/accessibility.md).

### Undo, or confirm

Two kinds of action, two behaviors. Do not mix them.

- **Undo for almost everything.** Change a status, pay, send, remove a row, link a color: do it at once and show a toast with "Undo" (short-lived, and paused while hovered or focused). It is faster and calmer than asking.
- **Confirm only when deleting a record.** Delete a product, customer, sale, order or entry: open a dialog. The title is "Delete X?", one sentence states the consequence, the red button names the action (`danger-solid`, "Delete order"), and **initial focus is on Cancel**. A toast with "Undo" follows when the data can be restored.

Anything that goes to a customer or touches money goes through an approval queue instead; see the [principles guide](../guides/principles.md).

### Wordmark

There is no logo. Until a brand exists, the product name is set in Geist 600 as plain text. Do not draw, trace or approximate a mark, and do not use an icon as a logo.

---

## Motion, layering and iconography

Motion is minimal, layers are strictly ordered, and icons come from one small curated set.

### Motion

Motion explains a change; it never decorates. Only `color`, `background-color`, `border-color`, `opacity` and position change, never size or layout.

| Token                    | Value                        | Use                                                                              |
| ------------------------ | ---------------------------- | -------------------------------------------------------------------------------- |
| `--ds-duration`          | 150ms                        | Standard transition: hover, focus and state changes.                             |
| `--ds-duration-done`     | 320ms                        | Completion feedback: a subtle check or fill when something is done. No confetti. |
| `--ds-duration-progress` | 300ms                        | Progress bar fill changes.                                                       |
| `--ds-ease`              | `cubic-bezier(0.2, 0, 0, 1)` | Easing for every transition: fast start, soft landing.                           |

Rules:

- Use the tokens; never write a raw duration or easing.
- No press animation, bounce, spring, parallax or looping decoration. The only continuous animation is a loading spinner.
- Feedback for a finished task is subtle and positive: a green check, a filled progress bar, a calm toast.

#### Reduced motion

When the user asks for less motion (`prefers-reduced-motion: reduce`), the base stylesheet cuts every transition and animation to an instant change, globally. Components must not depend on a transition to communicate state: the end state alone has to be clear. Do not add per-component motion that bypasses this rule.

### Layering

Overlays use a fixed stack of z-index tokens. Raw `z-index` values are not allowed.

| Layer    | Token             | Value | Why it sits here                                                                                |
| -------- | ----------------- | ----- | ----------------------------------------------------------------------------------------------- |
| Sheet    | `--ds-z-sheet`    | 40    | Side panels with their scrim. The panel is the sheet value plus one. The lowest overlay.        |
| Dialog   | `--ds-z-dialog`   | 45    | Modals and their backdrop. Above sheets, so a dialog opened from a sheet stacks on top of it.   |
| Dropdown | `--ds-z-dropdown` | 50    | Selects, comboboxes, date pickers. Above dialogs and sheets because they open from inside them. |
| Popover  | `--ds-z-popover`  | 55    | Popovers and action menus. Above dropdowns, dialogs and sheets.                                 |
| Toast    | `--ds-z-toast`    | 58    | Confirmations and Undo. Above every overlay so they stay visible.                               |
| Tooltip  | `--ds-z-tooltip`  | 60    | The highest layer. It must never be hidden. Do not add layers above it.                         |

Order: **sheet < dialog < dropdown < popover < toast < tooltip**. `Esc` closes only the top layer. Overlays render through a shared portal, so they never depend on the stacking context of their trigger.

### Iconography

Icons are Lucide, bundled in the package (never fetched from a CDN at runtime), drawn with a 1.5px stroke in `currentColor`.

- **Curated set only.** Import from the design system (`SearchIcon`, `XIcon`), not from `lucide-react`. To add an icon, add it to the set with a documented use first.
- **Decorative unless labelled.** `Icon` hides itself from assistive technology by default; the text next to it names the control. Pass `label` only when the icon carries meaning on its own. An icon-only control is an `IconButton`, and its `label` is required.
- **Sizes** are tokens: `xs` 12px, `sm` 14px, `md` 18px (default), `lg` 20px.
- **Directional icons** (chevrons, arrows) take the `directional` prop so they mirror in right-to-left languages.
- **No emoji.** No filled or colored icons, with one exception: the filled star of `Rating`. Unicode glyphs appear only inside a labelled `IconButton`.
- Color comes from the surrounding text color. A status icon is paired with text; do not rely on its color.

#### Decorative and labelled

---

## Design tokens

459 tokens; the table lists the 445 semantic and core ones (primitives are listed in tokens.json). Use the CSS variable, never the value.

| CSS variable | Value | Use |
| --- | --- | --- |
| `--ds-bg-canvas` | `#050506` | Page canvas behind the app shell (the html element). The darkest layer. Not for cards or controls. |
| `--ds-bg` | `#0B0B0C` | Default app background (body, top bar, main area). One step above the canvas. Not for cards; use surface. |
| `--ds-surface` | `#111113` | Cards, panels, table bodies and inputs at rest. Move one layer at a time: bg, surface, surface-raised, surface-hover. |
| `--ds-surface-raised` | `#18181B` | Menus, popovers, selected rows and anything floating above a surface. Not for page backgrounds. |
| `--ds-surface-hover` | `#1F1F23` | Hover state of controls and list items: one step lighter than the resting surface. Do not use at rest. |
| `--ds-surface-row-hover` | `#141416` | Hover background of table and list rows only; subtler than surface-hover so dense data stays calm. Not for buttons or menu items. |
| `--ds-line-subtle` | `#1E1E22` | Internal dividers inside a card or table (row separators). Decorative, so exempt from the 3:1 non-text contrast rule. Never use it as a control boundary. |
| `--ds-line` | `#26262B` | Default 1px border of cards and containers. Not for form control boundaries; use line-control. |
| `--ds-line-strong` | `#33333A` | Border of overlays, menus, popovers, dialogs and cards that must stand out. Not for form control boundaries (use line-control); it is below 3:1. |
| `--ds-line-control` | `#64646B` | Boundary of form controls: input, select, textarea, checkbox, radio and combobox triggers. At least 3:1 on bg, surface and surface-raised (WCAG 1.4.11). New in TOK-004. Not for decorative dividers. |
| `--ds-text` | `#EDEDEA` | Primary text and icons. Warm off-white, not pure white. Use for anything that must be read first. |
| `--ds-text-2` | `#A3A3A9` | Secondary text: descriptions, supporting copy, inactive labels. |
| `--ds-text-3` | `#86868E` | Tertiary text: metadata, placeholders, hints. Meets 4.5:1 on every surface up to surface-hover. Do not use on surfaces lighter than surface-hover or on colored fills. |
| `--ds-text-inverse` | `#0B0B0C` | Text and icons on solid light or signal fills (selected day in a calendar, solid badges). Not on dark surfaces. |
| `--ds-primary-bg` | `#EDEDEA` | Fill of the primary button and the tooltip: light ink on a dark UI. One primary action per screen. Hover is brightness .88, not a new token. |
| `--ds-primary-fg` | `#0B0B0C` | Text and icons on primary-bg. |
| `--ds-primary-fg-muted` | `#5A5A60` | Secondary text on primary-bg (for example the shortcut hint in a tooltip). Only valid on primary-bg. |
| `--ds-accent` | `#8AB4FF` | The single accent: focus, selection, links and open states. Never a button fill or a large area. Always pair with text or a shape, never color alone. |
| `--ds-success` | `#5FD49A` | Success signal: done, saved, healthy. Always accompanied by text or an icon. Not decorative. |
| `--ds-warning` | `#E9B65C` | Warning signal: attention needed, nothing broken. Always accompanied by text or an icon. |
| `--ds-danger` | `#F07A6E` | Error and destructive signal: errors, delete buttons, invalid fields. Always accompanied by text or an icon. |
| `--ds-accent-soft` | `rgba(138, 180, 255, 0.14)` | Tinted background for accent states (selected item, info). 14% accent over the surface beneath, resolved with color-mix so it adapts to the surface. Not for text. |
| `--ds-success-soft` | `rgba(95, 212, 154, 0.14)` | Tinted background for success states (badge, banner). 14% success over the surface beneath. Not for text. |
| `--ds-warning-soft` | `rgba(233, 182, 92, 0.14)` | Tinted background for warning states (badge, banner). 14% warning over the surface beneath. Not for text. |
| `--ds-danger-soft` | `rgba(240, 122, 110, 0.1)` | Tinted background for error states (badge, banner, invalid field). 10% danger over the surface beneath. Not for text. |
| `--ds-danger-soft-hover` | `rgba(240, 122, 110, 0.18)` | Hover state of danger-soft surfaces such as the ghost-danger button. 18% danger over the surface beneath. |
| `--ds-danger-line` | `rgba(240, 122, 110, 0.35)` | Border of danger-tinted surfaces (error banner, destructive confirmation). 35% danger over the surface beneath. Not a form control boundary; invalid fields use danger. |
| `--ds-overlay` | `rgba(5, 5, 6, 0.72)` | Backdrop behind dialogs. Flat, no blur. Not for side sheets; use scrim. |
| `--ds-scrim` | `rgba(5, 5, 6, 0.55)` | Backdrop behind side sheets. Lighter than overlay so the page stays visible. Not for dialogs. |
| `--ds-swatch-ring` | `rgba(255, 255, 255, 0.12)` | Inset 1px ring drawn inside color swatches and avatars so dark swatches stay visible on dark surfaces. Not a general border. |
| `--ds-paper` | `#F4F2EC` | Paper surface of printed-document previews (receipt, PDF). The only light surface in the system; use inside [data-theme="paper"] only. |
| `--ds-paper-ink` | `#151515` | Primary text on paper. Paper theme only. |
| `--ds-paper-ink-2` | `#3A3A3A` | Secondary text on paper. Paper theme only. |
| `--ds-paper-muted` | `#6B6B6B` | Tertiary text and control boundaries on paper (above 4.5:1 on paper). Paper theme only. |
| `--ds-paper-rule` | `#9A968C` | Decorative rules and dividers on paper (table lines, totals). Below 3:1, so never a control boundary or text. Paper theme only. |
| `--ds-paper-accent` | `#944A2D` | Accent on paper: links and highlighted figures (5.7:1 on paper, 4.7:1 on paper-accent-soft). Darkened from #B8603E in TOK-004 and again from #A95839 in TOK-012 so accent text passes on its own tint. Paper theme only. |
| `--ds-paper-success` | `#17683D` | Success signal on paper: text, icons and borders (6.1:1 on paper, 4.9:1 on paper-success-soft). Remaps success inside [data-theme="paper"] only (TOK-012). |
| `--ds-paper-warning` | `#7F5200` | Warning signal on paper: text, icons and borders (6.0:1 on paper, 4.9:1 on paper-warning-soft). Remaps warning inside [data-theme="paper"] only (TOK-012). |
| `--ds-paper-danger` | `#A8231B` | Error and destructive signal on paper (6.4:1 on paper, 4.8:1 on paper-danger-soft-hover). Remaps danger inside [data-theme="paper"] only (TOK-012). |
| `--ds-paper-success-soft` | `rgba(23, 104, 61, 0.14)` | Tinted background for success states on paper. 14% paper-success over the paper. Not for text. Paper theme only. |
| `--ds-paper-warning-soft` | `rgba(127, 82, 0, 0.14)` | Tinted background for warning states on paper. 14% paper-warning over the paper. Not for text. Paper theme only. |
| `--ds-paper-danger-soft` | `rgba(168, 35, 27, 0.1)` | Tinted background for error states on paper. 10% paper-danger over the paper. Not for text. Paper theme only. |
| `--ds-paper-danger-soft-hover` | `rgba(168, 35, 27, 0.18)` | Hover state of paper-danger-soft surfaces. 18% paper-danger over the paper. Paper theme only. |
| `--ds-paper-danger-line` | `rgba(168, 35, 27, 0.35)` | Border of danger-tinted surfaces on paper. 35% paper-danger over the paper. Paper theme only. |
| `--ds-paper-accent-soft` | `rgba(148, 74, 45, 0.14)` | Tinted background for accent states on paper (selected item, info badge). 14% paper-accent over the paper. Not for text. Paper theme only. |
| `--ds-focus-ring` | `0px 0px 0px 3px rgba(138, 180, 255, 0.25)` | Focus halo: 3px ring, 25% accent over the surface beneath, used as box-shadow next to an accent border. base.css adds a transparent outline so focus stays visible in forced-colors mode. Not a hover or selected style. |
| `--ds-focus-ring-danger` | `0px 0px 0px 3px rgba(240, 122, 110, 0.25)` | Focus halo for invalid fields: 3px ring, 25% danger over the surface beneath. Use instead of focus-ring when the control is in an error state. Not a general error style. |
| `--ds-font-sans` | `Geist, "Geist Fallback", system-ui, sans-serif` | UI font stack: self-hosted Geist, then a metric-matched Arial fallback face, then the system font. Use for all interface text. Not for numbers, codes or data (use font.mono). |
| `--ds-font-mono` | `"Geist Mono", "Geist Mono Fallback", ui-monospace, monospace` | Data font stack: self-hosted Geist Mono with a metric-matched fallback. Use for numbers, codes, amounts, shortcuts and uppercase group captions. Pair with tabular-nums. Not for running text. |
| `--ds-weight-regular` | `400` | Regular weight (400): body text, descriptions, mono data. |
| `--ds-weight-medium` | `500` | Medium weight (500): labels, chips, mono captions. Not for body paragraphs. |
| `--ds-weight-semibold` | `600` | Semibold weight (600): display, title and heading. The heaviest weight in use; do not add bold (700). |
| `--ds-fs-display` | `34px` | Display font size (34px, line 40px, tracking -2%, semibold). Hero statement; at most once per screen. Minimum font size in the system is 11.5px (caption); never go below it. |
| `--ds-fs-title` | `22px` | Title font size (22px, line 30px, tracking -1%, semibold). Page and section titles. Minimum font size in the system is 11.5px (caption); never go below it. |
| `--ds-fs-heading` | `17px` | Heading font size (17px, line 24px, semibold). Dialog titles and card headings. Minimum font size in the system is 11.5px (caption); never go below it. |
| `--ds-fs-body` | `15px` | Body font size (15px, line 24px, regular). Default running text; the base size of the app. Minimum font size in the system is 11.5px (caption); never go below it. |
| `--ds-fs-small` | `14px` | Small font size (14px, line 22px, regular). Descriptions, helper text and table cells. Minimum font size in the system is 11.5px (caption); never go below it. |
| `--ds-fs-label` | `13px` | Label font size (13px, line 18px, medium). Field labels, chips and compact buttons. Minimum font size in the system is 11.5px (caption); never go below it. |
| `--ds-fs-meta` | `12px` | Meta font size (12px, line 16px, mono regular). Dates, phone numbers and counts next to titles. Minimum font size in the system is 11.5px (caption); never go below it. |
| `--ds-fs-caption` | `11.5px` | Caption font size (11.5px, line 16px, mono medium, uppercase, +8% tracking). FLOOR of the type scale: no token or component may use a smaller size. Group captions and table headers. |
| `--ds-fs-num` | `24px` | Number font size for indicator figures (24px, line 32px, mono medium). Use with tabular-nums. Minimum font size in the system is 11.5px (caption); never go below it. |
| `--ds-fs-num-lg` | `30px` | Number font size for highlighted totals such as a balance (30px, line 36px, mono medium). Use with tabular-nums. Minimum font size in the system is 11.5px (caption); never go below it. |
| `--ds-fs-icon` | `20px` | Font size of text glyphs inside icon-only buttons (for example the multiplication sign and chevrons), 20px. Not for SVG icons; use size.icon-*. |
| `--ds-lh-display` | `40px` | Line height for fs.display (40px). |
| `--ds-lh-title` | `30px` | Line height for fs.title (30px). |
| `--ds-lh-heading` | `24px` | Line height for fs.heading (24px). |
| `--ds-lh-body` | `24px` | Line height for fs.body (24px, ratio 1.6). |
| `--ds-lh-small` | `22px` | Line height for fs.small (22px). |
| `--ds-lh-label` | `18px` | Line height for fs.label (18px). |
| `--ds-lh-meta` | `16px` | Line height for fs.meta (16px). |
| `--ds-lh-caption` | `16px` | Line height for fs.caption (16px). |
| `--ds-lh-num` | `32px` | Line height for fs.num (32px). |
| `--ds-lh-num-lg` | `36px` | Line height for fs.num-lg (36px). |
| `--ds-tracking-display` | `-0.68px` | Letter spacing for display: -2% of 34px = -0.68px. DTCG dimensions have no em unit, so the exact px equivalent is stored. Use only with fs.display. |
| `--ds-tracking-title` | `-0.22px` | Letter spacing for title: -1% of 22px = -0.22px. Use only with fs.title. |
| `--ds-tracking-caption` | `0.92px` | Letter spacing for caption: +8% of 11.5px = 0.92px. Use only with fs.caption and uppercase. |
| `typography.display` | `{"fontFamily":"Geist, \"Geist Fallback\", system-ui, sans...` | Display role: 34/40, semibold, -2% tracking. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `typography.title` | `{"fontFamily":"Geist, \"Geist Fallback\", system-ui, sans...` | Title role: 22/30, semibold, -1% tracking. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `typography.heading` | `{"fontFamily":"Geist, \"Geist Fallback\", system-ui, sans...` | Heading role: 17/24, semibold. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `typography.body` | `{"fontFamily":"Geist, \"Geist Fallback\", system-ui, sans...` | Body role: 15/24, regular. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `typography.small` | `{"fontFamily":"Geist, \"Geist Fallback\", system-ui, sans...` | Small role: 14/22, regular. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `typography.label` | `{"fontFamily":"Geist, \"Geist Fallback\", system-ui, sans...` | Label role: 13/18, medium. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `typography.meta` | `{"fontFamily":"\"Geist Mono\", \"Geist Mono Fallback\", u...` | Meta role: 12/16, mono regular. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `typography.caption` | `{"fontFamily":"\"Geist Mono\", \"Geist Mono Fallback\", u...` | Caption role: 11.5/16, mono medium, uppercase (text-transform applied in CSS), +8% tracking. Floor of the scale. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `typography.num` | `{"fontFamily":"\"Geist Mono\", \"Geist Mono Fallback\", u...` | Indicator number role: 24/32, mono medium, tabular-nums. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `typography.num-lg` | `{"fontFamily":"\"Geist Mono\", \"Geist Mono Fallback\", u...` | Highlight number role: 30/36, mono medium, tabular-nums. Composite for documentation and design tools; CSS uses the individual fs, lh and weight variables. |
| `--ds-space-1` | `4px` | Space step 1 (4px): the grid unit. Icon-to-text gaps and tight padding. |
| `--ds-space-2` | `8px` | Space step 2 (8px). Default gap between related elements inside a component. |
| `--ds-space-3` | `12px` | Space step 3 (12px). Compact padding and form field gaps. |
| `--ds-space-4` | `16px` | Space step 4 (16px). Standard padding and gap between components. |
| `--ds-space-5` | `20px` | Space step 5 (20px). Card padding. |
| `--ds-space-6` | `24px` | Space step 6 (24px). Gap between sections inside a page. |
| `--ds-space-8` | `32px` | Space step 8 (32px). Large section separation. |
| `--ds-space-12` | `48px` | Space step 12 (48px). Page-level separation. |
| `--ds-space-16` | `64px` | Space step 16 (64px). Largest spacing; hero and empty-state breathing room. |
| `--ds-control-h-sm` | `32px` | Height of small controls (32px). Dense toolbars. Must still meet the 24px minimum target (size.target-min). |
| `--ds-control-h-md` | `40px` | Height of default controls (40px): buttons, inputs, selects. The handoff --control-h. |
| `--ds-control-h-lg` | `48px` | Height of large controls (48px): primary actions and touch-first forms. |
| `--ds-item-h` | `36px` | Height of menu items, navigation items and listbox options (36px). |
| `--ds-row-h` | `52px` | Height of table and list rows (52px). |
| `--ds-row-h-dense` | `60px` | Height of dense rows with two lines of content (60px). Taller than row-h because it holds more content. |
| `--ds-sidebar-w` | `240px` | Width of the app sidebar (240px). |
| `--ds-topbar-h` | `64px` | Height of the top bar (64px). |
| `--ds-icon-xs` | `12px` | Icon size extra small (12px): inline status glyphs, chevrons in chips. |
| `--ds-icon-sm` | `14px` | Icon size small (14px): icons inside dense controls. |
| `--ds-icon-md` | `18px` | Icon size medium (18px): default icon beside text and in nav items. |
| `--ds-icon-lg` | `20px` | Icon size large (20px): icon-only buttons and empty states. |
| `--ds-target-min` | `24px` | Minimum interactive target size (24px, WCAG 2.5.8). No interactive element may be smaller in either dimension. |
| `--ds-radius-sm` | `4px` | Small radius (4px): chips, menu items, checkboxes. |
| `--ds-radius-md` | `6px` | Medium radius (6px): buttons and inputs. The handoff --radius. |
| `--ds-radius-lg` | `10px` | Large radius (10px): cards, menus, popovers, dialogs. |
| `--ds-radius-pill` | `999px` | Pill radius (999px): badges and switches. Any very large value renders fully round; do not use on large rectangles. |
| `--ds-shadow-overlay` | `0px 12px 32px 0px rgba(0, 0, 0, 0.6)` | Shadow for floating overlays: menus, popovers, toasts. The only elevation besides dialog. Never on cards or inline elements. |
| `--ds-shadow-dialog` | `0px 24px 48px 0px rgba(0, 0, 0, 0.7)` | Shadow for dialogs and side sheets: the highest elevation. Never on inline elements. |
| `--ds-duration` | `150ms` | Standard transition duration (150ms): hover, focus and state changes. Only color, opacity and position. Neutralized under prefers-reduced-motion. |
| `--ds-duration-done` | `320ms` | Completion feedback duration (320ms): subtle check or fill when something is done. No confetti. |
| `--ds-duration-progress` | `300ms` | Duration of progress bar fill changes (300ms). Neutralized under prefers-reduced-motion. |
| `--ds-ease` | `cubic-bezier(0.2, 0, 0, 1)` | Standard easing, cubic-bezier(.2, 0, 0, 1): fast start, soft landing. Use with every transition. |
| `--ds-z-sheet` | `40` | Layer of side sheets. The scrim uses this value and the panel uses this value + 1 (calc). Below dialogs, because a dialog can open from a sheet. |
| `--ds-z-dialog` | `45` | Layer of dialogs and their overlay. Above sheets; below dropdowns and popovers so a select or menu opened inside a dialog renders on top of it. |
| `--ds-z-dropdown` | `50` | Layer of dropdowns, selects, comboboxes and date pickers. Above dialogs and sheets (they can open from inside one); below popovers. |
| `--ds-z-popover` | `55` | Layer of popovers and action menus. Above dropdowns, dialogs and sheets. |
| `--ds-z-toast` | `58` | Layer of toasts. Above every overlay so confirmations and Undo stay visible; below tooltips. |
| `--ds-z-tooltip` | `60` | Layer of tooltips. The highest layer in the system. Do not add layers above it. |
| `--ds-opacity-disabled` | `0.35` | Opacity of disabled controls. One value for every component (the handoff .4 and .45 are unified). Disabled elements are exempt from contrast rules. Not for decorative fading. |
| `--ds-accordion-padding-inline` | `12px` | Horizontal padding of an Accordion header and panel (12px). |
| `--ds-add-card-min-block-size` | `64px` | Minimum height of an AddCard (64px), so a lone tile keeps a comfortable target. |
| `--ds-add-card-gap` | `8px` | Gap between the plus icon and the label of an AddCard (8px). |
| `--ds-agent-card-min-height` | `196px` | Minimum height of an AgentCard (196px), so cards in a grid line up. |
| `--ds-agent-card-padding` | `20px` | Inner padding of an AgentCard (20px). |
| `--ds-agent-card-gap` | `12px` | Vertical gap between the header, description and footer (12px). |
| `--ds-agent-card-icon-box-size` | `40px` | Side of the square that frames the agent icon (40px). |
| `--ds-alert-success-bg` | `rgba(95, 212, 154, 0.06)` | Background of a success Alert: 6% success over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-alert-success-border` | `rgba(95, 212, 154, 0.3)` | Border of a success Alert: 30% success over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-alert-warning-bg` | `rgba(233, 182, 92, 0.06)` | Background of a warning Alert: 6% warning over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-alert-warning-border` | `rgba(233, 182, 92, 0.3)` | Border of a warning Alert: 30% warning over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-alert-danger-bg` | `rgba(240, 122, 110, 0.06)` | Background of a danger Alert: 6% danger over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-alert-danger-border` | `rgba(240, 122, 110, 0.3)` | Border of a danger Alert: 30% danger over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-app-shell-detail-w` | `360px` | Width of the optional detail aside of AppShell (360px). |
| `--ds-app-shell-main-padding` | `24px` | Padding around the main content of AppShell (24px). |
| `--ds-app-shell-nav-z-index` | `40` | Layer of the off-canvas navigation panel and its scrim below the md breakpoint. Same layer as Sheet, so a Dialog opened from the panel stacks above it. |
| `--ds-approval-card-padding` | `20px` | Horizontal padding of the header and body of an ApprovalCard (20px). |
| `--ds-approval-card-header-min-height` | `48px` | Minimum height of the ApprovalCard header row (48px). |
| `--ds-approval-card-header-padding-block` | `12px` | Vertical padding of the header row (12px). |
| `--ds-approval-card-body-padding-block` | `16px` | Vertical padding of the body (16px). |
| `--ds-approval-card-gap` | `16px` | Gap between the message, the draft, the flag and the actions (16px). |
| `--ds-avatar-size-sm` | `24px` | Diameter of a small Avatar (24px). |
| `--ds-avatar-size-md` | `28px` | Diameter of the default Avatar (28px). |
| `--ds-avatar-size-lg` | `40px` | Diameter of a large Avatar (40px). |
| `--ds-avatar-ring-width` | `2px` | Width of the optional Avatar ring (2px) that separates stacked avatars from the surface. |
| `--ds-avatar-initials-ratio` | `0.4` | Initials font size as a share of the Avatar size (0.4). Keeps two letters inside the circle at every size. |
| `--ds-badge-height` | `24px` | Height of a Badge (24px). Badges are static labels, not targets. |
| `--ds-badge-dot-size` | `6px` | Diameter of the decorative status dot inside a Badge (6px). Never the only carrier of meaning. |
| `--ds-badge-padding-inline` | `8px` | Horizontal padding of a Badge (8px). |
| `--ds-banner-success-bg` | `rgba(95, 212, 154, 0.06)` | Background of a success Banner: 6% success over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-banner-success-border` | `rgba(95, 212, 154, 0.3)` | Border of a success Banner: 30% success over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-banner-warning-bg` | `rgba(233, 182, 92, 0.06)` | Background of a warning Banner: 6% warning over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-banner-warning-border` | `rgba(233, 182, 92, 0.3)` | Border of a warning Banner: 30% warning over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-banner-danger-bg` | `rgba(240, 122, 110, 0.06)` | Background of a danger Banner: 6% danger over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-banner-danger-border` | `rgba(240, 122, 110, 0.3)` | Border of a danger Banner: 30% danger over the surface beneath, resolved with color-mix. Not for text. |
| `--ds-banner-content-basis` | `240px` | Preferred inline size of the text of a Banner (240px). When the text and the action do not fit on one line, the action wraps below the text. |
| `--ds-breakpoint-sm` | `480px` | Small breakpoint (480px). Large phones. Components work from 320px; nothing in the DS changes layout at this width, it is a reference for consumer apps. |
| `--ds-breakpoint-md` | `768px` | Medium breakpoint (768px). AppShell shows the sidebar in the flow from this width up (measured on the shell's own width, with a container query) and turns it into an off-canvas panel below. CSS cannot read custom properties inside @media or @container conditions, so the CSS Module repeats this value; AppShell.test.tsx asserts they agree. |
| `--ds-breakpoint-lg` | `1024px` | Large breakpoint (1024px). Tablets in landscape and small laptops. A reference for consumer apps (for example to show a detail pane beside a list). |
| `--ds-breakpoint-xl` | `1280px` | Extra-large breakpoint (1280px). Desktop. The handoff prototype assumed 1180px minimum; the DS itself guarantees nothing above md. |
| `--ds-button-hover-brightness` | `0.88` | Brightness filter of the primary Button on hover (0.88): ink on dark gets slightly dimmer instead of changing color. Not for other variants or other components. |
| `--ds-button-pending-label-opacity` | `0.65` | Opacity of the Button label while isPending (0.65): the label stays readable next to the spinner but reads as busy. Busy state only, not for disabled. |
| `--ds-button-danger-solid-hover-brightness` | `0.9` | Brightness filter of the danger-solid Button on hover (0.9). Use only for the confirm action of a destructive dialog. |
| `--ds-calendar-cell-size` | `36px` | Width and height of a Calendar day cell (36px). A month grid is seven cells wide. |
| `--ds-calendar-weekday-height` | `24px` | Height of the weekday header row of a Calendar (24px). |
| `--ds-calendar-today-ring-width` | `1px` | Border width of the ring that marks today in a Calendar (1px). |
| `--ds-card-link-gap` | `12px` | Gap between the leading node and the text of a CardLink (12px). |
| `--ds-card-link-text-gap` | `4px` | Vertical gap between the title, description and meta of a CardLink (4px). |
| `--ds-card-padding` | `20px` | Inner padding of a Card (20px). |
| `--ds-card-gap` | `16px` | Vertical gap between the header and the content of a Card (16px). |
| `--ds-chart-series-1` | `#EDEDEA` | Series 1 of a multi-series chart (StackedBar) and its Legend swatch: the neutral ramp's first step. Series never use the accent or signal colors by default; pass an explicit color instead. |
| `--ds-chart-series-2` | `#A3A3A9` | Series 2 of a multi-series chart and its Legend swatch. |
| `--ds-chart-series-3` | `#86868E` | Series 3 of a multi-series chart and its Legend swatch. |
| `--ds-chart-series-4` | `#64646B` | Series 4 of a multi-series chart and its Legend swatch. Every step keeps 3:1 against the track background. |
| `--ds-chart-series-hatch-size` | `3px` | Stripe width of the hatch pattern that tells apart series beyond the fourth (3px). The pattern is the non-color cue. |
| `--ds-chart-height` | `200px` | Default height of a Chart (200px). The height prop overrides it per instance. |
| `--ds-chart-stroke-w` | `1.5px` | Stroke width of the line series and of point rings (1.5px, same as icons). |
| `--ds-chart-point-r` | `3.5px` | Radius of the active point marker of a line Chart (3.5px). |
| `--ds-chart-bar-radius` | `4px` | Corner radius of a bar (4px). |
| `--ds-chart-grid-dash` | `2px` | Dash length of the grid lines of a Chart (2px). |
| `--ds-chart-grid-gap` | `3px` | Gap between dashes of the grid lines of a Chart (3px). |
| `--ds-chart-area-opacity` | `0.08` | Opacity of the area under the line of a line Chart (0.08). |
| `--ds-chart-outline-w` | `2px` | Outline width of a highlighted bar (2px). Together with the label it is the non-color cue of a highlight. |
| `--ds-chart-tooltip-padding-inline` | `8px` | Horizontal padding of the value label of the active Chart point (8px). |
| `--ds-chart-tooltip-padding-block` | `4px` | Vertical padding of the value label of the active Chart point (4px). |
| `--ds-chart-ref-w` | `1px` | Stroke width of a reference line (average or target) in a Chart (1px). |
| `--ds-chart-ref-average-dash` | `6px` | Dash length of an average reference line (6px). Long dashes tell it apart from the target line without color. |
| `--ds-chart-ref-average-gap` | `4px` | Gap between dashes of an average reference line (4px). |
| `--ds-chart-ref-target-dash` | `10px` | Dash length of a target reference line (10px). Dash, gap, dot, gap: tells it apart from the average line without color. |
| `--ds-chart-ref-target-dot` | `2px` | Dot length of a target reference line (2px), between its dashes. |
| `--ds-chart-ref-target-gap` | `3px` | Gap around the dot and between dashes of a target reference line (3px). |
| `--ds-chart-tooltip-max-w` | `240px` | Widest the active-point label grows before a long note wraps (240px). Keep in sync with chartLayout.ts. |
| `--ds-chart-color` | `#8AB4FF` | Series color of a Chart. Each tone class sets it; it can be overridden at runtime via style (ADR-0002 amendment). |
| `--ds-chart-tooltip-x` | `0px` | Horizontal position of the active-point label, in px from the chart's left edge. Set at runtime via style. |
| `--ds-chart-tooltip-y` | `0px` | Vertical position of the active-point label, in px from the chart's top edge. Set at runtime via style. |
| `--ds-chat-panel-header-height` | `56px` | Height of the ChatPanel header (56px). |
| `--ds-chat-panel-padding-inline` | `20px` | Horizontal padding of the header and the message list (20px). |
| `--ds-chat-panel-padding-block` | `16px` | Vertical padding of the message list (16px). |
| `--ds-chat-panel-gap` | `12px` | Gap between messages (12px). |
| `--ds-chat-panel-bubble-max-ratio` | `0.88` | Maximum width of a message bubble as a share of the list width (0.88). |
| `--ds-chat-panel-composer-padding` | `16px` | Padding of the composer area (16px). |
| `--ds-checkbox-box-size` | `18px` | Width and height of the Checkbox box (18px). The 24px minimum target (WCAG 2.5.8) is met by the clickable label row, not the box. |
| `--ds-checkbox-radius` | `5px` | Corner radius of the Checkbox box (5px, the handoff value; between radius.sm and radius.md). Not for other controls. |
| `--ds-choice-tiles-min-width` | `120px` | Minimum tile width. Columns collapse so a tile never gets narrower than this (responsive columns). |
| `--ds-choice-tiles-gap` | `8px` | Gap between tiles (8px). |
| `--ds-choice-tiles-height-md` | `40px` | Minimum height of a medium tile (40px). |
| `--ds-choice-tiles-height-lg` | `48px` | Minimum height of a large tile (48px, default). |
| `--ds-choice-tiles-columns` | `2` | Maximum number of columns of ChoiceTiles. Default 2; the component sets it inline from its `columns` prop, and the grid collapses on narrow containers. |
| `--ds-citation-size` | `24px` | Minimum side of an inline citation marker (24px, the WCAG 2.5.8 target size). |
| `--ds-code-inline-padding-block` | `1px` | Vertical padding of inline Code (1px) so the box fits the line height of the surrounding text. |
| `--ds-color-option-group-min-width` | `140px` | Minimum option width. Columns collapse so an option never gets narrower than this (responsive columns). |
| `--ds-color-option-group-gap` | `8px` | Gap between options (8px). |
| `--ds-color-option-group-columns` | `2` | Maximum number of columns of ColorOptionGroup. Default 2; the component sets it inline from its `columns` prop, and the grid collapses on narrow containers. |
| `--ds-combobox-popover-max-height` | `320px` | Maximum height of the Combobox list before it scrolls (same as the Select list). |
| `--ds-command-palette-width` | `640px` | Maximum width of the CommandPalette panel (640px). Narrower on small screens. |
| `--ds-command-palette-list-max-height` | `360px` | Maximum height of the CommandPalette command list before it scrolls (360px, about 9 rows at item-h). |
| `--ds-command-palette-offset-top` | `96px` | Distance between the top of the viewport and the CommandPalette panel (96px). The panel hangs from the top so it does not jump while the list shrinks. |
| `--ds-container-sm` | `640px` | Maximum inline size of a small Container (640px): a single column form or a narrow article. |
| `--ds-container-md` | `960px` | Maximum inline size of a medium Container (960px): the default for settings pages and detail views. |
| `--ds-container-lg` | `1200px` | Maximum inline size of a large Container (1200px): dashboards and tables. |
| `--ds-content-max` | `1200px` | Default maximum inline size of page content (1200px). Container uses it when no size is given. |
| `--ds-content-gutter` | `24px` | Inline padding of page content, and of Container (24px). It keeps content off the viewport edge on narrow screens. |
| `--ds-data-table-selection-col-w` | `40px` | Width of the selection checkbox column of a DataTable (40px). |
| `--ds-data-table-cell-padding-inline` | `12px` | Horizontal padding of DataTable header and body cells (12px). |
| `--ds-data-table-header-padding-block` | `8px` | Vertical padding of DataTable header cells (8px). |
| `--ds-data-table-active-bar-w` | `2px` | Width of the ink bar on the inline-start edge of the active (or selected) DataTable row (2px). |
| `--ds-data-table-bulk-bar-h` | `36px` | Height of the bulk action bar shown above a DataTable while rows are selected (36px). |
| `--ds-data-table-gap` | `12px` | Gap between the bulk bar, the table and the pagination of a DataTable (12px). |
| `--ds-data-table-sticky-z-index` | `1` | Stacking order of a sticky DataTable header inside its scroll container (1). Local to the table, not a layer. |
| `--ds-data-table-col-w` | `160px` | Width of a DataTable column that has a `width` prop (default 160px). Set at runtime via style on that column header; columns without `width` share the remaining space. |
| `--ds-data-table-col-min-w` | `0px` | Minimum width of a DataTable column that has `width` and `minWidth` props (default 0px, no minimum). Set at runtime via style on that column header; the column is as wide as the larger of `width` and `minWidth`. |
| `--ds-data-table-min-w` | `0px` | Minimum width of the DataTable table element (default 0px, no minimum). Set at runtime via style when any column has a `minWidth`: the sum of every column's own minimum. A narrower container then scrolls horizontally. |
| `--ds-data-table-flex-count` | `1` | Number of flexible DataTable columns (no `width`), which share the space left after every column minimum. Set at runtime via style on the table when any column has a `minWidth`; default 1. |
| `--ds-data-table-max-h` | `480px` | Maximum height of a scrollable DataTable (default 480px). Set at runtime via style from the `maxHeight` prop. |
| `--ds-dialog-width-sm` | `420px` | Maximum width of a small Dialog (420px): confirmations and short forms. The handoff default. |
| `--ds-dialog-width-md` | `540px` | Maximum width of a medium Dialog (540px): forms with several fields. |
| `--ds-dialog-width-lg` | `680px` | Maximum width of a large Dialog (680px): dialogs with a table or a preview. |
| `--ds-dialog-gutter` | `24px` | Minimum distance between a Dialog and the viewport edge (24px). |
| `--ds-dialog-padding` | `20px` | Inner padding of the Dialog header, body and footer (20px, the card padding). |
| `--ds-donut-meter-size-sm` | `48px` | Diameter of a small DonutMeter (48px). |
| `--ds-donut-meter-size-md` | `72px` | Diameter of a medium DonutMeter (72px). |
| `--ds-donut-meter-size-lg` | `96px` | Diameter of a large DonutMeter (96px). |
| `--ds-donut-meter-stroke-w` | `10px` | Thickness of the ring in units of the 100-unit drawing box (10), so it scales with the diameter: 4.8px at 48px, 9.6px at 96px. |
| `--ds-donut-meter-value` | `0` | Filled share of the ring, 0 to 100. Set at runtime via style (ADR-0002 amendment); the ring is drawn with a dash of this length on a path of length 100. |
| `--ds-donut-meter-color` | `#8AB4FF` | Color of the filled part of the ring. Each tone sets it. |
| `--ds-drawer-width-sm` | `280px` | Width of a small Drawer (280px): a narrow filter or navigation panel. |
| `--ds-drawer-width-md` | `320px` | Width of a medium Drawer (320px), the default. |
| `--ds-drawer-width-lg` | `400px` | Width of a large Drawer (400px): an inspector with forms. |
| `--ds-drawer-padding` | `16px` | Inner padding of the Drawer header, body and footer (16px). |
| `--ds-drawer-shift` | `16px` | Distance the Drawer slides while it fades in (16px). |
| `--ds-drawer-width` | `320px` | Resolved width of the Drawer. The size attribute sets it from `--ds-drawer-width-sm\|md\|lg`; not meant to be set by consumers. |
| `--ds-drawer-from` | `16px` | Start offset of the Drawer fade-in. The placement and writing direction set its sign; not meant to be set by consumers. |
| `--ds-due-indicator-dot-size` | `8px` | Diameter of the tone dot before the date (8px). Decorative: the status is always text. |
| `--ds-due-indicator-gap` | `8px` | Gap between the dot, the date and the status text (8px). |
| `--ds-empty-state-padding-block` | `48px` | Vertical padding of an EmptyState (48px). |
| `--ds-empty-state-padding-inline` | `24px` | Horizontal padding of an EmptyState (24px). |
| `--ds-empty-state-compact-padding-block` | `24px` | Vertical padding of a compact EmptyState (24px). |
| `--ds-empty-state-compact-padding-inline` | `20px` | Horizontal padding of a compact EmptyState (20px). |
| `--ds-empty-state-description-max-w` | `360px` | Maximum width of the EmptyState description (360px), to keep lines short. |
| `--ds-field-set-gap` | `12px` | Vertical gap between the legend, the description and the fields of a FieldSet (12px). |
| `--ds-field-gap` | `6px` | Vertical gap between label, control, description and error in every form field (6px, the handoff value; no 6px step exists in the space scale). Not for spacing between fields. |
| `--ds-field-control-padding-inline` | `10px` | Inline padding inside text-like control boxes (Input, Select trigger, Select option): 10px, the handoff value. Not for buttons. |
| `--ds-field-choice-gap` | `10px` | Gap between a Checkbox or Radio box and its label text (10px, the handoff value). Not for form layout. |
| `--ds-file-upload-dropzone-padding-block` | `20px` | Vertical padding of the FileUpload drop zone (20px, the handoff value). |
| `--ds-file-upload-dropzone-padding-inline` | `16px` | Horizontal padding of the FileUpload drop zone (16px). |
| `--ds-file-upload-item-padding-block` | `12px` | Vertical padding of a file row in the FileUpload list (12px). |
| `--ds-file-upload-item-padding-inline` | `12px` | Horizontal padding of a file row in the FileUpload list (12px). |
| `--ds-form-gap` | `20px` | Vertical gap between the fields and groups of a Form (20px). |
| `--ds-form-summary-padding` | `16px` | Padding of the form error summary (16px). |
| `--ds-form-summary-gap` | `8px` | Gap between the title and the list of the error summary, and between its items (8px). |
| `--ds-grid-min-item-sm` | `160px` | Minimum width of a Grid item at minItemWidth sm (160px): small tiles and stat numbers. |
| `--ds-grid-min-item-md` | `240px` | Minimum width of a Grid item at minItemWidth md (240px): cards. |
| `--ds-grid-min-item-lg` | `320px` | Minimum width of a Grid item at minItemWidth lg (320px): wide cards and previews. |
| `--ds-grid-gap` | `16px` | Default Grid gap; set at runtime via style from the `gap` prop (a space token key). |
| `--ds-grid-columns` | `1` | Default Grid column count; set at runtime via style from the `columns` prop. |
| `--ds-icon-stroke-width` | `1.5px` | Rendered stroke width of every Icon (1.5px). Applied with non-scaling strokes, so it stays 1.5px at every icon size. Not for filled or colored icons. |
| `--ds-inline-gap` | `8px` | Default Inline gap; set at runtime via style from the `gap` prop (a space token key). |
| `--ds-kbd-height` | `18px` | Height of a Kbd keycap (18px). Inline hint, not a target. |
| `--ds-kbd-padding-inline` | `4px` | Horizontal padding of a Kbd keycap (4px). |
| `--ds-kbd-fg` | `#A3A3A9` | Text color of a Kbd keycap. Filled buttons (primary, danger-solid) override it for the Kbd inside, so the hint stays readable on their fill. |
| `--ds-kbd-border` | `#33333A` | Border color of a Kbd keycap. Overridden together with kbd-fg by filled buttons. |
| `--ds-ledger-list-date-width` | `64px` | Width of the date column (64px). |
| `--ds-ledger-list-gap` | `12px` | Gap between the columns of an entry (12px). |
| `--ds-ledger-list-padding-inline` | `24px` | Horizontal padding of an entry (24px). |
| `--ds-ledger-list-text-gap` | `2px` | Gap between the stacked lines of an entry (title and subtitle, amount and balance) (2px). |
| `--ds-legend-swatch-size` | `10px` | Size of the series swatch in a Legend (10px). |
| `--ds-legend-gap` | `16px` | Gap between the items of a horizontal Legend (16px). |
| `--ds-legend-share-col-w` | `48px` | Minimum width of the share column in a Legend with `showShare` (48px), so shares line up. |
| `--ds-legend-color` | `#EDEDEA` | Fill of a Legend swatch. The series ramp classes set it per step; an item `color` overrides it at runtime via style (ADR-0002 amendment). |
| `--ds-matrix-grid-cell-size` | `40px` | Width and height of a toggle cell (40px, above the 24px minimum target). |
| `--ds-matrix-grid-color` | `#A3A3A9` | Fill of a linked MatrixGrid cell. Defaults to secondary text; the component sets it inline from the column `color`. |
| `--ds-matrix-grid-column-header-padding-inline` | `2px` | Horizontal padding of a column header so neighboring labels do not touch (2px). |
| `--ds-matrix-grid-column-width` | `64px` | Width of a data column (64px). |
| `--ds-matrix-grid-columns` | `0` | Number of data columns of MatrixGrid. The component sets it inline from the `columns` prop. |
| `--ds-matrix-grid-count-width` | `64px` | Width of the optional count column (64px). |
| `--ds-matrix-grid-label-width` | `220px` | Width of the row header column (220px). |
| `--ds-matrix-grid-padding-inline` | `20px` | Horizontal padding of rows and the header (20px). |
| `--ds-matrix-grid-sticky-z-index` | `1` | Stacking order of the sticky MatrixGrid header row and row header column inside the scroll region (1; the corner adds 1). Local to the grid, not a layer. |
| `--ds-matrix-grid-row-header-gap` | `2px` | Gap between the label and the description of a row header (2px). |
| `--ds-matrix-grid-row-min-height` | `60px` | Minimum height of a row (60px). |
| `--ds-menu-min-width` | `200px` | Minimum width of a Menu (200px, the handoff default). |
| `--ds-menu-max-width` | `360px` | Maximum width of a Menu popover (360px). A longer label wraps instead of stretching the popover across the screen; it never goes below the trigger width. |
| `--ds-menu-indicator-size` | `18px` | Width reserved for the check or radio indicator of selectable Menu items (18px). |
| `--ds-nav-item-padding-inline` | `10px` | Horizontal padding of a NavItem (10px). |
| `--ds-nav-item-indicator-width` | `2px` | Width of the inset ink bar on the active NavItem (2px). |
| `--ds-nav-item-icon-opacity` | `0.7` | Opacity of the icon of an inactive NavItem (0.7). The active icon is fully opaque. |
| `--ds-nav-item-count-size` | `20px` | Minimum width and height of the count pill of a NavItem (20px). |
| `--ds-nav-item-count-padding-inline` | `6px` | Horizontal padding of the count pill of a NavItem (6px). |
| `--ds-number-field-value-min-width` | `56px` | Minimum width of the NumberField value box between the stepper buttons (56px, about four digits plus a suffix in mono). |
| `--ds-popover-min-width` | `180px` | Minimum width of a Popover (180px). |
| `--ds-popover-arrow-size` | `8px` | Width of the optional Popover arrow (8px); its height is half of this. |
| `--ds-popover-padding` | `12px` | Inner padding of a Popover with free content (12px). |
| `--ds-progress-height` | `4px` | Height of the Progress and Meter bar (4px). |
| `--ds-progress-indeterminate-width` | `40` | Width of the moving segment of an indeterminate Progress, in percent of the track (40). |
| `--ds-progress-indeterminate-duration` | `1400ms` | Duration of one sweep of an indeterminate Progress (1400ms). Static under prefers-reduced-motion. |
| `--ds-proportion-bar-height` | `10px` | Height of the ProportionBar track (10px). |
| `--ds-proportion-bar-segment-gap` | `2px` | Gap between segments of a ProportionBar (2px). The track shows through, so neighbours are always separated. |
| `--ds-proportion-bar-swatch-size` | `10px` | Size of a legend swatch of a ProportionBar (10px). |
| `--ds-proportion-bar-percent-col-w` | `48px` | Width of the percentage column in the ProportionBar legend (48px). |
| `--ds-proportion-bar-hatch-size` | `3px` | Stripe width of the hatch pattern that tells apart segments beyond the fourth (3px). |
| `--ds-proportion-bar-color` | `#EDEDEA` | Fill of a ProportionBar segment and its legend swatch. The neutral ramp classes set it per step; a segment `color` prop overrides it at runtime via style. |
| `--ds-proportion-bar-columns` | `2` | Number of legend columns after the label in a ProportionBar (share, value, count). Set at runtime via style from legendColumns. |
| `--ds-proportion-bar-share` | `1` | Relative size (flex-grow) of a ProportionBar segment. Set at runtime via style from the segment value. |
| `--ds-radio-size` | `18px` | Width and height of the Radio circle (18px). |
| `--ds-radio-dot-size` | `9px` | Diameter of the selected dot inside the Radio circle (9px). |
| `--ds-rank-list-bar-h` | `4px` | Height of the relative bar of a RankList row (4px). |
| `--ds-rank-list-position-w` | `24px` | Width of the position column of a RankList (24px). |
| `--ds-rank-list-padding-block` | `8px` | Vertical padding of a RankList row (8px). |
| `--ds-rank-list-padding-inline` | `20px` | Horizontal padding of a RankList row (20px, aligned with Card padding). |
| `--ds-rank-list-share` | `0px` | Width of the relative bar of a RankList row. Set at runtime via style as a percentage of the track (0 by default: an empty bar). |
| `--ds-rating-gap` | `8px` | Gap between the stars and the optional numeric value (8px). |
| `--ds-rating-star-gap` | `2px` | Gap between two stars (2px). |
| `--ds-rating-fill` | `0px` | Width of the filled part of a partially filled Rating star. Set at runtime via style as a percentage of the star (0 by default: an empty star). |
| `--ds-response-feedback-gap` | `4px` | Gap between the feedback, copy and regenerate buttons (4px). |
| `--ds-response-feedback-divider-gap` | `8px` | Space on each side of the divider between the rating and the other actions (8px). |
| `--ds-scroll-area-max-h` | `320px` | Maximum block size of a ScrollArea with the `maxBlockSize` prop. Set at runtime via style from that prop (a number is px); 320px is only the fallback value of the token. |
| `--ds-segmented-control-padding` | `2px` | Inner padding and gap of the SegmentedControl track (2px). |
| `--ds-segmented-control-height-sm` | `24px` | Height of a small segment (24px, the minimum target size). The handoff used 26px. |
| `--ds-segmented-control-height-md` | `32px` | Height of a medium segment (32px). |
| `--ds-select-popover-max-height` | `320px` | Maximum height of the Select list before it scrolls (320px, about 8 options at item-h). |
| `--ds-sheet-width-sm` | `440px` | Width of a small Sheet (440px): the handoff default side panel. |
| `--ds-sheet-width-md` | `460px` | Width of a medium Sheet (460px). |
| `--ds-sheet-width-lg` | `480px` | Width of a large Sheet (480px). |
| `--ds-sheet-padding` | `24px` | Inner padding of the Sheet body and footer (24px). |
| `--ds-sheet-from` | `0px` | Start offset of the Sheet slide-in animation. The placement classes set it (100% or -100%); not meant to be set by consumers. |
| `--ds-sheet-width` | `440px` | Resolved width of the Sheet. The size classes set it from `--ds-sheet-width-sm\|md\|lg`; not meant to be set by consumers. |
| `--ds-sidebar-padding-block` | `16px` | Vertical padding of the Sidebar (16px). |
| `--ds-sidebar-padding-inline` | `12px` | Horizontal padding of the Sidebar (12px). |
| `--ds-sidebar-gap` | `20px` | Gap between the blocks of the Sidebar: workspace, sections, footer (20px). |
| `--ds-sidebar-workspace-mark-size` | `28px` | Width and height of the initial tile of the workspace block (28px). |
| `--ds-sidebar-status-dot-size` | `8px` | Diameter of the decorative dot of the Sidebar status card (8px). The text carries the meaning. |
| `--ds-skeleton-height` | `12px` | Default height of a Skeleton block (12px), roughly one line of small text. |
| `--ds-skeleton-pulse-duration` | `1400ms` | Duration of one Skeleton pulse (1400ms). Switched off under prefers-reduced-motion. |
| `--ds-skeleton-pulse-opacity` | `0.45` | Lowest opacity of the Skeleton pulse (0.45). Opacity is the only animated property. |
| `--ds-skip-link-z-index` | `60` | Layer of a focused SkipLink: above everything, because it is the first stop for keyboard users. |
| `--ds-slider-track-height` | `4px` | Thickness of the Slider track and fill (4px, the handoff value). |
| `--ds-slider-thumb-size` | `24px` | Width and height of the Slider thumb hit area (24px, WCAG 2.5.8). The visible knob is thumb-dot-size; the ring on focus follows this box. |
| `--ds-slider-thumb-dot-size` | `16px` | Diameter of the visible Slider knob (16px), centered in the thumb hit area. |
| `--ds-source-list-gap` | `12px` | Gap between the sources of a SourceList (12px). |
| `--ds-source-list-indent` | `24px` | Inline start padding of the numbered list, where the numbers sit (24px). |
| `--ds-source-list-padding` | `8px` | Padding of one source, so its focus outline does not touch the text (8px). |
| `--ds-sparkline-stroke-w` | `1.5px` | Stroke width of the Sparkline line and of its marker rings (1.5px, same as icons and Chart). |
| `--ds-sparkline-dot-r` | `2.5px` | Radius of the solid last-value dot of a Sparkline (2.5px). |
| `--ds-sparkline-marker-r` | `2px` | Radius of the hollow minimum and maximum markers of a Sparkline (2px). |
| `--ds-sparkline-area-opacity` | `0.12` | Opacity of the area under the line of an area Sparkline (0.12). |
| `--ds-sparkline-color` | `#A3A3A9` | Series color of a Sparkline. Each tone sets it (neutral by default). |
| `--ds-spinner-stroke-width` | `2px` | Ring thickness of the Spinner (2px) at every size. Not for progress bars or icon strokes. |
| `--ds-spinner-duration` | `700ms` | Time of one full Spinner rotation (700ms). Replaced by a static ring under prefers-reduced-motion. Not for transitions. |
| `--ds-split-layout-aside-w-sm` | `280px` | Width of the SplitLayout aside at asideWidth sm (280px): a short filter or summary panel. |
| `--ds-split-layout-aside-w-md` | `360px` | Width of the SplitLayout aside at asideWidth md (360px). Same value as the AppShell detail pane, so a side panel looks the same in both. |
| `--ds-split-layout-aside-w-lg` | `480px` | Width of the SplitLayout aside at asideWidth lg (480px): a chat or an editor beside a list. |
| `--ds-split-layout-gap` | `24px` | Default gap between the main content and the aside (24px); set at runtime via style from the `gap` prop (a space token key). |
| `--ds-split-layout-sticky-offset` | `16px` | Distance (16px) between the top of the scrolling area and a sticky aside, and the room kept below it. |
| `--ds-stack-gap` | `16px` | Default Stack gap; set at runtime via style from the `gap` prop (a space token key). |
| `--ds-stacked-bar-bar-thickness` | `20px` | Thickness of a horizontal StackedBar bar (20px). |
| `--ds-stacked-bar-column-max-w` | `56px` | Maximum width of a vertical StackedBar column (56px). |
| `--ds-stacked-bar-height` | `200px` | Height of the plot area of a vertical StackedBar (200px). |
| `--ds-stacked-bar-category-w` | `96px` | Width of the category label column of a horizontal StackedBar (96px). Longer labels are truncated; the readout and the data table carry the full text. |
| `--ds-stacked-bar-segment-gap` | `2px` | Gap between the segments of a StackedBar bar (2px). The track shows through, so neighbouring series are always separated without relying on color. |
| `--ds-stacked-bar-readout-min-h` | `24px` | Reserved height of the readout line under a StackedBar (24px), so showing it never shifts the layout. |
| `--ds-stacked-bar-extent` | `100` | Length of a StackedBar bar as a percentage of the plot (the largest total is 100). Set at runtime via style. |
| `--ds-stacked-bar-share` | `1` | Relative size (flex-grow) of a StackedBar segment. Set at runtime via style from the series value. |
| `--ds-stacked-bar-color` | `#EDEDEA` | Fill of a StackedBar segment. The series ramp classes set it per step; a series `color` overrides it at runtime via style. |
| `--ds-stat-card-padding` | `20px` | Padding of a StatCard (20px, same as Card). |
| `--ds-stat-card-gap` | `8px` | Vertical gap between the label, value, content and note of a StatCard (8px). |
| `--ds-status-steps-connector-thickness` | `2px` | Thickness of the decorative line between two steps (2px). |
| `--ds-status-steps-content-z-index` | `1` | Stacking order of a step above the connector lines of its neighbours (1). Local to the list, not a layer. |
| `--ds-status-steps-gap` | `8px` | Gap between the marker and the label (8px). |
| `--ds-status-steps-marker-border-width` | `1.5px` | Border width of a pending step marker (1.5px), matching the 1.5px icon stroke. |
| `--ds-status-steps-marker-hover-border` | `#86868E` | Border of the marker of a step that is hovered in an interactive list. line-control is only 2.8:1 on surface-hover, so the border brightens to text-3 (4.5:1 there) to keep the 3:1 boundary of WCAG 1.4.11 (TOK-014). |
| `--ds-status-steps-marker-size` | `20px` | Diameter of the numbered or checked marker of a step (20px). |
| `--ds-status-steps-padding-block` | `4px` | Vertical padding of a step (4px). |
| `--ds-stepper-connector-thickness` | `2px` | Thickness of the decorative line between two steps (2px). |
| `--ds-stepper-content-z-index` | `1` | Stacking order of a step above the connector lines of its neighbours (1). Local to the list, not a layer. |
| `--ds-stepper-gap` | `8px` | Gap between the marker and the label, or between the label and the description (8px). |
| `--ds-stepper-marker-border-width` | `1.5px` | Border width of an upcoming step marker (1.5px), matching the 1.5px icon stroke. |
| `--ds-stepper-marker-size` | `24px` | Diameter of the numbered or checked marker of a step (24px). Also the minimum target size of a step button (WCAG 2.5.8). |
| `--ds-stepper-padding-block` | `4px` | Vertical padding of a step (4px). |
| `--ds-stepper-step-gap` | `16px` | Space below a step in the vertical orientation, where the connector line runs (16px). |
| `--ds-swatch-size-sm` | `16px` | Diameter of a small Swatch (16px), used inside options and headers. |
| `--ds-swatch-size-md` | `20px` | Diameter of a medium Swatch (20px, default). |
| `--ds-swatch-size-lg` | `32px` | Diameter of a large Swatch (32px). |
| `--ds-swatch-color` | `rgba(0, 0, 0, 0)` | Fill of a Swatch. Transparent by default; the component sets it inline from its `color` prop (ADR-0002 amendment). Do not override it in CSS. |
| `--ds-switch-track-width` | `36px` | Width of the Switch track (36px). |
| `--ds-switch-track-height` | `20px` | Height of the Switch track (20px). |
| `--ds-switch-knob-size` | `16px` | Diameter of the Switch knob (16px). |
| `--ds-switch-knob-offset` | `2px` | Gap between the knob and the track edge (2px). The knob travels track-width minus knob-size minus twice this value. |
| `--ds-tabs-gap` | `20px` | Gap between tabs in a horizontal tab list (20px). |
| `--ds-tabs-divider-width` | `1px` | Thickness of the line under the tab list (1px). The tabs are one divider shorter so the list never overflows vertically. |
| `--ds-tabs-indicator-height` | `2px` | Thickness of the active-tab underline (2px, ink colored). |
| `--ds-tabs-count-size` | `20px` | Minimum width and height of the count pill inside a Tab (20px). A label, not a target. |
| `--ds-tabs-count-padding-inline` | `6px` | Horizontal padding of the count pill inside a Tab (6px). |
| `--ds-tag-input-padding-block` | `3px` | Vertical padding inside the TagInput box (3px): one row of tags plus border is exactly the small control height (32px). The box is at least as tall as the control height of its size, and grows when tags wrap. |
| `--ds-tag-input-padding-inline` | `10px` | Horizontal padding inside the TagInput box (10px), the same as other text fields. |
| `--ds-tag-input-gap` | `4px` | Gap between tags, and between the last tag and the text input (4px). |
| `--ds-tag-input-input-min-width` | `96px` | Minimum width of the text input. When less room is left on the line, the input wraps to the next one (96px). |
| `--ds-tag-height` | `24px` | Height of a Tag (24px): meets the minimum target size of its remove button. |
| `--ds-tag-remove-size` | `24px` | Width and height of the remove button inside a Tag (24px, WCAG 2.5.8). |
| `--ds-tag-padding-inline` | `8px` | Horizontal padding of a Tag (8px). |
| `--ds-textarea-padding-block` | `10px` | Block padding inside a Textarea (10px, the handoff value). Not for single-line controls. |
| `--ds-textarea-padding-inline` | `12px` | Inline padding inside a Textarea (12px, the handoff value). Not for single-line controls. |
| `--ds-timeline-connector-thickness` | `2px` | Thickness of the decorative line that joins the markers of two events (2px). |
| `--ds-timeline-dot-size` | `8px` | Diameter of the dot that marks a neutral event (8px). |
| `--ds-timeline-item-gap` | `20px` | Space between two events, where the connector line runs (20px). |
| `--ds-timeline-marker-gap` | `12px` | Gap between the marker column and the text of an event (12px). |
| `--ds-timeline-marker-size` | `20px` | Width and height of the marker slot that holds the dot or the tone icon (20px). |
| `--ds-toast-max-width` | `420px` | Maximum width of a Toast (420px). It shrinks to the viewport on narrow screens. |
| `--ds-toast-min-height` | `40px` | Minimum height of a Toast (40px). |
| `--ds-toast-dot-size` | `6px` | Diameter of the tone dot of a Toast (6px). Decorative: the tone is also spoken. |
| `--ds-toast-offset` | `24px` | Distance between the Toast region and the bottom edge of the viewport (24px). |
| `--ds-toast-clearance` | `0px` | Height of viewport the Toast region covers at the bottom (0 when no toast is shown). ToastRegion sets it on the root element while mounted; scroll containers use it as scroll-padding-block-end so focus never scrolls under a toast (WCAG 2.4.11). Do not set it by hand. |
| `--ds-tool-call-step-padding-inline` | `12px` | Horizontal padding of the ToolCallStep header and details (12px). |
| `--ds-tool-call-step-padding-block` | `8px` | Vertical padding of the ToolCallStep header (8px). |
| `--ds-tool-call-step-gap` | `8px` | Gap between the status, name and duration, and between detail blocks (8px). |
| `--ds-tool-call-step-list-gap` | `8px` | Gap between the steps of a ToolCallList (8px). |
| `--ds-tooltip-max-width` | `240px` | Maximum width of a Tooltip (240px) before the text wraps. Tooltips stay short. |
| `--ds-top-bar-padding-inline` | `24px` | Horizontal padding of the TopBar (24px). Its height is size.topbar-h (64px; the handoff code used 56px). |
| `--ds-tour-width` | `320px` | Width of a Tour step (320px); it shrinks to fit narrow viewports. |
| `--ds-tour-padding` | `16px` | Inner padding of a Tour step (16px). |
| `--ds-tour-arrow-size` | `8px` | Width of the Tour arrow (8px); its height is half of this. |

### Pairings that fail contrast

- `--ds-line-control` fails 3:1 on color.surface-hover (2.8:1).

---

## Components

### Accordion

> A stack of sections that expand and collapse. Each header is a heading that wraps a real
button (`aria-expanded`, `aria-controls`), so it appears in the page outline and works with
`Enter` and `Space`. Built on React Aria `DisclosureGroup`.

Use it to shorten a long page of related, optional content (FAQs, settings groups). Do not
hide content people need to finish their task.

A stack of sections that expand and collapse. Each header is a heading that wraps a real button. Built on React Aria `DisclosureGroup`, `Disclosure` and `DisclosurePanel`.

- Handoff source: `components/layout/Accordion.jsx` (TODO `CMP-LAY-04`).

- Import: `import { Accordion } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Accordion/Accordion.tsx`
- Stories (Storybook title `Components/Accordion`): Default, Plain, InitiallyExpanded, KeyboardSingle, Multiple, DisabledItem, HeadingLevel2, Controlled, LongText, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly AccordionItem[]` | yes |  | The sections, in order. |
| `multiple` | `boolean` |  | `false` | Allow several sections open at once. By default opening one section closes the others (single expansion). |
| `value` | `readonly string[]` |  |  | Values of the expanded items (controlled). |
| `defaultValue` | `readonly string[]` |  | `[]` | Values of the items expanded at first (uncontrolled). |
| `onChange` | `(value: string[]) => void` |  |  | Called with the values of all expanded items after the user toggles one. |
| `variant` | `'bordered' \| 'plain'` |  | `'bordered'` | `bordered` (default) draws a card around the sections; `plain` only draws dividers. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` |  | `3` | Level of the heading that wraps each trigger, `3` by default. Use the level that follows the heading above the accordion in the page outline. |
| `isDisabled` | `boolean` |  | `false` | Disables every section. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the root element. |

##### Inherited props

- From `DOMProps` (@react-types/shared): `id`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `bordered`, `plain`

#### Design tokens used

`--ds-accent`, `--ds-accordion-padding-inline`, `--ds-duration`, `--ds-ease`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-small`, `--ds-icon-sm`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-subtle`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-row-h`, `--ds-space-3`, `--ds-space-4`, `--ds-surface`, `--ds-surface-row-hover`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- FAQs, grouped settings, long optional detail on a record.
- To shorten a page whose sections people read one at a time.

#### When not to use

- For content people must see to finish the task.
- For switching between views: use `Tabs`.
- For a single show/hide of one block: a plain disclosure is enough.

#### Accessibility

- Each header is `h3` (configurable) containing a `button` with `aria-expanded` and `aria-controls`; the panel is a `group` labelled by the button. Headings appear in the page outline and in screen reader heading lists.
- Keys: `Tab` moves between triggers; `Enter` and `Space` toggle. Optional arrow-key movement between headers (APG) is not added: each trigger is a tab stop.
- Collapsed panels are hidden (`hidden="until-found"`), so find-in-page can open them, and they take no space.
- The chevron rotates 180 degrees to show the state; the state itself is `aria-expanded`, not the icon. Under `prefers-reduced-motion` the rotation is instant.
- The focus indicator is an inset accent outline because the group clips overflow. Forced colors use `Highlight`.
- Disabled items are not focusable.
- Meta text is read after the title; keep it short.

#### Content rules

- Titles are short phrases or questions in sentence case, and say what is inside.
- Do not put the only copy of important information in a collapsed panel.

#### Examples

```tsx
<Accordion
  headingLevel={2}
  items={[
    { value: 'shipping', title: 'How long does shipping take?', content: 'Two to five days.' },
    { value: 'returns', title: 'Can I return an order?', meta: '30 days', content: '…' },
  ]}
/>

<Accordion multiple variant="plain" value={open} onChange={setOpen} items={items} />
```

#### Related components

- Instead, see Tabs: For switching between views: use `Tabs`.
- Renders: Icon

### ActionList

> A vertical list of records, each with a title, optional description, a mono meta value and a
"more actions" menu, with optional row checkboxes (`selectionMode="multiple"`). Built on React Aria `GridList`: rows are reached with the arrow keys
(one tab stop for the list), `Enter` runs `onAction`, and `Tab` or the right arrow moves
from a row to its menu button.

A vertical list of records. Each row has an optional leading node, a title, an optional description, a mono meta value and an optional "more actions" menu. Built on React Aria `GridList`, so rows are reachable with the arrow keys and can run an action.

- Import: `import { ActionList } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/ActionList/ActionList.tsx`
- Stories (Storybook title `Components/ActionList`): Default, Actionable, KeyboardNavigation, RowMenu, Borderless, WithLeadingAndLongText, DisabledRow, Empty, CustomEmpty, PortugueseBrazil, WithCheckboxes, CheckboxWithRowActionAndMenu, TaskRows, DoneRows, CheckboxesLongText, CheckboxesDisabledRow, ToggleWithUndo

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly ActionListItem[]` | yes |  | The rows, in the order given. The list never sorts: lists are alphabetical by default in this design system, so sort with `sortByText` before passing them (tasks by urgency and dated records newest first are the exceptions). |
| `className` | `string` |  |  | Class name for the list root. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the list root element. |
| `onAction` | `(item: ActionListItem) => void` |  |  | Called when the user activates a row (click, or Enter on the focused row). Makes the whole row a press target with hover and pointer cursor. The menu button does not trigger it. |
| `selectionMode` | `'none' \| 'multiple'` |  | `'none'` | Adds a checkbox at the start of every row. `'multiple'` toggles rows independently (the checkbox toggles, the row still runs `onAction`). Default `'none'`. |
| `selectedKeys` | `"all" \| Iterable<Key>` |  |  | Controlled selected row ids. Use together with `onSelectionChange`. |
| `defaultSelectedKeys` | `"all" \| Iterable<Key>` |  |  | Initially selected row ids (uncontrolled). |
| `onSelectionChange` | `(keys: Selection) => void` |  |  | Called when the checkbox of a row is toggled (click, or `Space` on the focused row or checkbox). The list never shows an Undo toast itself: update your state, then call `toastWithUndo` (reversible toggles never ask for confirmation). |
| `bordered` | `boolean` |  | `true` | Draws the border, surface and radius around the list. Turn off inside a `Card`. Default `true`. |
| `emptyState` | `ReactNode` |  |  | Content when `items` is empty. Default: an `EmptyState` with built-in text. |
| `messages` | `Partial<{ moreActions: (title: string) => string; select: string; done: string; emptyTitle: string; emptyDescription: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `aria-label` | `string` |  |  | Accessible name of the list. Required unless `aria-labelledby` is set. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the list (a visible heading). |

##### Inherited props

- From `AriaGridListProps` (react-aria): `escapeKeyBehavior`, `keyboardNavigationBehavior`
- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `DOMProps` (@react-types/shared): `id`
- From `GridListProps` (react-aria): `autoFocus`, `disabledBehavior`, `shouldSelectOnPressUp`
- From `GridListProps` (react-aria-components): `disallowTypeAhead`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ ActionList: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `moreActions(title: string)` | `More actions for {title}` | Accessible name of the row actions button. `title` is the text of the row ("More actions for Price list"). |
| `select` | `Select` | Start of the accessible name of a row checkbox. React Aria appends the text of the row ("Select" + "Price list 2026"), so keep it a bare verb. |
| `done` | `Done` | Visually hidden text added to a row marked `isDone`, read after the title. |
| `emptyTitle` | `No items found` | Title of the default empty state. |
| `emptyDescription` | `Try another filter or search term.` | Description of the default empty state. |

#### Design tokens used

`--ds-accent`, `--ds-font-mono`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-label`, `--ds-line`, `--ds-line-subtle`, `--ds-radius-lg`, `--ds-row-h`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-surface`, `--ds-surface-row-hover`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`

#### When to use

- Short lists of things with a few actions each: files, saved filters, members, recent items.
- One main line of text per record, with secondary detail.

#### When not to use

- Many comparable columns or sorting: use `DataTable`.
- Navigation between pages: use `NavItem` or `Tabs`.
- Choosing options in a form: use `RadioGroup`, `CheckboxGroup` or `Select`.

#### Anatomy

```
div[role=grid]            named by aria-label / aria-labelledby
  div[role=row]           one tab stop for the whole list; arrow keys move between rows
    Checkbox  selection   optional (selectionMode="multiple"), named "Select {title}"
    span  leading         optional (Avatar, Icon)
    span  title / description
    span  meta            mono, text-2; a node: a module label plus a Badge / DueIndicator
    MoreActionsMenu       IconButton "More actions for {title}" + Menu (optional)
```

In a list 480 px wide or narrower (a container query on the list, not the viewport), `meta` moves under the title and description, so a long title keeps its width instead of shrinking to a few characters next to a due chip.

#### Props (key ones)

| Prop                                   | Type                        | Default  | Notes                                                                                           |
| -------------------------------------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `items`                                | `ActionListItem[]`          | -        | `id`, `title`, `textValue`, `description`, `meta`, `leading`, `actions`, `isDisabled`, `isDone` |
| `aria-label`                           | `string`                    | -        | Required (or `aria-labelledby`)                                                                 |
| `onAction`                             | `(item) => void`            |          | Row click or Enter. Makes the row a press target                                                |
| `selectionMode`                        | `'none' \| 'multiple'`      | `'none'` | `'multiple'` adds a checkbox to every row (toggle behavior)                                     |
| `selectedKeys` / `defaultSelectedKeys` | `'all' \| Iterable<Key>`    |          | Controlled / initial selected row ids                                                           |
| `onSelectionChange`                    | `(keys: Selection) => void` |          | Called when a checkbox is toggled. The consumer owns Undo                                       |
| `bordered`                             | `boolean`                   | `true`   | Border, surface and radius. Turn off inside a `Card`                                            |
| `emptyState`                           | `ReactNode`                 |          | Default: compact `EmptyState` with built-in text                                                |
| `messages`                             | `Partial<messages>`         |          | `moreActions(title)`, `select`, `done`, `emptyTitle`, `emptyDescription`                        |

`actions` is a node: `MenuItem`, `MenuSection` and `MenuSeparator` elements from `Menu`. Put the handler on the item (`<MenuItem onAction={...}>`). Destructive items use `tone="danger"` and still ask for confirmation in a dialog.

The list renders `items` in the order given. Lists are alphabetical by default in this design system: pass them through `sortByText` first (exceptions: tasks by urgency, dated records newest first).

#### Checkbox rows and done state

```tsx
const [done, setDone] = useState<Set<string>>(new Set());

<ActionList
  aria-label="Tasks"
  selectionMode="multiple"
  selectedKeys={done}
  onSelectionChange={(keys) => {
    if (keys === 'all') return;
    const before = done;
    setDone(new Set([...keys].map(String)));
    toastWithUndo('Task updated', { onUndo: () => setDone(before) });
  }}
  onAction={(task) => openTask(task.id)}
  items={tasks.map((task) => ({
    id: task.id,
    title: task.name,
    isDone: done.has(task.id),
    meta: (
      <>
        <span>{task.module}</span>
        <DueIndicator date={task.due} />
      </>
    ),
    actions: <MenuItem onAction={() => edit(task)}>Edit task</MenuItem>,
  }))}
/>;
```

- `isDone` and the checkbox are independent: the list does not derive one from the other. A to-do usually passes `isDone: selected` as above.
- `isDone` sets the title to `text-3` with a line-through (also in forced colors) and adds a visually hidden "Done" after the title (`messages.done`), so the state is never color or decoration alone.
- Toggling is reversible, so it never asks for confirmation. The list does not toggle silently with undo built in: show `toastWithUndo` from `onSelectionChange` as above.

#### Design note (GAP-017, GAP-015)

Decision: extend `ActionList`; no separate `CheckList`. A checkbox list is the same anatomy (title, description, meta, menu) plus a leading control, and consumers need both the checkbox and the row action, which is what `GridList` models. Only `selectionMode: 'none' | 'multiple'` is exposed with `selectionBehavior="toggle"` fixed; `single` is a different pattern (`RadioGroup`, `ListBox`). The "control, module label, due chip, actions" row is built with the existing slots: the checkbox is the selection control, `meta` accepts nodes (module label plus `Badge` or `DueIndicator`), `actions` is the menu. No new slot was needed.

React Aria turns a row into a pure selection toggle as soon as one row is selected, which would silence `onAction`. With `selectionMode="multiple"` the list therefore handles the row action itself (click on the row content, `Enter` on the focused row), so it works whether or not rows are selected. Only the checkbox and `Space` toggle selection.

#### Accessibility

- `GridList` gives `role="grid"` with `row` and `gridcell` roles; rows are not a `list`/`listitem` pair because they are focusable and actionable.
- Each selection checkbox is named "Select {title}" (pt-BR "Selecionar {title}"): the `select` message plus the row's plain-text name, never the meta. A `title` that is not a string needs `textValue`; without it the name falls back to the row `id` and a development warning says so.
- Keyboard: `Tab` enters the list on one row (one tab stop); Arrow Up/Down, Home and End move between rows; Arrow Right moves from the row to its menu button (Arrow Left back); `Enter` on a row runs `onAction`; the menu button follows the Menu contract (`Enter`/`Space`/`Arrow Down` opens, `Escape` closes and focus returns to the button).
- With `selectionMode="multiple"`: `Space` on the focused row (or on its checkbox) toggles it, `Enter` and a click on the row content run `onAction`, a click on the checkbox toggles. Each checkbox is named "Select {title}" (React Aria composes the message `select` with the row text). `Tab`/`ArrowRight` moves from the row to its checkbox and menu button.
- Every menu button has its own name ("More actions for Price list 2026") so a screen reader user can tell them apart.
- Row actions never rely on color; the meta value is text. Disabled rows are dimmed and skipped.
- Known quirk: React Aria moves focus to the row after an overlay inside a row closes. The component hands focus back to the button that was pressed.

#### Content rules

- Titles are the record name, not a sentence. Descriptions say who or when ("Updated by Ana").
- Menu items are verb + object ("Download file", "Delete file").

#### Examples

```tsx
<ActionList
  aria-label="Files"
  items={sortByText(files, (f) => f.name, locale).map((file) => ({
    id: file.id,
    title: file.name,
    description: `Updated by ${file.author}`,
    meta: formatBytes(file.size),
    actions: (
      <>
        <MenuItem onAction={() => download(file)}>Download file</MenuItem>
        <MenuSeparator />
        <MenuItem tone="danger" onAction={() => askToDelete(file)}>
          Delete file
        </MenuItem>
      </>
    ),
  }))}
  onAction={(item) => openFile(item.id)}
/>
```

#### Related components

- Instead, see DataTable: Many comparable columns or sorting: use `DataTable`.
- Instead, see NavItem: Navigation between pages: use `NavItem` or `Tabs`.
- Instead, see Tabs: Navigation between pages: use `NavItem` or `Tabs`.
- Instead, see RadioGroup: Choosing options in a form: use `RadioGroup`, `CheckboxGroup` or `Select`.
- Instead, see CheckboxGroup: Choosing options in a form: use `RadioGroup`, `CheckboxGroup` or `Select`.
- Instead, see Select: Choosing options in a form: use `RadioGroup`, `CheckboxGroup` or `Select`.
- Renders: Checkbox, EmptyState, MoreActionsMenu, VisuallyHidden

### AddCard

> A dashed "create new" tile that sits in a grid next to cards. The whole tile is one link
(`href`) or button (`onPress`) with a centred plus icon and a verb-plus-object label. It
stretches to the height of its row.

A dashed "create new" tile that sits in a grid next to cards. Decision: [ADR-0011](../../../docs/adr/0011-interactive-cards.md).

- Import: `import { AddCard } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/AddCard/AddCard.tsx`
- Stories (Storybook title `Components/AddCard`): Default, AsLink, Disabled, Focused, LongText, RightToLeft, InGrid

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | Label: a short verb plus object in sentence case ("Create agent"). It is the accessible name. |
| `href` | `string` |  |  | Destination of the create flow. Renders a real `<a>`. |
| `target` | `string` |  |  | Link target. `_blank` adds `rel="noopener noreferrer"` and a hidden "opens in a new tab" note. |
| `rel` | `string` |  |  | Link relationship, merged with `noopener noreferrer` for `_blank`. |
| `onPress` | `((event: PressEvent) => void) \| ((event: PressEvent) => void)` |  |  | Fired when the link is pressed, before navigation. Action run when the tile is pressed (usually opens a dialog). Renders a real `<button type="button">`. |
| `ref` | `((instance: HTMLAnchorElement \| null) => void \| (() => VoidOrUndefinedOnly)) \| RefObject<HTMLAnchorElement \| null> \| ((instance: HTMLButtonElement \| null) => void \| (() => VoidOrUndefinedOnly)) \| RefObject<...> \| null` |  |  | Ref to the underlying `<a>` element. Ref to the underlying `<button>` element. |
| `isDisabled` | `boolean` |  |  | Disables the tile: it is dimmed, skipped by `Tab` and ignores presses. |
| `messages` | `Partial<{ opensInNewTab: string; }>` |  |  | Override the built-in messages for this instance. |
| `className` | `string` |  |  |  |

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ AddCard: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `opensInNewTab` | `(opens in a new tab)` |  |

#### Design tokens used

`--ds-accent`, `--ds-add-card-gap`, `--ds-add-card-min-block-size`, `--ds-card-padding`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-fs-body`, `--ds-lh-body`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-weight-medium`

#### When to use

- The last tile of a grid of cards, to create another one ("Create agent", "Create report").

#### When not to use

- A navigation or action tile with a title and description: use `CardLink`.
- A card that groups content: use `Card`.
- The primary action of a screen: use a primary `Button`.
- A tile that is not available yet and does nothing: render a non-interactive card (for example `AgentCard status="soon"`), not a disabled `AddCard`, unless you want to show that creation is currently blocked.

#### Accessibility

- One real `<a>` or `<button>` named by the label; the plus icon is decorative.
- `Tab` reaches it once; `Enter` activates a link or a button, `Space` also activates a button.
- Focus: accent border and ring (kept in `forced-colors`). Hover: one surface step lighter. Dashed border marks an "add" slot (AGENTS.md section 7).
- It stretches to the height of its row in a `Grid`; minimum height 64 px.

#### Example

```tsx
<Grid minItemWidth="md">
  <Card title="Support agent">…</Card>
  <AddCard onPress={openCreateAgent}>Create agent</AddCard>
</Grid>
```

#### Related components

- Instead, see CardLink: A navigation or action tile with a title and description: use `CardLink`.
- Instead, see Card: A card that groups content: use `Card`.
- Instead, see Button: The primary action of a screen: use a primary `Button`.
- Renders: Icon, VisuallyHidden

### AgentCard

> A card for one agent: icon, name, status, description and a footer with the last activity
and the number of items waiting for approval.

The whole card is clickable through the "stretched link" pattern: the agent name inside the
heading is the only link (or button), and a pseudo-element extends its hit area over the
card. The accessible name is just the agent name; status, description and footer are the
description. There is no nested interactive element and no `role="button"` on a `div`.

A card that represents one AI agent: icon, name, status, description and a footer with the last activity and the number of items waiting for approval. The whole card opens the agent. Import it from `loui-ds/patterns`.

- Handoff source: `components/agents/AgentCard` (TODO `CMP-AGT-01`).

- Import: `import { AgentCard } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/AgentCard/AgentCard.tsx`
- Stories (Storybook title `Patterns/AgentCard`): Default, Testing, Paused, ComingSoon, AsLink, NothingPending, LongText, WithoutIcon, Grid, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` | yes |  | Name of the agent. It is the accessible name of the card's single link or button. |
| `area` | `string` |  |  | Short caption under the name (the area the agent works in). |
| `icon` | `LucideIcon` |  |  | Icon of the agent: any icon of the curated set (for example `SearchIcon`) or another Lucide icon. Decorative. |
| `description` | `ReactNode` |  |  | One or two sentences about what the agent does. Part of the accessible description. |
| `status` | `'testing' \| 'active' \| 'paused' \| 'soon'` |  | `'active'` | Lifecycle of the agent. `testing`, `active` and `paused` are available. `soon` is not interactive: dashed border, no link, no pending count. Default `active`. |
| `pending` | `number` |  | `0` | Number of items waiting for approval. Shown (accent number plus text) only when above zero and the agent is available. |
| `lastActivity` | `ReactNode` |  |  | Text about the last activity ("Last reply sent at 08:40"). Shown in the footer. |
| `href` | `string` |  |  | Destination of the card. Renders a real link (router-aware through `DSProvider`). |
| `onOpen` | `() => void` |  |  | Called when the card is activated. Without `href` it renders a real button. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `3` | Heading level of the agent name (`h1` to `h6`). Default `3`. |
| `messages` | `Partial<{ statusTesting: string; statusActive: string; statusPaused: string; statusSoon: string; notConfigured: string; pending: (n: number) => string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ AgentCard: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `statusTesting` | `In testing` | Status badge text. |
| `statusActive` | `Active` |  |
| `statusPaused` | `Paused` |  |
| `statusSoon` | `Coming soon` |  |
| `notConfigured` | `Not set up yet` | Footer text of a card that is not available yet and has no last-activity text. |
| `pending(n: number)` | `to approve` | Text after the (separately styled) pending number: "4 to approve". |

#### Design tokens used

`--ds-accent`, `--ds-agent-card-gap`, `--ds-agent-card-icon-box-size`, `--ds-agent-card-min-height`, `--ds-agent-card-padding`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-body`, `--ds-fs-heading`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-lh-body`, `--ds-lh-heading`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-line`, `--ds-line-strong`, `--ds-line-subtle`, `--ds-radius-lg`, `--ds-radius-md`, `--ds-radius-sm`, `--ds-space-2`, `--ds-space-3`, `--ds-surface`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-semibold`

#### When to use

- A grid of agents (or automations) on an overview page, each leading to its own screen.
- To make "what needs me" visible: the accent number is the only call for attention on the card.

#### When not to use

- A generic clickable card of any other content: build it with `Card` and the same stretched-link technique.
- Several actions per card: this card has exactly one (open). Put other actions on the agent's own screen.

#### Pattern decision: stretched link

The card needs to be fully clickable, show a status badge and still have a clean accessible name. Three options were weighed:

1. Wrap the card in a link or button: the accessible name becomes the concatenation of every text inside (name, caption, status, description, footer), and block content inside a `<button>` is invalid HTML.
2. `div role="button"` (the handoff): no native semantics, and a badge nested in a button.
3. **Stretched link (chosen)**: the agent name, inside the heading, is the only real link or button. A `::after` pseudo-element on it covers the card, so a click anywhere activates it. The accessible name is just the agent name; the status, description and footer are the accessible description (`aria-describedby`). No nested interactive elements.

The focus ring is drawn around the whole card (`:has()` on the focused link), hover brightens the card border.

#### Anatomy

```
div (card, data-status)
  header
    icon box (decorative)
    h{headingLevel} > a | button   <- the only interactive element, stretched over the card
    area caption
    Badge (status)
  p description
  footer
    last activity text
    pending: accent number + "to approve"
```

#### Accessibility

- One tab stop per available card; `Enter` activates a link or button, `Space` also a button.
- The status is text in a `Badge` (color and dot only reinforce it) and is part of the description, so it is read after the name.
- A `soon` card has no link or button and no tab stop; the heading and the "Coming soon" badge say why.
- Count: "4 to approve" is real text in reading order (the number is just styled), pluralized and number-formatted through messages and `Intl`.
- Contrast: the caption and last-activity text use `--ds-text-3` on the surface (passes 4.5:1 there; do not move the card onto a raised surface). Forced colors: the ring becomes a `Highlight` outline.

#### Content rules

- Name: the agent's job in two or three words. Description: what it does and that you approve, in one or two sentences.
- Last activity in the past tense with a time: "Last reply sent at 08:40". Do not add decorative metrics.

#### Examples

```tsx
<AgentCard
  name="Marketplace agent"
  area="Marketplace"
  icon={ShoppingBag}
  status="active"
  pending={4}
  description="Answers buyer questions and reviews. You approve before it sends."
  lastActivity="Last reply sent at 08:40"
  href="/agents/marketplace"
/>
<AgentCard name="Chat agent" status="soon" description="Will draft orders from the conversation." />
```

#### Related components

- Instead, see Card: A generic clickable card of any other content: build it with `Card` and the same stretched-link technique.
- Renders: Badge, Icon

### Alert

> An inline message with a tone, an icon, an optional title, an action and a dismiss button.
The icon is decorative and a visually hidden prefix names the tone for screen readers.

An inline message with a tone, an icon, an optional title, one action and an optional dismiss button.

- Import: `import { Alert } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Alert/Alert.tsx`
- Stories (Storybook title `Components/Alert`): Default, Success, Warning, Danger, Urgent, StaticNotice, TitleOnly, TextOnly, WithAction, Dismissible, LongText, AllTones, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tone` | `'info' \| 'success' \| 'warning' \| 'danger'` |  | `'info'` | Kind of message: `info` (neutral, default), `success`, `warning` or `danger`. |
| `title` | `ReactNode` |  |  | Short heading of the alert, in one line: what happened. Plain text, not a document heading. |
| `children` | `ReactNode` |  |  | The detail: why it happened and what to do. |
| `action` | `ReactNode` |  |  | A single action next to the text, usually a link or a small `Button` ("Update card"). |
| `onDismiss` | `() => void` |  |  | Shows a dismiss button that calls this. The alert is removed by the parent. |
| `urgent` | `boolean` |  | `false` | The message interrupts the user's task and must be announced immediately (`role="alert"`, assertive). Use it only for failures the user must know about right now. |
| `announce` | `boolean` |  | `true` | Whether the alert is a live region (`role="status"`, polite). Default `true`, because most alerts appear after something the user did. Set `false` for a static notice that is part of the page content from the start: it then has no role and is read in page order. Ignored when `urgent`. |
| `messages` | `Partial<{ dismiss: string; info: string; success: string; warning: string; danger: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `tone`: `info`, `success`, `warning`, `danger`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Alert: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `dismiss` | `Dismiss alert` | Name of the dismiss button. |
| `info` | `Information` | Visually hidden prefix that tells screen reader users the kind of alert; color and icon alone cannot. |
| `success` | `Success` |  |
| `warning` | `Warning` |  |
| `danger` | `Error` |  |

#### Design tokens used

`--ds-accent`, `--ds-alert-danger-bg`, `--ds-alert-danger-border`, `--ds-alert-success-bg`, `--ds-alert-success-border`, `--ds-alert-warning-bg`, `--ds-alert-warning-border`, `--ds-bg`, `--ds-danger`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line`, `--ds-radius-lg`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-success`, `--ds-text`, `--ds-text-2`, `--ds-warning`, `--ds-weight-medium`

#### When to use

- Explain a state that affects the page or a form: a declined payment, a scheduled maintenance, a failed import.
- Tell the user what to do about it, next to the thing it is about.

#### When not to use

- Feedback about an action that just finished ("Order #1051 created"): use `Toast`.
- A confirmation that needs a decision: use `Dialog`.
- A field error: use the field's error message.
- A status of a record (Shipped, Failed): use `Badge`.

#### Anatomy

```
div[role=status | alert | none]  (tinted surface, 1px tinted border, radius lg)
  Icon (decorative)  info | success | warning (triangle) | danger
  content
    VisuallyHidden   "Information" | "Success" | "Warning" | "Error"
    title            optional, 14/22, weight 500
    children         13/18, text-2
  actions            action slot · dismiss IconButton
```

#### Accessibility: role decisions

- **Default `role="status"` (polite).** Most alerts appear after something the user did (submit, import). A status region is announced politely, without stealing focus or interrupting speech. The handoff used `role="alert"` for every `danger` alert, which interrupts for things that are not urgent; urgency is now an explicit `urgent` prop, not a function of the tone.
- **`urgent` gives `role="alert"` (assertive).** Use it for a failure the user must know right now (lost connection, session expired). Avoid more than one at a time.
- **`announce={false}` gives no role.** A notice that is part of the page when it loads (a permanent banner, a form-level note) does not need a live region; screen readers read it in page order. A live region that never changes is noise, and many `status` regions on one page are worse.
- Live regions announce **changes**: for the announcement to work, render the Alert when the event happens and keep the region mounted; do not render it hidden and unhide it.
- **The tone is not only color and icon.** The icon is `aria-hidden`; a visually hidden prefix ("Error", "Warning", "Success", "Information", from messages) names the kind of alert for screen readers.
- The **dismiss button** is an `IconButton` named "Dismiss alert" (messages), reachable by Tab and operated with Enter or Space. After dismissing, the parent should move focus somewhere sensible if the alert held it.
- Text contrast on the tinted backgrounds is at least 4.5:1 (checked in the browser test with the real computed colors). The 6% and 30% tints are component tokens (`--ds-alert-*`).
- Forced colors: the browser repaints border and icon with system colors; the icon and the hidden tone prefix still name the tone.

#### Content rules

- Title: what happened, sentence case, no exclamation marks ("Payment declined").
- Text: why and what to do ("The card ending in 4242 was declined. Use another card.").
- The action is a verb plus object ("Update card"), not "Click here".

#### Examples

```tsx
<Alert title="Scheduled maintenance">Sunday, 02:00 to 03:00 UTC.</Alert>

<Alert tone="danger" title="Payment declined" action={<Link href="/billing">Update card</Link>}>
  The card ending in 4242 was declined.
</Alert>

<Alert tone="danger" urgent title="Connection lost" onDismiss={() => setOffline(false)}>
  Changes are not being saved.
</Alert>
```

#### Related components

- Instead, see Dialog: A confirmation that needs a decision: use `Dialog`.
- Instead, see Badge: A status of a record (Shipped, Failed): use `Badge`.
- Renders: Icon, IconButton, VisuallyHidden

### ApprovalCard

> A reply waiting for approval: the original message, an editable draft written by an agent
and two actions, send and discard.

It is an `article` named by its heading ("Review buyer_sp"). Send and discard are secondary
and ghost buttons on purpose: a screen has many of these cards and only one primary action.
They act immediately; the consumer shows an Undo toast instead of asking for confirmation.

A reply waiting for approval: the original message, an editable draft written by an agent, an optional warning and two actions, send and discard. Import it from `loui-ds/patterns`.

- Handoff source: `components/agents/ApprovalCard` (TODO `CMP-AGT-02`).

- Import: `import { ApprovalCard } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/ApprovalCard/ApprovalCard.tsx`
- Stories (Storybook title `Patterns/ApprovalCard`): Default, Review, LowRatingWithFlag, Minimal, LongText, RightToLeft, SendWithUndo

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `message` | `ReactNode` | yes |  | The original message the draft answers. Plain text or nodes. |
| `kind` | `'question' \| 'review'` |  | `'question'` | What is being answered: a `question` or a `review`. Shown as a text badge. Default `question`. |
| `author` | `string` |  |  | Who wrote it (a username or code). Shown in mono and part of the card's accessible name. |
| `itemName` | `string` |  |  | Reference to the item the message is about (a product or order name). |
| `itemColor` | `string` |  |  | Hex color (`#rgb` or `#rrggbb`) shown as a dot before `itemName`. Decorative: `itemName` must name it. |
| `when` | `ReactNode` |  |  | When it was written, as display text ("today, 10:40"). |
| `whenDateTime` | `string` |  |  | Machine-readable date for `when` (an ISO string). Renders a `<time>`. |
| `rating` | `number` |  |  | Star rating of a `review` (0 to 5, halves allowed). Shown only for reviews. |
| `draft` | `string` |  |  | Controlled value of the draft reply. |
| `defaultDraft` | `string` |  |  | Initial value of the draft when uncontrolled. |
| `onDraftChange` | `(draft: string) => void` |  |  | Called with the new text whenever the draft is edited. |
| `flag` | `ReactNode` |  |  | Warning shown above the actions (for example "2-star review: read it carefully before sending"). Linked to the card as its description. Reviews of 1 to 3 stars should always have one. |
| `onSend` | `() => void` |  |  | Called when the send button is pressed. Do it now and offer Undo with a toast; do not ask to confirm. |
| `onDiscard` | `() => void` |  |  | Called when the discard button is pressed. Do it now and offer Undo with a toast. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `3` | Heading level of the card heading (`h1` to `h6`). Default `3`. |
| `messages` | `Partial<{ kindQuestion: string; kindReview: string; messageLabel: string; draftLabel: string; draftHint: string; send: string; discard: string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ ApprovalCard: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `kindQuestion` | `Question` | Kind badge and the first word of the accessible name. |
| `kindReview` | `Review` |  |
| `messageLabel` | `Customer message` | Visually hidden label before the original message. |
| `draftLabel` | `Agent reply` | Label and hint of the editable draft. |
| `draftHint` | `You can edit before sending` |  |
| `send` | `Send reply` | Verb plus object buttons. The card's heading describes which card they belong to. |
| `discard` | `Discard reply` |  |

#### Design tokens used

`--ds-approval-card-body-padding-block`, `--ds-approval-card-gap`, `--ds-approval-card-header-min-height`, `--ds-approval-card-header-padding-block`, `--ds-approval-card-padding`, `--ds-bg`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-lh-small`, `--ds-line`, `--ds-line-subtle`, `--ds-radius-lg`, `--ds-radius-md`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-weight-medium`

#### When to use

- An approval queue: replies, messages or changes an agent prepared that go to a customer or touch money.
- Any "review the draft, edit it, send or discard it" step with many items on one screen.

#### When not to use

- A single decision with a consequence you cannot take back: use a `Dialog` with a confirmation.
- Free chat with an agent: use `ChatPanel`.

#### Principles

**Approve before sending.** Anything an agent writes to a customer goes through this card first. The draft is editable ("You can edit before sending"). Reviews of 1 to 3 stars always carry a `flag`.

**Undo, don't confirm.** Send and discard act immediately. Do not open a confirmation dialog; show a toast with **Undo** (see the recipe below). A confirmation for every card would train people to click through it.

**Secondary buttons, on purpose.** A screen has many cards and only one primary action (AGENTS.md section 5). Send is `secondary`, Discard is `ghost`. The button text is verb plus object ("Send reply", "Discard reply"), not a bare "Send".

#### Anatomy

```
article (named by the heading)
  header
    h{headingLevel}    Badge (Question | Review) + author in mono   <- the accessible name
    Rating             reviews only
    item               optional Swatch dot + item name
    time               when
  body
    message            original text, visually hidden label "Customer message:"
    Textarea           label "Agent reply", aside "You can edit before sending"
    flag               optional warning (icon + text), the card's description
    actions            Discard (ghost)                 Send (secondary)
```

#### Undo recipe

```tsx
function Queue() {
  const toast = useToast();
  function send(reply: Reply) {
    const previous = reply.state; // save what you need to reverse
    markSent(reply.id); // 1. do it now
    toast.success('Reply sent', {
      // 2. say so, past tense
      action: { label: 'Undo', onPress: () => restore(reply.id, previous) }, // 3. reverse it
    });
  }
  return replies.map((reply) => (
    <ApprovalCard
      key={reply.id}
      {...reply}
      onSend={() => send(reply)}
      onDiscard={() => discard(reply)}
    />
  ));
}
```

The real side effect (actually sending to the customer) should be held for the undo window, or undone by a compensating action; see the Toast documentation. After send or discard, remove the card from the queue and move focus to the next card's heading or to the list, so keyboard focus is not lost.

#### Accessibility

- `article` named by its heading through `aria-labelledby` ("Review buyer_sp"); with several cards, screen reader users can jump by heading or article.
- The two buttons are described by the heading (`aria-describedby`), so "Send reply, Review buyer_sp" is spoken without making every button name unique.
- The kind is a text badge, the rating is an image with a text alternative, the flag is text with a decorative icon: nothing relies on color alone. The flag uses `--ds-warning` on the surface (4.5:1 or better).
- Tab order follows reading order: draft, Discard, Send. The draft is a real labelled `Textarea` (its hint is the field description).
- The original message is announced after a hidden "Customer message:" label.

#### Content rules

- The draft is a customer-facing reply: short, factual, no promises about delivery time or discounts, no emoji (AGENTS.md section 5). That is the agent's job; the card only makes it visible and editable.
- `flag` explains the risk and what to do: "2-star review: read it carefully before sending."

#### Related components

- Instead, see Dialog: A single decision with a consequence you cannot take back: use a `Dialog` with a confirmation.
- Instead, see ChatPanel: Free chat with an agent: use `ChatPanel`.
- Renders: Badge, Button, Icon, Rating, Swatch, Textarea, VisuallyHidden

### AppShell

> The application layout: a sidebar, and a main column with a top bar above a scrollable
content region. The sidebar and the content scroll independently; the page itself does not.

Landmarks: the sidebar (`aside`, from `Sidebar`), the top bar (`header`), one `main`
(`id="main"`), and the optional detail `aside`. A skip link to `main` comes first.

Responsive contract (TOK-010): the shell measures its own width (a container query, so it
also works inside a frame). From `--ds-breakpoint-md` (768px) up the sidebar sits in the flow.
Below it the sidebar leaves the flow and opens as an off-canvas panel over the content,
controlled by `isNavOpen` and `AppShellNavToggle`; while it is open the rest of the page is
inert, `Escape` and the scrim close it, and focus returns to the toggle. The shell works from
320px. It fills its parent: give the parent a height, or it takes the viewport height.

The application layout: a sidebar, and a main column with a top bar above a scrollable content region. It includes the skip link and the landmarks.

- Import: `import { AppShell } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/AppShell/AppShell.tsx`
- Stories (Storybook title `Layout/AppShell`): Default, WithDetail, WithoutSidebar, Unpadded, LongContent, NarrowClosed, NarrowOpen, Narrow320, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sidebar` | `ReactNode` |  |  | The app sidebar: a `Sidebar` element. Below the md breakpoint it becomes an off-canvas panel. |
| `topBar` | `ReactNode` |  |  | The page header: a `TopBar` element. Put an `AppShellNavToggle` in its `children` so narrow screens can open the sidebar. |
| `children` | `ReactNode` |  |  | The page content. It is rendered inside the one `main` landmark. |
| `detail` | `ReactNode` |  |  | Optional detail pane at the inline end, `--ds-app-shell-detail-w` (360px) wide, for the record selected in the main content. It is an `aside` landmark with its own scroll. Below the md breakpoint it moves under the main content. `null`, `undefined` and `false` render nothing; a component that renders `null` leaves no empty aside and no reserved column either (the empty aside is hidden with `:empty`). |
| `detailLabel` | `string` |  |  | Accessible name of the detail aside. Default "Details" from the message catalog. |
| `mainId` | `string` |  | `main` | `id` of the `main` element, and the target of the skip link. Default `main`. |
| `padded` | `boolean` |  | `true` | Pads the main content with `--ds-app-shell-main-padding`. Turn it off when the content brings its own padding (a `Container` has a gutter). Default `true`. |
| `skipLink` | `boolean` |  | `true` | Renders the skip link as the first focusable element. Default `true`; turn it off only if the app has its own. |
| `isNavOpen` | `boolean` |  |  | Controlled state of the off-canvas sidebar (narrow screens only). Pair with `onNavOpenChange`. |
| `defaultNavOpen` | `boolean` |  | `false` | Initial state of the off-canvas sidebar when uncontrolled. Default `false`. |
| `onNavOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the off-canvas sidebar opens or closes (toggle, `Escape`, scrim, close button). |
| `messages` | `Partial<{ navToggle: string; navClose: string; detail: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ AppShell: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `navToggle` | `Menu` | Text of the button that opens the navigation panel on narrow screens. |
| `navClose` | `Close menu` | Text of the button that closes the navigation panel on narrow screens. |
| `detail` | `Details` | Accessible name of the detail aside landmark. |

#### Design tokens used

`--ds-accent`, `--ds-app-shell-detail-w`, `--ds-app-shell-main-padding`, `--ds-app-shell-nav-z-index`, `--ds-bg`, `--ds-duration`, `--ds-ease`, `--ds-font-sans`, `--ds-line-control`, `--ds-line-subtle`, `--ds-scrim`, `--ds-shadow-dialog`, `--ds-space-1`, `--ds-space-12`, `--ds-space-2`, `--ds-space-3`, `--ds-text`, `--ds-toast-clearance`

#### When to use

- The frame of every screen of an app: `Sidebar` + `TopBar` + content (+ optional detail pane).

#### When not to use

- A marketing page or a single-column document: use `Container` and let the page scroll.
- Inside another AppShell.

#### Anatomy

```
div.root  (container, fills the parent, no page scroll)
  SkipLink                       first focusable element
  div.nav                        wraps the Sidebar (aside); off-canvas below md
  div.scrim                      only when the panel is open
  div.column
    TopBar                       header
    div.body
      main#main                  scrolls on its own
      aside "Details"            optional, 360px, scrolls on its own
```

#### Responsive decision (TOK-010)

**The DS guarantees every component works from 320px wide, and AppShell collapses its sidebar into an off-canvas panel below `--ds-breakpoint-md` (768px).**

Why built in rather than left to apps: a sidebar hidden by an app without a way back strands keyboard and touch users, and every product would build the same panel. It is kept simple: it reuses the same `Sidebar` element (no second copy, no lost state) and CSS does the layout.

- The shell measures **its own width** with a container query, so it behaves the same in a frame, a preview or a test. The 768px in the CSS is `--ds-breakpoint-md`; CSS cannot read variables inside a query, so `AppShell.test.tsx` asserts the two agree at 767/768px.
- From md up the sidebar sits in the flow. Below, it leaves the flow; `AppShellNavToggle` (visible only below md) opens it as a panel over a scrim.
- While open: focus moves into the panel, the rest of the page is `inert`, `Escape`, the scrim or the "Close menu" button close it, and focus returns to the toggle. It is not a `Dialog`: it keeps the sidebar's own landmarks.
- An empty detail leaves nothing behind: `detail` set to `null`, `undefined` or `false` renders no aside, and a component that renders `null` leaves an empty aside that is hidden (`:empty`), so no landmark and no 360px column stay. Prefer `detail={selected ? <Detail /> : undefined}`.
- The detail pane moves **under** the main content (half the height at most, own scroll) below md.
- Breakpoint tokens: `--ds-breakpoint-sm|md|lg|xl` (480 / 768 / 1024 / 1280 px); content: `--ds-content-max`, `--ds-content-gutter`; `--ds-container-sm|md|lg`.

#### Accessibility

- Landmarks: `aside` (Sidebar, "Sidebar"), `header` (TopBar), **one** `main`, optional `aside` ("Details"). Each `nav` in the sidebar is named by its caption.
- The skip link is the first stop and moves focus to `main`.
- `main` and the detail aside scroll independently. While they overflow they become keyboard stops (`tabindex="0"`) so the arrow keys scroll them; with nothing to scroll there is no extra tab stop.
- The closed panel is `visibility: hidden` and `inert`, so it is out of the tab order and the accessibility tree.
- The panel slide respects `prefers-reduced-motion`; the layout mirrors in RTL.
- `AppShellNavToggle` reports `aria-expanded` and `aria-controls`. It is an `IconButton` (menu icon) named "Menu" (`pt-BR` "Menu"; pass a string child to rename it); the close button is an `IconButton` (x icon) named "Close menu" / "Fechar menu", which sits on the scrim beside the panel and never wraps.

#### Content rules

- One `h1` per page: `TopBar` renders it from `title`.
- One primary action per screen, at the end of the top bar.

#### Examples

```tsx
<AppShell
  sidebar={<Sidebar workspace={workspace} sections={sections} value={route} onChange={go} />}
  topBar={
    <TopBar title="Orders" actions={<Button variant="primary">New order</Button>}>
      <AppShellNavToggle />
    </TopBar>
  }
  detail={selected ? <OrderDetail order={selected} /> : undefined}
>
  <OrdersTable />
</AppShell>
```

#### Related components

- Instead, see Container: A marketing page or a single-column document: use `Container` and let the page scroll.
- Renders: IconButton, SkipLink

### AppShellNavToggle

> The icon button (menu icon) that opens the off-canvas sidebar. Put it in the `TopBar` (as its `children`).
It is only visible below the md breakpoint, and reports `aria-expanded`. It must be rendered
inside `AppShell`.

The application layout: a sidebar, and a main column with a top bar above a scrollable content region. It includes the skip link and the landmarks.

- Import: `import { AppShellNavToggle } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/AppShell/AppShell.tsx`
- Stories (Storybook title `Layout/AppShell`): Default, WithDetail, WithoutSidebar, Unpadded, LongContent, NarrowClosed, NarrowOpen, Narrow320, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `string` |  |  | Accessible name of the icon button. Default "Menu" from the message catalog. |
| `className` | `string` |  |  | Class name for the wrapper. |

#### Design tokens used

`--ds-accent`, `--ds-app-shell-detail-w`, `--ds-app-shell-main-padding`, `--ds-app-shell-nav-z-index`, `--ds-bg`, `--ds-duration`, `--ds-ease`, `--ds-font-sans`, `--ds-line-control`, `--ds-line-subtle`, `--ds-scrim`, `--ds-shadow-dialog`, `--ds-space-1`, `--ds-space-12`, `--ds-space-2`, `--ds-space-3`, `--ds-text`, `--ds-toast-clearance`

#### When to use

- The frame of every screen of an app: `Sidebar` + `TopBar` + content (+ optional detail pane).

#### When not to use

- A marketing page or a single-column document: use `Container` and let the page scroll.
- Inside another AppShell.

#### Anatomy

```
div.root  (container, fills the parent, no page scroll)
  SkipLink                       first focusable element
  div.nav                        wraps the Sidebar (aside); off-canvas below md
  div.scrim                      only when the panel is open
  div.column
    TopBar                       header
    div.body
      main#main                  scrolls on its own
      aside "Details"            optional, 360px, scrolls on its own
```

#### Responsive decision (TOK-010)

**The DS guarantees every component works from 320px wide, and AppShell collapses its sidebar into an off-canvas panel below `--ds-breakpoint-md` (768px).**

Why built in rather than left to apps: a sidebar hidden by an app without a way back strands keyboard and touch users, and every product would build the same panel. It is kept simple: it reuses the same `Sidebar` element (no second copy, no lost state) and CSS does the layout.

- The shell measures **its own width** with a container query, so it behaves the same in a frame, a preview or a test. The 768px in the CSS is `--ds-breakpoint-md`; CSS cannot read variables inside a query, so `AppShell.test.tsx` asserts the two agree at 767/768px.
- From md up the sidebar sits in the flow. Below, it leaves the flow; `AppShellNavToggle` (visible only below md) opens it as a panel over a scrim.
- While open: focus moves into the panel, the rest of the page is `inert`, `Escape`, the scrim or the "Close menu" button close it, and focus returns to the toggle. It is not a `Dialog`: it keeps the sidebar's own landmarks.
- An empty detail leaves nothing behind: `detail` set to `null`, `undefined` or `false` renders no aside, and a component that renders `null` leaves an empty aside that is hidden (`:empty`), so no landmark and no 360px column stay. Prefer `detail={selected ? <Detail /> : undefined}`.
- The detail pane moves **under** the main content (half the height at most, own scroll) below md.
- Breakpoint tokens: `--ds-breakpoint-sm|md|lg|xl` (480 / 768 / 1024 / 1280 px); content: `--ds-content-max`, `--ds-content-gutter`; `--ds-container-sm|md|lg`.

#### Accessibility

- Landmarks: `aside` (Sidebar, "Sidebar"), `header` (TopBar), **one** `main`, optional `aside` ("Details"). Each `nav` in the sidebar is named by its caption.
- The skip link is the first stop and moves focus to `main`.
- `main` and the detail aside scroll independently. While they overflow they become keyboard stops (`tabindex="0"`) so the arrow keys scroll them; with nothing to scroll there is no extra tab stop.
- The closed panel is `visibility: hidden` and `inert`, so it is out of the tab order and the accessibility tree.
- The panel slide respects `prefers-reduced-motion`; the layout mirrors in RTL.
- `AppShellNavToggle` reports `aria-expanded` and `aria-controls`. It is an `IconButton` (menu icon) named "Menu" (`pt-BR` "Menu"; pass a string child to rename it); the close button is an `IconButton` (x icon) named "Close menu" / "Fechar menu", which sits on the scrim beside the panel and never wraps.

#### Content rules

- One `h1` per page: `TopBar` renders it from `title`.
- One primary action per screen, at the end of the top bar.

#### Examples

```tsx
<AppShell
  sidebar={<Sidebar workspace={workspace} sections={sections} value={route} onChange={go} />}
  topBar={
    <TopBar title="Orders" actions={<Button variant="primary">New order</Button>}>
      <AppShellNavToggle />
    </TopBar>
  }
  detail={selected ? <OrderDetail order={selected} /> : undefined}
>
  <OrdersTable />
</AppShell>
```

#### Related components

- Instead, see Container: A marketing page or a single-column document: use `Container` and let the page scroll.
- Renders: IconButton, SkipLink

### Avatar

> A circular photo or initials of a person, in grays (never a color per person). The `name`
drives the initials and the accessible name; a photo that fails to load falls back to the
initials.

A circular photo or the initials of a person, in grays. There is no color per person.

- Import: `import { Avatar } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Avatar/Avatar.tsx`
- Stories (Storybook title `Components/Avatar`): Default, Sizes, WithPhoto, BrokenPhoto, Decorative, Shades, Stacked, LongName, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` |  |  | The person's full name. Drives the initials and the accessible name (`alt` of the photo). Optional: still used to compute the initials. |
| `decorative` | `boolean` |  | `false` | Hides the avatar from assistive technology (`alt=""`). Use it when the name is shown next to it. |
| `src` | `string` |  |  | URL of the photo. If it fails to load, the initials are shown instead. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | `sm` 24px, `md` 28px (default), `lg` 40px. |
| `ring` | `boolean` |  | `false` | Draws a 2px ring in the surface color, to separate overlapping avatars. Default `false`. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Design tokens used

`--ds-avatar-initials-ratio`, `--ds-avatar-ring-width`, `--ds-avatar-size-lg`, `--ds-avatar-size-md`, `--ds-avatar-size-sm`, `--ds-font-sans`, `--ds-line`, `--ds-line-strong`, `--ds-radius-pill`, `--ds-surface`, `--ds-surface-hover`, `--ds-text`, `--ds-weight-semibold`

#### When to use

- Identify who owns, created or is assigned to something.
- Next to a name in a list, a comment or a menu.

#### When not to use

- For a company logo or a product thumbnail: use an image.
- For a status: use `Badge`.

#### Anatomy

```
span.root (circle, role="img" + aria-label when it initials)
  img | span[aria-hidden] initials
```

#### Initials

`getInitials(name, locale)` (also exported) takes the first letter of the first and of the last word: "Ana Maria da Silva" is `AS`; a single word gives one letter. It uses `Intl.Segmenter` (combined characters stay whole) and `toLocaleUpperCase` with the `DSProvider` locale (`i` becomes `İ` in Turkish). The gray shade is derived from the name, so one person always looks the same.

#### Accessibility

- With initials the root is `role="img"` named by `name`; the letters are `aria-hidden` so they are not read twice.
- With a photo the `<img>` has `alt={name}`. A decorative avatar has `alt=""` and no role.
- The handoff set `alt` to the initials ("AL"), which is meaningless to a screen reader; the full name is used now.
- If the image cannot be loaded the initials appear and the accessible name stays the same.
- Avatars are not interactive. Put one inside a button or link that has its own name and mark it `decorative`.

#### Content rules

- Pass the full display name, not the initials.
- Never pass an email or an id as `name`.

#### Examples

```tsx
<Avatar name="Ada Lovelace" />
<Avatar name="Ada Lovelace" src="/photos/ada.jpg" size="lg" />
<Avatar decorative name="Ada Lovelace" /> <span>Ada Lovelace</span>
```

Stacked avatars: wrap them in a flex container with `role="group"` and an `aria-label`, give each `ring`, and overlap with a negative inline margin. A dedicated `AvatarGroup` is not part of this version.

#### Related components

- Instead, see Badge: For a status: use `Badge`.
- Used by: Sidebar

### Badge

> A pill with a short status label. The text always states the status; the tone and the
dot only reinforce it.

A pill with a short status label. The text always states the status; the tone and the dot only reinforce it.

- Import: `import { Badge } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Badge/Badge.tsx`
- Stories (Storybook title `Components/Badge`): Default, Accent, Success, Warning, Danger, WithoutDot, AllTones, LongText, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | The status text. Required: color and the dot never carry the meaning alone. |
| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  | `'neutral'` | Meaning of the badge: `accent` open or in progress, `success` done, `warning` pending, `danger` failed, `neutral` everything else (default). |
| `dot` | `boolean` |  | `true` | Shows the small decorative dot before the text. It is hidden from assistive technology. Default `true`. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `tone`: `neutral`, `accent`, `success`, `warning`, `danger`

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-badge-dot-size`, `--ds-badge-height`, `--ds-badge-padding-inline`, `--ds-danger`, `--ds-danger-soft`, `--ds-font-sans`, `--ds-fs-label`, `--ds-lh-label`, `--ds-radius-pill`, `--ds-space-2`, `--ds-success`, `--ds-success-soft`, `--ds-surface-hover`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-warning-soft`, `--ds-weight-medium`

#### When to use

- Show the state of a record in a list, a table row or a card header: Draft, In progress, Shipped, Failed.
- Keep the text short (one to three words, sentence case).

#### When not to use

- For a count or a filter value: use `Tag`.
- For a message the user must read or act on: use `Alert`.
- For an action: use `Button`. A Badge is never interactive.

#### Anatomy

```
[ dot ] Text
```

- `dot` (optional, decorative, `aria-hidden`).
- `text`: required, the status.

#### Accessibility

- A Badge is plain text in a `span`: there is no role and no keyboard behavior.
- The dot is `aria-hidden`; the tone is never the only carrier of meaning, because the text names the status (WCAG 1.4.1).
- Text on every soft tint keeps at least 4.5:1 contrast (checked in the browser test by compositing the real computed colors).
- In forced-colors mode the Badge gets a border and the dot takes the text color.

#### Content rules

- Sentence case, no punctuation, no emoji: "In progress", not "IN PROGRESS!".
- Name the state, not the action: "Shipped", not "Ship".
- If the status can be unknown, say so with text ("Unknown"), do not omit the Badge.

#### Examples

```tsx
<Badge tone="success">Shipped</Badge>
<Badge tone="danger">Failed</Badge>
<Badge dot={false}>Draft</Badge>
```

#### Related components

- Instead, see Tag: For a count or a filter value: use `Tag`.
- Instead, see Alert: For a message the user must read or act on: use `Alert`.
- Instead, see Button: For an action: use `Button`. A Badge is never interactive.
- Used by: AgentCard, ApprovalCard

### Banner

> A persistent, full-width message for a whole page or section: maintenance, a limited account,
an offline mode. It stays until the condition ends or the user dismisses it.
The icon is decorative and a visually hidden prefix names the tone for screen readers.

A persistent, full-width message for a whole page or section: maintenance, a limited account, an offline mode. It has a tone, an icon, an optional title, one action and an optional dismiss button.

- Import: `import { Banner } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Banner/Banner.tsx`
- Stories (Storybook title `Components/Banner`): Default, Success, Warning, Danger, Urgent, Announced, TitleOnly, TextOnly, Dismissible, LongText, AllTones, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tone` | `'info' \| 'success' \| 'warning' \| 'danger'` |  | `'info'` | Kind of message: `info` (neutral, default), `success`, `warning` or `danger`. |
| `title` | `ReactNode` |  |  | Short heading in one line: what is going on. Plain text, not a document heading. |
| `children` | `ReactNode` |  |  | The detail: why, and what to do. Keep it to one or two sentences. |
| `action` | `ReactNode` |  |  | A single action next to the text, usually a link or a small `Button` ("Update card"). |
| `onDismiss` | `() => void` |  |  | Shows a dismiss button that calls this. The banner is removed by the parent. |
| `urgent` | `boolean` |  | `false` | The banner appears while the user is working and interrupts the task, so it must be announced immediately (`role="alert"`, assertive). Only for a failure the user must know about right now. A banner that is on the page from the start never needs it. |
| `announce` | `boolean` |  | `false` | Whether the banner is a live region (`role="status"`, polite). Default `false`, because a banner is usually part of the page when it loads and a live region that never changes is noise. Set `true` when the banner is added to the page after load (a lost connection that is restored, a session that is about to expire). Ignored when `urgent`. |
| `messages` | `Partial<{ dismiss: string; info: string; success: string; warning: string; danger: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `tone`: `info`, `success`, `warning`, `danger`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Banner: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `dismiss` | `Dismiss banner` | Name of the dismiss button. |
| `info` | `Information` | Visually hidden prefix that tells screen reader users the kind of banner; color and icon alone cannot. |
| `success` | `Success` |  |
| `warning` | `Warning` |  |
| `danger` | `Error` |  |

#### Design tokens used

`--ds-accent`, `--ds-banner-content-basis`, `--ds-banner-danger-bg`, `--ds-banner-danger-border`, `--ds-banner-success-bg`, `--ds-banner-success-border`, `--ds-banner-warning-bg`, `--ds-banner-warning-border`, `--ds-bg`, `--ds-danger`, `--ds-fs-small`, `--ds-lh-small`, `--ds-line`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-success`, `--ds-text`, `--ds-text-2`, `--ds-warning`, `--ds-weight-medium`

#### When to use

- A condition that affects the whole page or area and lasts until it is resolved or dismissed: scheduled maintenance, a trial ending, a read-only mode.
- Place it at the top of the page or section it applies to, above the content.

#### When not to use

- Feedback about something that just happened and goes away by itself ("Order #1051 created"): use `Toast`.
- A message about one piece of content, inside it (a form, a card): use `Alert`.
- A field error: use the field's error message.
- A confirmation that needs a decision: use `Dialog`.
- The status of a record: use `Badge`.

##### Banner, Alert and Toast

|             | Banner                                             | Alert                                   | Toast                                |
| ----------- | -------------------------------------------------- | --------------------------------------- | ------------------------------------ |
| Scope       | Page or section                                    | Inline, next to the content it explains | The app, in a corner                 |
| Lifetime    | Persistent, until resolved or dismissed            | Persistent while relevant               | Transient, auto-dismisses (pausable) |
| Shape       | Full width, flat, top and bottom border only       | Rounded card                            | Elevated overlay                     |
| Live region | None by default (it is on the page from the start) | Polite status by default                | Always announced                     |

#### Anatomy

```
div[role=alert | status | none]  (tinted surface, 1px tinted top and bottom border, full width)
  Icon (decorative)  info | success | warning (triangle) | danger
  content
    VisuallyHidden   "Information" | "Success" | "Warning" | "Error"
    title            optional, 14/22, weight 500
    children         text-2, on the same line as the title when it fits
  actions            action slot · dismiss IconButton
```

#### Accessibility: role decisions

- **No role by default.** A banner is normally part of the page when it loads; screen readers read it in page order. A live region that never changes is noise.
- **`announce` gives `role="status"` (polite).** Use it when the banner is inserted after load (connection restored, session about to expire). Render the banner when the event happens and keep it mounted; do not render it hidden and unhide it.
- **`urgent` gives `role="alert"` (assertive).** Use it only for a `danger` or `warning` banner that appears dynamically and needs attention now (connection lost, session expired). A `danger` or `warning` banner that is on the page from the start must not be `urgent`: the tone does not imply urgency.
- **The tone is not only color and icon.** The icon is `aria-hidden`; a visually hidden prefix ("Error", "Warning", "Success", "Information", from messages) names the kind of banner.
- The **dismiss button** is an `IconButton` named "Dismiss banner" (messages), reachable by Tab and operated with Enter or Space. After dismissing, move focus somewhere sensible if the banner held it.
- Text contrast on the tinted backgrounds is at least 4.5:1 (checked in the browser test with the real computed colors). The tints are component tokens (`--ds-banner-*`).
- Reflow: the text and the actions wrap; at 320 px the action moves below the text.

#### Content rules

- Title: what is going on, sentence case, no exclamation marks ("Trial ends in 3 days").
- Text: why and what to do, one or two sentences.
- The action is a verb plus object ("Choose plan"), not "Click here".
- Do not stack more than one banner per page area.

#### Examples

```tsx
<Banner title="Scheduled maintenance">Sunday, 02:00 to 03:00 UTC.</Banner>

<Banner
  tone="warning"
  title="Trial ends in 3 days"
  action={<Button size="sm">Choose plan</Button>}
  onDismiss={() => setHidden(true)}
>
  Choose a plan to keep your data.
</Banner>

<Banner tone="danger" urgent title="Connection lost">
  Changes are not being saved.
</Banner>
```

#### Related components

- Instead, see Alert: A message about one piece of content, inside it (a form, a card): use `Alert`.
- Instead, see Dialog: A confirmation that needs a decision: use `Dialog`.
- Instead, see Badge: The status of a record: use `Badge`.
- Renders: Icon, IconButton, VisuallyHidden

### Breadcrumb

> The path to the current page as an ordered list of links inside a `nav` landmark. The
separators are decorative (`aria-hidden`), so a screen reader hears a list of N items. Long
labels are truncated with an ellipsis (the current page keeps the most room); collapsing the
middle of a long trail into a menu is not supported yet.

The path from the root to the current page, as an ordered list of links inside a `nav` landmark. Built on React Aria `Breadcrumbs` and `Breadcrumb`.

- Handoff source: `components/layout/Breadcrumb.jsx` (TODO `CMP-LAY-03`).

- Import: `import { Breadcrumb } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Breadcrumb/Breadcrumb.tsx`
- Stories (Storybook title `Components/Breadcrumb`): Default, SingleItem, KeyboardNavigation, LongTrail, RouterNavigation, Portuguese, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly BreadcrumbItem[]` | yes |  | The trail from the root to the current page. The last item is the current page: it gets `aria-current="page"` and is not a link. |
| `messages` | `Partial<{ label: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Breadcrumb: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `label` | `Breadcrumb` | Accessible name of the breadcrumb navigation landmark. |

#### Design tokens used

`--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-sans`, `--ds-fs-small`, `--ds-lh-small`, `--ds-radius-sm`, `--ds-space-2`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`

#### When to use

- Deep hierarchies (Orders > Northwind Traders > ORD-1048) where people need to go up a level.
- Inside the `TopBar` instead of a title.

#### When not to use

- For the steps of a process: use a stepper (`StatusSteps`).
- For the main navigation: use `Sidebar` and `NavItem`.
- For a flat app with two levels: a page title and a "Back" link are enough.

#### Accessibility

- `nav` named "Breadcrumb" containing an `ol`: a screen reader announces a list and its length.
- The current page is `aria-current="page"` and is not a link.
- Separators are decorative icons with `aria-hidden`, so they are never read. They mirror in right-to-left locales.
- Tab visits each ancestor link in order. Link text is `--ds-text-2` and turns ink with an underline on hover.
- Truncation: ancestors shrink first (three times faster than the current page) and show an ellipsis; labels are not wrapped. Give the full text to users some other way when it matters (the page title).
- Collapsing the middle of a long trail into a menu ("...") is not supported yet; it needs the `Menu` component (P3).

#### Content rules

- Labels are the page titles, short, in sentence case. The last label matches the page `h1`.
- Do not include "Home" unless it is a real destination people use.

#### Examples

```tsx
<Breadcrumb
  items={[
    { label: 'Orders', href: '/orders' },
    { label: 'Northwind Traders', href: '/customers/northwind' },
    { label: 'ORD-1048' },
  ]}
/>
```

#### Related components

- Instead, see StatusSteps: For the steps of a process: use a stepper (`StatusSteps`).
- Instead, see Sidebar: For the main navigation: use `Sidebar` and `NavItem`.
- Instead, see NavItem: For the main navigation: use `Sidebar` and `NavItem`.
- Renders: Icon
- Used by: TopBar

### Button

> An action button built on React Aria's `Button`.

Use one `primary` button per screen. While `isPending` the button keeps its width and its
label (dimmed), shows a spinner before the label (over the `leading` icon when there is one), stays focusable, sets `aria-disabled` and ignores presses, so it can be explained
by a tooltip and focus is never lost.

The control for an action. Built on React Aria's `Button`, styled with tokens and `data-*` state attributes.

- Handoff source: `components/forms/Button` (CMP-FRM-01).

- Import: `import { Button } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Button/Button.tsx`
- Stories (Storybook title `Components/Button`): Default, Primary, Secondary, Ghost, Danger, DangerSolid, Variants, Sizes, WithLeadingIcon, WithTrailingShortcut, FullWidth, Disabled, Pending, PendingVariants, PendingWithLeadingAndSizes, LongText, Rtl, KeyboardActivation, Focused, Hovered

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'danger-solid'` |  | `'secondary'` | Visual style. - `primary`: the single main action of the screen (light ink on dark). One per screen. - `secondary`: default for other actions. - `ghost`: tertiary, low emphasis actions. - `danger`: destructive action that is not yet confirmed. - `danger-solid`: the confirm button of a destructive dialog. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Height token: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `fullWidth` | `boolean` |  | `false` | Stretch to the width of the container. |
| `leading` | `ReactNode` |  |  | Node before the label, usually `<Icon size="sm" />`. Decorative; the label names the button. |
| `trailing` | `ReactNode` |  |  | Node after the label, for example a `Kbd` shortcut hint. |
| `shortcut` | `readonly string[]` |  |  | Keyboard shortcut of the action, as `Kbd` keys (`['Mod', 'K']`). Renders the hint after the label (before `trailing`), hidden from assistive technology, and sets `aria-keyshortcuts` so the shortcut is announced once and is not part of the accessible name. Bind the key itself with `useHotkeys`. |
| `children` | `ReactNode` |  |  | Label: a short verb plus object in sentence case ("Create order"). |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLButtonElement>` |  |  | Ref to the underlying `<button>` element. |

##### Inherited props

- From `AriaBaseButtonProps` (react-aria): `aria-controls`, `aria-current`, `aria-disabled`, `aria-expanded`, `aria-haspopup`, `aria-pressed`, `form`, `formAction`, `formEncType`, `formMethod`, `formNoValidate`, `formTarget`, `name`, `preventFocusOnPress`, `type`, `value`
- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `ButtonProps` (react-aria): `isDisabled`
- From `ButtonProps` (react-aria-components): `isPending`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `HoverEvents` (@react-types/shared): `onHoverChange`, `onHoverEnd`, `onHoverStart`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `primary`, `secondary`, `ghost`, `danger`, `danger-solid`
- `size`: `sm`, `md`, `lg`

#### Design tokens used

`--ds-accent`, `--ds-button-danger-solid-hover-brightness`, `--ds-button-hover-brightness`, `--ds-button-pending-label-opacity`, `--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-danger`, `--ds-danger-line`, `--ds-danger-soft`, `--ds-danger-soft-hover`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-sans`, `--ds-fs-body`, `--ds-fs-label`, `--ds-fs-small`, `--ds-icon-md`, `--ds-icon-sm`, `--ds-lh-body`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-primary-bg`, `--ds-primary-fg`, `--ds-primary-fg-muted`, `--ds-radius-md`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-space-5`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-text-inverse`, `--ds-weight-medium`

#### One primary per screen

Use **one `primary` button per screen**, at the top right of the view, ideally with a keyboard shortcut. Primary is "ink for action": light on dark, never the accent color. Every other action is `secondary` or `ghost`. A second primary button means the screen has two main jobs: split the screen or demote one action.

#### When to use

- To run an action in place: "Create order", "Mark as shipped".
- `danger` for a destructive action that opens a confirmation, `danger-solid` for the confirm button inside that dialog (initial focus stays on Cancel).
- `ghost` for low-emphasis actions such as "View all" in a card header.

#### When not to use

- To navigate to another page: use `Link` (styled as text) so the browser keeps link semantics.
- For an icon-only action: use `IconButton`, which requires an accessible name.
- For a two-state toggle: use a toggle component.

#### Anatomy

`[leading] label [trailing]` inside one native `<button>`. When pending, the label stays visible, dimmed with `--ds-button-pending-label-opacity` (0.65), and a `Spinner` takes the leading position: it sits over the `leading` icon when there is one, otherwise before the label, using the button padding (the content is pulled outward by half of spinner plus gap on each side), so the width never changes. The dimmed label is a busy state, not a disabled one; the label keeps meaning, so users still see what the action is doing (for example "Connecting").

#### Accessibility

- A `Kbd` inside a button (through `shortcut` or `trailing`) is hidden from assistive technology, so the accessible name is only the label ("Settings", not "Settings Escape"). `shortcut` also sets `aria-keyshortcuts` (`Control+K`, `Meta+K` on Apple).

- A real `<button>`; the name is its visible label.
- Keys: `Tab` focuses, `Enter` and `Space` press (RAC). One tab stop.
- Focus: accent border plus a 3px ring through `data-focus-visible`, a transparent outline that forced-colors mode repaints as `Highlight`. Mouse clicks do not show the ring.
- Pending: the button stays in the tab order (focus is not lost while waiting) with `aria-disabled="true"` (React Aria does not set `aria-busy`). React Aria announces the busy state when the focused button becomes pending and again when it finishes. The spinner is named "Loading" (pt-BR "Carregando", from the `Spinner` messages) and sits inside the button so it is part of the button's content.
- Disabled: removed from the tab order. Explain _why_ in nearby text rather than relying on a disabled button alone.
- Targets: at least 32px high, above the 24px minimum of WCAG 2.5.8.
- Contrast: label colors meet 4.5:1 on their backgrounds in every variant; disabled controls are exempt.
- Reduced motion: the only transition is a 150ms background color change, which the global reduced-motion rule neutralizes. The pending spinner turns into a static ring.

#### Content rules

- Verb plus object, sentence case: "Create order", "Retry charge". Never a bare "OK" or "Send".
- Destructive buttons name the action: "Delete order".
- No exclamation marks, no emoji, no decorative ellipsis. Use "..." only when the action opens something that needs more input ("Move to...").

#### States

Hover (one surface step lighter; primary dims with `--ds-button-hover-brightness`), focus-visible, disabled, pending. Hover, focus and pending are CSS (`data-hovered`, `data-focus-visible`, `data-pending`), never React state. There is no press animation.

#### Examples

```tsx
<Button variant="primary" onPress={save}>Save changes</Button>

<Button leading={<Icon icon={PlusIcon} size="sm" />}>Create order</Button>

<Button variant="primary" isPending={isSaving} onPress={save}>
  Save changes
</Button>

<Button trailing={<span className="ds-mono">⌘K</span>}>Search</Button>
```

#### Related components

- Instead, see Link: To navigate to another page: use `Link` (styled as text) so the browser keeps link semantics.
- Instead, see IconButton: For an icon-only action: use `IconButton`, which requires an accessible name.
- Renders: Kbd, Spinner
- Used by: ApprovalCard, ChatPanel, ConfirmDialog, DataTable, DatePicker, FileUpload, InlineConfirm, ResponseFeedback, ShortcutsHelp, ToastRegion, Tour

### Calendar

> A month calendar (React Aria `Calendar`, an ARIA grid). The value is a `YYYY-MM-DD` string.
Months, weekday names and the first day of the week follow the `DSProvider` locale.

Keys: arrows move by day and week, `PageUp` / `PageDown` by month, `Shift+PageUp` /
`Shift+PageDown` by year, `Home` / `End` to the start / end of the week, `Enter` / `Space`
select. Each day button is named with its full date ("Wednesday, October 28, 2026"); today is
ringed and named "Today".

`DatePicker` is a date field (typed segments) with a calendar popover and "Today" / "Clear" buttons. `Calendar` is the standalone month grid. Built on React Aria `DatePicker`, `DateInput`, `DateSegment`, `Calendar`, `CalendarGrid`, `CalendarCell`, `Popover`. Task: CMP-INP-02.

- Import: `import { Calendar } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/DatePicker/Calendar.tsx`
- Stories (Storybook title `Components/DatePicker`): Default, CalendarKeyboard, Open, PickDate, EscapeRestoresFocus, WithValue, MinAndMax, Required, Invalid, Disabled, ReadOnly, Brazilian, Sizes, StandaloneCalendar, FullWidthInRow

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `min` | `string` |  |  | Earliest selectable date (`YYYY-MM-DD`). Earlier days are disabled. |
| `max` | `string` |  |  | Latest selectable date (`YYYY-MM-DD`). Later days are disabled. |
| `isDisabled` | `boolean` |  |  | Disables the whole calendar: days cannot be focused or selected. |
| `isReadOnly` | `boolean` |  |  | The calendar can be navigated and focused but the value cannot change. |
| `autoFocus` | `boolean` |  |  | Moves focus into the grid on mount. |
| `className` | `string` |  |  |  |
| `messages` | `Partial<{ previousMonth: string; nextMonth: string; }>` |  |  | Message overrides for this instance: `previousMonth`, `nextMonth`. |
| `ref` | `Ref<HTMLDivElement>` |  |  |  |
| `aria-label` | `string` |  |  | Accessible name of the calendar grid. Required unless `aria-labelledby` is given. Accessible name of the calendar grid. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the calendar. Required unless `aria-label` is given. Id of the element that names the calendar. |
| `value` | `string \| null` |  |  | The selected date as `YYYY-MM-DD`, or `null` for none. Pair with `onChange`. |
| `defaultValue` | `string \| null` |  |  | The initially selected date when uncontrolled. |
| `onChange` | `((value: string) => void)` |  |  | Called with the picked date as `YYYY-MM-DD`. |

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Calendar: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `today` | `Today` | Footer button that picks today's date. |
| `clear` | `Clear` | Footer button that empties the field. |
| `openCalendar` | `Open calendar` | Accessible name of the button that opens the calendar. |

#### Design tokens used

`--ds-accent`, `--ds-calendar-cell-size`, `--ds-calendar-today-ring-width`, `--ds-calendar-weekday-height`, `--ds-field-control-padding-inline`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-sm`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-target-min`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-text-inverse`, `--ds-weight-medium`, `--ds-weight-semibold`, `--ds-z-dropdown`

#### When to use

- A single calendar date: delivery, due date, birthday.
- `Calendar` alone for inline planners and for composing your own picker.

#### When not to use

- A date range: not supported yet (range picker is P2).
- A time of day or a timestamp: the value has no time and no time zone.
- Dates years away from now: typing the segments is faster than the grid.

#### Value contract

`value`, `defaultValue`, `onChange`, `min` and `max` are **ISO strings `YYYY-MM-DD`** (the `ISODate` type of `src/utils/date`), never `Date`. Conversion to React Aria's `CalendarDate` happens inside the component (`@internationalized/date`, see below), so the day cannot shift with the viewer's time zone. Invalid strings are treated as "no date". `onChange` receives a string only once every segment is filled, or `null` from the Clear button; an incomplete date is not reported. The form receives the ISO string under `name`.

#### Props (key ones)

| Prop                                                                                                 | Notes                                                                                                                           |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `label` / `aria-label` / `aria-labelledby`                                                           | One is required.                                                                                                                |
| `value` / `defaultValue` / `onChange`                                                                | ISO string or `null`.                                                                                                           |
| `min`, `max`                                                                                         | ISO strings. Outside days are disabled in the grid; typed dates outside are invalid. "Today" is disabled when today is outside. |
| `description`, `errorMessage`, `size`, `name`, `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly` | As in `Select`.                                                                                                                 |
| `fullWidth`                                                                                          | Take the free space of a flex row such as `Inline` (`flex: 1 1 auto`, can shrink). Off by default.                              |
| `messages`                                                                                           | `today`, `clear`, `openCalendar`, `previousMonth`, `nextMonth`, `requiredMark`.                                                 |

`Calendar` takes `value`, `defaultValue`, `onChange(iso)`, `min`, `max`, `isDisabled`, `isReadOnly`, `autoFocus`, `messages`, and requires `aria-label` or `aria-labelledby`.

#### Locale

Segment order and separators, placeholders (`dd/mm/aaaa`), month names, weekday letters and the first day of the week come from the `DSProvider` locale through React Aria; there are no hard-coded names. Only the button texts are in the message catalog (`Calendar` key for the month buttons, `DatePicker` for the rest).

#### Accessibility and keyboard

| Key (calendar grid)               | Behavior                                                      |
| --------------------------------- | ------------------------------------------------------------- |
| Arrows                            | Previous / next day, previous / next week                     |
| `PageUp` / `PageDown`             | Previous / next month                                         |
| `Shift+PageUp` / `Shift+PageDown` | Previous / next year                                          |
| `Home` / `End`                    | First / last day of the **month** (React Aria; APG says week) |
| `Enter` / `Space`                 | Select the focused day                                        |
| `Escape`                          | Close the popover, focus returns to the button                |

In the field: digits fill the segment and move to the next; arrows change a segment's value; `Backspace` clears a segment; `Tab` moves between segments. Each day is named with its full date ("Wednesday, October 28, 2026", "Today, ..."), so the grid is usable without sight. Today has a ring (`--ds-text-3`), the selected day an accent fill with `--ds-text-inverse`; disabled days are dimmed and `aria-disabled`.

#### Content rules

Label with the date's role ("Delivery date"). Errors say how to fix: "Choose a date after today."

#### Example

```tsx
<DatePicker
  label="Delivery date"
  name="delivery"
  min="2026-10-30"
  value={date}
  onChange={setDate}
/>
```

#### Dependency note

The component imports `@internationalized/date`, which React Aria already depends on. It is not a direct dependency of this package yet, so under pnpm's strict layout it must be added to `package.json` (`pnpm add @internationalized/date@^3.12.4`, already in the lockfile as a transitive dependency).

#### Related components

- Renders: IconButton

### Card

> A bordered surface that groups related content. With a `title` it is a labelled region
(`section` named by its heading).

A bordered surface that groups related content. With a `title` it is a labelled region.

- Import: `import { Card } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Card/Card.tsx`
- Stories (Storybook title `Components/Card`): Default, WithActions, Raised, WithoutTitle, HeadingLevel3, NoPadding, LongText, RightToLeft, PaperReceipt, ReceiptPreview

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` |  |  | Title shown as an uppercase mono caption. It is a real heading (see `headingLevel`) and names the card region through `aria-labelledby`. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `2` | Heading level of the title (`h1` to `h6`). Pick the level that fits the page outline. Default `2`. |
| `actions` | `ReactNode` |  |  | Controls placed at the end of the header, next to the title (buttons, a menu). |
| `variant` | `'default' \| 'raised'` |  | `'default'` | `default` is a flat surface with a border. `raised` uses the raised surface, a stronger border and the overlay shadow: use it only for a card that floats above the page (a pinned panel, a detail popover shell), never for cards that sit in the normal flow. |
| `padding` | `'md' \| 'none'` |  | `'md'` | `md` applies the card padding token; `none` removes it (for full-bleed content such as a table). Default `md`. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `default`, `raised`

#### Design tokens used

`--ds-card-gap`, `--ds-card-padding`, `--ds-font-mono`, `--ds-fs-caption`, `--ds-lh-caption`, `--ds-line`, `--ds-line-strong`, `--ds-radius-lg`, `--ds-shadow-overlay`, `--ds-space-2`, `--ds-space-3`, `--ds-surface`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-tracking-caption`, `--ds-weight-medium`

#### When to use

- Group a set of related fields, numbers or a list under one caption.
- Put page sections side by side in a grid.

#### When not to use

- To wrap a whole page: use the page layout.
- For content that interrupts the user: use `Dialog` or `Alert`.
- Do not nest a Card inside a Card; use a divider instead.
- For a card that is itself one click target (a settings category tile): use `CardLink`. For a dashed "create new" tile: use `AddCard`. `Card` is never interactive (ADR-0011); a card with inner buttons stays a `Card`.

#### Anatomy

```
section (surface + 1px line, radius lg, padding)
  header (optional)
    h{headingLevel}  mono caption, uppercase by CSS
    actions          optional controls
  children
```

#### Elevation

Borders carry hierarchy, shadows are for overlays (AGENTS.md section 5). A `raised` card gets the raised surface, a stronger border **and** `--ds-shadow-overlay`, so use it only when the card really floats (a pinned side panel, the shell of a custom popover). A card in the normal flow stays `default`.

#### Paper scope

Put `data-theme="paper"` on the `Card` to render the only light surface in the system, for receipt and PDF previews (ADR-0007). The card reads semantic tokens (`--ds-surface`, `--ds-line`, `--ds-text`), which the `[data-theme='paper']` scope remaps on the element itself, so the background, border and text switch with no extra prop. Inside it, `Text`, `Heading` and `Divider` (solid and dashed) follow the same remap; use `<Divider variant="dashed" />` for the total line.

```tsx
<Card data-theme="paper" title="Receipt #1051">
  <Text mono>$1,240.00</Text>
  <Divider variant="dashed" />
  <Text mono>Total $1,240.00</Text>
</Card>
```

Paper-safe components (axe contrast tested in the paper scope): `Card`, `Text`, `Heading`, `Divider`, plus `Badge`, `Alert` and `Button` (see the `PaperReceipt` story). A receipt or PDF component is product domain and is not part of the design system; compose these instead.

#### Accessibility

- The root is a `section`. With a `title`, the heading id is wired to `aria-labelledby`, so screen readers expose a named `region` landmark. Without a title or a label it is a plain generic container (no landmark), which is correct for decorative grouping.
- Give a title-less card an `aria-label` when it should be a landmark.
- The heading level is yours to choose: keep levels sequential (a Card inside a page with an `h1` usually uses `2`; inside another section use `3`).
- The caption uses `--ds-text-2` (the handoff used `--ds-text-3`, which drops below 4.5:1 on the raised surface).

#### Content rules

- Captions are sentence case in the source ("Storage"); uppercase is applied by CSS only.
- Keep captions to one to three words.

#### Examples

```tsx
<Card title="Storage" actions={<Button size="sm">Manage</Button>}>
  <Progress value={62} label="Used" meta="6.2 / 10 GB" />
</Card>

<Card title="Details" headingLevel={3}>…</Card>
```

#### Related components

- Instead, see Dialog: For content that interrupts the user: use `Dialog` or `Alert`.
- Instead, see Alert: For content that interrupts the user: use `Dialog` or `Alert`.
- Instead, see CardLink: For a card that is itself one click target (a settings category tile): use `CardLink`. For a dashed "create new" tile: use `AddCard`. `Card` is never interactive (ADR-0011); a card with inner buttons stays a `Card`.
- Instead, see AddCard: For a card that is itself one click target (a settings category tile): use `CardLink`. For a dashed "create new" tile: use `AddCard`. `Card` is never interactive (ADR-0011); a card with inner buttons stays a `Card`.

### CardLink

> A card whose whole surface is one link or button. The title is the real interactive
element (an `<a>` with `href`, a `<button>` with `onPress`) inside a heading, and a
stretched `::after` makes the full card its hit area. The title is the accessible name; the
description and meta are the accessible description.

Use it for navigation tiles (a settings category grid). A card that needs inner buttons is a
`Card` with a `Button` (ADR-0011).

A card whose whole surface is one link or button. Decision: [ADR-0011](../../../docs/adr/0011-interactive-cards.md).

- Import: `import { CardLink } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/CardLink/CardLink.tsx`
- Stories (Storybook title `Components/CardLink`): Default, WithLeadingAndMeta, AsButton, LongText, Disabled, Focused, ExternalLink, RightToLeft, InGrid

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | `string` | yes |  | Title of the card. It is the accessible name of the link or button, and a real heading (see `headingLevel`). Keep it to a few words ("Billing"). |
| `href` | `string` |  |  | Destination. Renders a real `<a>`; uses the router set on `DSProvider` for client-side navigation. |
| `target` | `string` |  |  | Link target. `_blank` adds `rel="noopener noreferrer"` and a hidden "opens in a new tab" note. |
| `rel` | `string` |  |  | Link relationship, merged with `noopener noreferrer` for `_blank`. |
| `onPress` | `((event: PressEvent) => void) \| ((event: PressEvent) => void)` |  |  | Fired when the link is pressed, before navigation. Action run when the card is pressed. Renders a real `<button type="button">`. |
| `description` | `ReactNode` |  |  | Supporting text. It is the accessible description (`aria-describedby`), not part of the name. Plain text only: the whole card is one interactive element, so never put links, buttons or form controls here. |
| `meta` | `ReactNode` |  |  | Small mono detail under the text ("3 members", "ORD-1048"). Same rule as `description`: no interactive content. |
| `leading` | `ReactNode` |  |  | Icon or avatar before the text. Decorative: the title names the card. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  |  | Heading level of the title (`h1` to `h6`). Pick the level that fits the page outline. Default `3`. |
| `isDisabled` | `boolean` |  |  | Disables the card: it is dimmed, skipped by `Tab` and ignores presses. |
| `messages` | `Partial<{ opensInNewTab: string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ CardLink: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `opensInNewTab` | `(opens in a new tab)` |  |

#### Design tokens used

`--ds-card-link-gap`, `--ds-card-link-text-gap`, `--ds-card-padding`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-fs-body`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-body`, `--ds-lh-meta`, `--ds-lh-small`, `--ds-line`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-surface`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`

#### When to use

- A grid of destinations, such as a settings category grid: each tile opens a page.
- A tile that runs one action (`onPress`), such as "Import data".

#### When not to use

- A card that contains its own buttons, a menu or form controls: use `Card` with a `Button` (a card can't be interactive and contain interactive content).
- A "create new" tile: use `AddCard`.
- A plain group of content: use `Card`.
- A list row: use `ActionList` or a table.

#### Anatomy

```
div (surface + 1px line, radius lg, padding, hover = raised surface)
  leading            optional icon or avatar, decorative
  div
    h{headingLevel}
      a | button     the title; its ::after stretches over the whole card
    p                description (aria-describedby)
    p                meta, mono (aria-describedby)
```

#### Accessibility

- One real `<a>` or `<button>`, in a heading, so the card shows up in the heading outline. The name is the title only; the description and meta are announced as the description.
- Keyboard: `Tab` reaches it once; `Enter` activates a link or a button, `Space` also activates a button (AGENTS.md section 8).
- Focus ring on the whole card outline, kept in `forced-colors`. Hover is one surface step lighter. Transitions are neutralized by the global reduced-motion rule.
- The target is the whole card (well above 24 px).
- Trade-off: the stretched overlay stops text selection by dragging inside the card.

#### Examples

```tsx
<Grid minItemWidth="md">
  <CardLink
    leading={<Icon icon={UsersIcon} />}
    title="Team"
    description="Members, roles and invitations."
    href="/settings/team"
  />
  <CardLink title="Import data" description="Upload a CSV file." onPress={openImport} />
  <AddCard href="/settings/new">Create category</AddCard>
</Grid>
```

#### Related components

- Instead, see Card: A card that contains its own buttons, a menu or form controls: use `Card` with a `Button` (a card can't be interactive and contain interactive content).
- Instead, see Button: A card that contains its own buttons, a menu or form controls: use `Card` with a `Button` (a card can't be interactive and contain interactive content).
- Instead, see AddCard: A "create new" tile: use `AddCard`.
- Instead, see ActionList: A list row: use `ActionList` or a table.
- Renders: VisuallyHidden

### Chart

> A responsive bar or line chart for one series, drawn in SVG.

It is a single focusable image: `Tab` focuses it, the left and right arrow keys (and Home and
End) move between data points, and each point is announced politely ("Tue: 58. 2 of 7") and
shown in a label above it. Pointer users get the same label on hover. A visually hidden
`<table>` with a caption carries the same data for assistive technology.

Limits: one series, a value axis that always includes zero, categories spaced evenly, no
zoom, no stacked or grouped bars, no legend. The axis is not mirrored in right-to-left
languages (time reads left to right in charts).

A small responsive bar or line chart for one series, drawn in SVG with no chart library. Grid and axis are quiet (dashed lines, mono labels); the data is reachable by keyboard and by a hidden table.

- Import: `import { Chart } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Chart/Chart.tsx`
- Stories (Storybook title `Components/Chart`): Default, Line, Highlight, LineHighlight, NegativeValues, Notes, LongNote, AverageLine, TargetLine, AverageAndTarget, TickEvery, ReferenceLabelAvoidsHighlight, ReferenceLabelOutside, ReferenceLabelPinned, ReferenceLabelTopRow, ReferenceLabelReport800, AnnotatedRtl, SmallValues, AllZero, SinglePoint, Empty, Tones, CustomHeight, ManyPoints, KeyboardNavigation, Hover, PortugueseBrazil

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | `readonly ChartDatum[]` | yes |  | The data, in display order (usually time). The chart does not sort. |
| `type` | `'line' \| 'bar'` |  | `'bar'` | `bar` (default) or `line`. One series per chart. |
| `format` | `(value: number) => string` |  |  | Formats values on the axis, in the tooltip, in the announcement and in the data table. Receives a number and returns text; use `formatCurrency` or `formatNumber` with the active locale. Default: `formatNumber` (compact on the axis, full in the tooltip). |
| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  | `'accent'` | Color of the active point and of the line: `accent` (default), `neutral`, `success`, `warning` or `danger`. |
| `highlight` | `Readonly<Record<number, string>>` |  |  | Marks points by index with short text, for example `{ 29: 'Today', 12: 'Best day' }`. The marked point is drawn in the strong ink color, and its text is printed above it and read by screen readers, so the highlight never depends on color. Keep the texts short. |
| `notes` | `Readonly<Record<number, string>>` |  |  | Long text about a point by index, for example `{ 12: 'Free shipping started this day.' }`. Shown under the value in the label of the active point, in the "Note" column of the hidden table and in the announcement of the point. Points with a note get a small diamond marker above them (a shape, not a color). Unlike `highlight`, the text is not printed on the chart, so it may be a full sentence. |
| `referenceLines` | `readonly ChartReferenceLine[]` |  |  | Dashed lines across the plot, each with its label printed next to the line, where it does not cover bars or other texts (see `labelPosition`). `average` and `target` differ by dash pattern and by name. Use `chartAverage(values)` for the average. The lines are listed in the description and in the last rows of the hidden table. A value outside the data range widens the axis. |
| `tickEvery` | `number` |  |  | Show the label of every nth category (`tickEvery={7}` shows 1st, 8th, 15th...). Default: automatic, labels are skipped only when they would collide. Values below 1 or not finite mean automatic. Points still get a keyboard stop and a table row. |
| `height` | `string \| number` |  |  | Height of the chart (a number is px, or any CSS length). Default `--ds-chart-height` (200px). The width is always 100% of the container. |
| `description` | `string` |  |  | Longer description of what the chart shows. Read after the name, together with the keyboard instructions. |
| `categoryLabel` | `string` |  |  | Header of the category column in the hidden data table. Default: the "Category" message. |
| `valueLabel` | `string` |  |  | Header of the value column in the hidden data table (for example "Sales"). Default: the "Value" message. |
| `messages` | `Partial<{ instructions: (count: number, formatted: string) => string; point: (label: string, value: string, position: string, count: string, note?: string) => string; tableCaption: (name?: string) => string; ... 7 more ...; empty: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `aria-label` | `string` |  |  | Accessible name of the chart: what it shows ("Sales, last 30 days"). Required unless `aria-labelledby` is set. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the chart (a visible heading). |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `tone`: `neutral`, `accent`, `success`, `warning`, `danger`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Chart: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `instructions(count: number, formatted: string)` | `{formatted} data points. Use the left and right arrow keys to move between points, Home and End for the first and last.` | Instructions linked to the chart with `aria-describedby`. `count` is the number of data points; `formatted` is the same number formatted for the locale. |
| `point(label: string, value: string, position: string, count: string, note?: string)` | `{label}: {value}, {note?}. {position} of {count}` | Announced (polite) when the user moves to a point. `value` is already formatted; `note` is the highlight text of the point, if any ("Today"). |
| `tableCaption(name?: string)` | `Data for {name?}` | Caption of the visually hidden data table. `name` is the accessible name of the chart, if it has a text one. |
| `category` | `Category` | Header of the category column of the data table, unless `categoryLabel` is given. |
| `value` | `Value` | Header of the value column of the data table, unless `valueLabel` is given. |
| `note` | `Note` | Header of the note column of the data table (shown when a point is highlighted). |
| `average` | `Average` | Name of the `average` reference line kind (dash pattern: long dashes). |
| `target` | `Target` | Name of the `target` reference line kind (dash pattern: dash and dot). |
| `referenceLine(kind: string, label: string)` | `{kind}, {label}` | Read form of one reference line, used in the description and as the row header in the data table. `kind` is the "Average" / "Target" message; `label` is the author's text. |
| `referenceSummary(items: string)` | `Reference lines: {items}.` | Sentence added to the description. `items` is the joined list of "kind, label: value". |
| `empty` | `No data to show` | Text shown inside the plot when there is no data. |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-chart-area-opacity`, `--ds-chart-bar-radius`, `--ds-chart-color`, `--ds-chart-grid-dash`, `--ds-chart-grid-gap`, `--ds-chart-height`, `--ds-chart-outline-w`, `--ds-chart-point-r`, `--ds-chart-ref-average-dash`, `--ds-chart-ref-average-gap`, `--ds-chart-ref-target-dash`, `--ds-chart-ref-target-dot`, `--ds-chart-ref-target-gap`, `--ds-chart-ref-w`, `--ds-chart-stroke-w`, `--ds-chart-tooltip-max-w`, `--ds-chart-tooltip-padding-block`, `--ds-chart-tooltip-padding-inline`, `--ds-chart-tooltip-x`, `--ds-chart-tooltip-y`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-label`, `--ds-line-control`, `--ds-line-strong`, `--ds-line-subtle`, `--ds-primary-bg`, `--ds-primary-fg`, `--ds-radius-sm`, `--ds-space-1`, `--ds-success`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- A trend or a comparison across a handful to a few dozen categories: sales per day, orders per week.
- Next to the number it explains (a `StatCard`).

#### When not to use

- Several series, stacked or grouped bars, zoom, brushing, pie charts: not supported (see limits).
- Parts of a whole: use `ProportionBar`.
- Rankings with names: use `RankList`.
- Exact values the user must read or compare: use `DataTable` (the chart is for shape).

#### Anatomy

```
div.root
  div[role=img][tabindex=0]   named by aria-label / aria-labelledby, described by the instructions
    svg[aria-hidden]          grid + tick labels, bars or line + area, reference lines + labels, category labels, highlight texts, note markers
    span                      value label of the active point (aria-hidden)
  span                        visually hidden description + keyboard instructions
  span[role=status]           visually hidden polite live region: "Tue: 58. 2 of 7"
  table (visually hidden)     caption, headers, one row per point, one footer row per reference line
```

#### Props (key ones)

| Prop                          | Type                                       | Default   | Notes                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`                        | `{ label, value }[]`                       | -         | In display order; the chart never sorts                                                                                                                                         |
| `aria-label`                  | `string`                                   | -         | Required (or `aria-labelledby`): what the chart shows                                                                                                                           |
| `type`                        | `bar \| line`                              | `bar`     |                                                                                                                                                                                 |
| `format`                      | `(value) => string`                        | `Intl`    | Axis, label, announcement and table. Default: compact on the axis, full elsewhere                                                                                               |
| `tone`                        | `ChartTone`                                | `accent`  | Color of the active bar and of the line                                                                                                                                         |
| `highlight`                   | `Record<index, string>`                    |           | `{ 29: 'Today', 12: 'Best day' }`: ink fill + outline + text above + announced                                                                                                  |
| `notes`                       | `Record<index, string>`                    |           | Long text per point: in the label of the active point, the table and the announcement; diamond marker on the point                                                              |
| `referenceLines`              | `{ value, label, kind, labelPosition? }[]` |           | Dashed lines across the plot (`kind`: `average` or `target`); the axis widens to include them. `labelPosition`: `auto` (default), `end` or `start`, see "Reference line labels" |
| `tickEvery`                   | `number`                                   | automatic | Show every nth category label. Below 1 or not finite means automatic                                                                                                            |
| `height`                      | `number \| string`                         | `200px`   | Width is always 100% of the container                                                                                                                                           |
| `description`                 | `string`                                   |           | Longer description, read before the keyboard instructions                                                                                                                       |
| `categoryLabel`, `valueLabel` | `string`                                   |           | Headers of the hidden table ("Day", "Sales")                                                                                                                                    |
| `messages`                    | `Partial<messages>`                        |           | `instructions`, `point`, `tableCaption`, `category`, `value`, `note`, `average`, `target`, `referenceLine`, `referenceSummary`, `empty`                                         |

`chartAverage(values)` is exported: the mean of numbers (or of `{ value }` data), ignoring non-finite entries, `0` when empty. Use it for the `average` line: `referenceLines={[{ kind: 'average', label: 'Average', value: chartAverage(data) }]}`.

`niceScale(min, max, tickCount?)` is exported: a pure helper that returns `{ min, max, step, ticks }` for a round axis. It always includes zero, handles all-zero data (0 to 1), tiny values (`0.00003`), huge values, negatives and non-finite input.

#### Accessibility

- The plot is one `role="img"` with an accessible name and a description; the SVG inside is hidden. The visually hidden `<table>` with a `<caption>` is the text alternative and holds every value (and the highlight texts in a "Note" column).
- Notes: a point with a `notes` entry gets a small diamond above it (a shape, not a color). Its text is shown under the value in the label of the active point (wrapping, up to `--ds-chart-tooltip-max-w`), read in the announcement after the highlight ("Tue: 58, Today. Free shipping started. 2 of 7") and written in the "Note" column of the table. When a point has both, the cell reads "Today. Free shipping started."; the table gets the Note column as soon as any point has a highlight or a note.
- Reference lines: dashed across the plot with the label and the formatted value as text at the end side of the line ("Goal 120"). `average` uses long dashes, `target` dash and dot, so the kind never depends on color; the line and the text use `text-2`. Screen readers get them in the description ("Reference lines: Average, Weekly mean: 51.5 and Target, Goal: 120.") and in the footer rows of the table ("Average, Weekly mean" / "51.5"). If the label already starts with the kind name as a whole word ("Average per open day", pt-BR "Média por dia aberto"; compared ignoring case and accents in the active locale), only the label is read, so the kind is never said twice. Where the text is printed never changes what is read (see "Reference line labels").
- Axis labels: by default category labels are skipped automatically when they would collide; `tickEvery` forces every nth label (1 shows all, even if they touch). The keyboard and the table always reach every point.
- Keyboard: `Tab` focuses the chart (nothing announced yet). Left/Right (also Up/Down) move to the previous/next point, Home/End to the first/last, Escape clears the active point. The first Right arrow goes to the first point, the first Left arrow to the last. Movement stops at the ends.
- The active point is announced politely ("Tue: 58, Today. 2 of 7") and drawn as a label above it; hover shows the same label. The label is also in the SVG as text, never color-only.
- Highlights always carry text and a stronger shape (outline on bars, a ring marker on lines), so they do not depend on color. Active bars get a tone fill and outline.
- Bars use `line-control` (3:1 against the surface); tick labels use `text-3` (above 4.5:1 on `bg` and `surface`).
- Reduced motion: color transitions only apply when motion is allowed. Forced colors: bars, lines and labels switch to system colors (`GrayText`, `CanvasText`, `Highlight`).
- The chart does not mirror in right-to-left languages (time still runs left to right); the label position uses physical coordinates on purpose.

#### Reference line labels

The text of a reference line ("Average $1.8K") is placed where it does not cover the bars, the line, a highlight text ("Today"), a note marker or the text of another reference line. With `labelPosition: 'auto'` (the default) the chart tries, in order:

1. the end of the line, above it (the usual place, used whenever it is clear);
2. the start of the line, above it;
3. the end, then the start, below the line;
4. outside the plot, on the end side, level with its line: the plot gives up the width of the text. This happens when bars cross the line at both ends, as in a 90-day report whose last bar is the tallest. Texts of nearby lines are moved apart there. Skipped when the margin would take more than 40% of the chart width, would hide category labels that all fit before, or would touch a highlight text that reaches past the last bar;
5. in a row above the plot, aligned to the end side, after a short sample of the line in its dash pattern (like a legend): the plot gives up the height of the row. Nothing else is drawn there, so the text never covers anything. Several texts sit side by side and wrap onto more rows. This is the usual result for a long label in a narrow chart, such as "Média por dia aberto R$ 1.611,98" in a 470 px report.

With `auto` the text never covers a bar, the line, a point, a highlight text or another reference text.

`labelPosition: 'end'` or `'start'` pins the text to that end of the line: above it, or below it when above is taken, and never outside. Use it only when the position must stay fixed across data, since the text may then cover bars.

The accessible name, the description and the hidden table are the same wherever the text is printed. The placement uses estimated text boxes (caption mono); the browser tests measure the real boxes at 470, 800 and 1366 px with 30 and 90 points.

#### Content rules

- Reference line labels: either a short name that adds to the kind ("Goal", "Weekly mean"; read as "Target, Goal") or a full name that starts with the kind ("Average per open day"; read as written). Do not put the kind in the middle or the end of the label ("Daily average" is read "Average, Daily average"). The visible text is always the label alone.
- Name says what and when: "Sales, last 30 days". Labels are short ("Mon", "28") because they are printed under the plot.
- Highlight texts are one or two words ("Today", "Best day").
- Format money with `formatCurrency` (integer minor units) and the active locale; never hand-build strings.

#### Limits

- One series per chart. For two series use two charts side by side.
- Categories are spaced evenly (no time scale); labels are skipped when crowded unless `tickEvery` is set (the table and the keyboard still reach every point).
- Reference lines are horizontal only. Their labels avoid marks (see "Reference line labels"); only a pinned `labelPosition` can cross bars (the text carries a background-colored halo).
- The value axis always includes zero, and reference line values (a target far above the data, for example) widen it. Up to about 100 ticks are generated at most (usually 4 to 7).
- Geometry (padding, bar width, label spacing) lives in `chartLayout.ts` as SVG units; every color, stroke, radius and font is a token.

#### Example

```tsx
<Chart
  aria-label="Sales, last 30 days"
  type="bar"
  data={days.map((d) => ({ label: d.day, value: d.totalMinor }))}
  format={(v) => formatCurrency(v, 'USD', locale)}
  highlight={{ 29: 'Today', [bestIndex]: 'Best day' }}
  notes={{ [bestIndex]: 'Free shipping campaign started this day.' }}
  referenceLines={[
    { kind: 'average', label: 'Average', value: chartAverage(days.map((d) => d.totalMinor)) },
    { kind: 'target', label: 'Goal', value: 500000 },
  ]}
  tickEvery={7}
/>
```

#### Related components

- Instead, see ProportionBar: Parts of a whole: use `ProportionBar`.
- Instead, see RankList: Rankings with names: use `RankList`.
- Instead, see DataTable: Exact values the user must read or compare: use `DataTable` (the chart is for shape).
- Renders: VisuallyHidden

### ChatPanel

> A chat side panel for talking to an agent: header with Clear, a message log, suggested prompts
when empty, and a composer. Built for streaming replies.

Live-region approach: the message list is `role="log"` (a navigable transcript) with
`aria-live="off"`, so partial text never reaches a screen reader token by token. A separate
visually hidden `role="status"` region announces "Thinking…", "The assistant is responding",
and then the full reply once, when it is complete.

Message content is plain text. Pass `renderContent` to render sanitized markdown.

A chat panel for talking to an agent: header with a Clear action, a message log, suggested prompts when empty, and a composer. It supports streaming replies, Stop and Retry. Import it from `loui-ds/patterns`.

- Handoff source: `components/agents/ChatPanel` (TODO `CMP-AGT-03`; groundwork for `AI-013`).

- Import: `import { ChatPanel } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/ChatPanel/ChatPanel.tsx`
- Stories (Storybook title `Patterns/ChatPanel`): Empty, Conversation, Busy, WithoutIds, CustomBusyLabel, Streaming, ErrorWithRetry, PrimarySend, LongConversation, LongText, CustomRenderer, RightToLeft, InteractiveStreaming, InteractiveError

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly ChatMessage[]` | yes |  | The conversation, oldest first. Update `content` and `status` of the last item as a reply streams in. |
| `title` | `ReactNode` |  |  | Heading of the panel. Defaults to the "Chat with the agent" message. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `2` | Heading level of the title (`h1` to `h6`). Default `2`. |
| `busy` | `boolean` |  | `false` | Waiting for the first part of a reply: shows a spinner with "Thinking…" and disables sending. |
| `busyLabel` | `string` |  |  | Text shown next to the busy indicator and announced while waiting ("Searching orders…"). Defaults to the "Thinking…" message. |
| `busyIndicator` | `ReactNode` |  |  | Replaces the default `Spinner` of the busy row. Decorative: the busy text is `busyLabel`. Pass `null` to show the text only. |
| `getKey` | `(message: ChatMessage, index: number) => string` |  |  | Key of a message, used as the React key and to tell history from news. Must be unique and stable for the same message across renders. Default: `message.id` when present, otherwise the role plus the position among messages of the same role (`user-0`, `assistant-1`), which breaks if you insert or remove messages before the end. Pass `getKey` (or give each message an `id`) whenever the list is not append-only. |
| `intro` | `ReactNode` |  |  | Short text shown while the conversation is empty. |
| `prompts` | `readonly string[]` |  | `[]` | Suggested prompts shown while the conversation is empty. Pressing one sends it. |
| `placeholder` | `string` |  |  | Placeholder of the composer. Never a substitute for its label. |
| `onSend` | `(text: string) => void` |  |  | Called with the trimmed text when the user sends (Enter, or the send button) or presses a suggested prompt. |
| `onStop` | `() => void` |  |  | Called when the user stops a reply that is being generated. Without it the button is disabled meanwhile. |
| `onRetry` | `(message: ChatMessage) => void` |  |  | Called with the failed message when the user presses Retry. Without it, failed messages have no Retry. |
| `onClear` | `() => void` |  |  | Called when the user clears the conversation. Without it there is no Clear button. |
| `renderContent` | `(message: ChatMessage) => ReactNode` |  |  | Renders the content of a message. Use it to plug in a markdown renderer. Whatever it returns is rendered as-is, so it must be **sanitized**: the design system never uses `dangerouslySetInnerHTML` and ships no markdown library. Without it the content is plain text with line breaks preserved. |
| `sendVariant` | `'primary' \| 'secondary'` |  | `'secondary'` | Visual weight of the send button: `secondary` (default) for a chat that sits beside the page's main task, `primary` when the chat is the main task of the page. One primary per screen. |
| `messages` | `Partial<{ title: string; clear: string; transcript: string; composerLabel: string; placeholder: string; send: string; stop: string; thinking: string; responding: string; you: string; assistant: string; ... 5 more ...; errorSaid: (text: string) => string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ ChatPanel: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `title` | `Chat with the agent` | Default heading of the panel. |
| `clear` | `Clear conversation` | Clear button in the header. |
| `transcript` | `Conversation` | Accessible name of the message list (`role="log"`). |
| `composerLabel` | `Message` | Accessible name of the composer field. |
| `placeholder` | `Ask or request something` | Default placeholder of the composer. |
| `send` | `Send message` | Composer button while it can send, and while the assistant is working (it stops). |
| `stop` | `Stop generating` |  |
| `thinking` | `Thinking…` | Visible busy text and the announcement while waiting for the first part of a reply. |
| `responding` | `The assistant is responding` | Announcement when a reply starts streaming. The text itself is announced once, when complete. |
| `you` | `You` | Visually hidden author prefix of each message. |
| `assistant` | `Assistant` |  |
| `error` | `Error` |  |
| `retry` | `Retry` | Retry button of a failed reply. |
| `jumpToLatest` | `Jump to latest` | Shown while the list is scrolled away from the latest message. |
| `suggestions` | `Suggested prompts` | Accessible name of the group of suggested prompts. |
| `assistantSaid(text: string)` | `Assistant: {text}` | Announcements made when a reply is complete or failed. |
| `errorSaid(text: string)` | `Error: {text}` |  |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-chat-panel-bubble-max-ratio`, `--ds-chat-panel-composer-padding`, `--ds-chat-panel-gap`, `--ds-chat-panel-header-height`, `--ds-chat-panel-padding-block`, `--ds-chat-panel-padding-inline`, `--ds-danger`, `--ds-danger-line`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-sans`, `--ds-fs-body`, `--ds-fs-label`, `--ds-lh-body`, `--ds-lh-label`, `--ds-line`, `--ds-line-control`, `--ds-line-subtle`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-md`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-surface`, `--ds-surface-hover`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-semibold`

#### When to use

- A side panel where the owner tests an agent, asks why it did something or asks for an adjustment.
- Any short, owner-facing conversation with an assistant.

#### When not to use

- Customer-facing conversations: the chat is for the owner. Anything that goes to a customer must pass through an approval queue (`ApprovalCard`), never straight from the chat.
- A one-shot prompt with a single answer: use a form.
- Rich documents as replies: render those in the page and keep the chat short.

#### Anatomy

```
section (named by the heading)
  header          h{headingLevel} title + Clear (ghost, only with messages and onClear)
  viewport
    div[role=log][aria-live=off][tabindex=0]
      intro + suggested prompts (group)    only while empty
      message rows (user right, assistant left, error with Retry)
      "Thinking…" row                      while busy or a reply has no text yet
    Jump to latest                         only when scrolled away from the end
  div[role=status][aria-live=polite]       visually hidden announcer
  composer        Textarea (Enter sends) + one button: Send message | Stop generating
```

#### Streaming and live regions (research notes)

Sources: practitioner write-ups on accessible streaming chat UIs (azukiazusa.dev, tianpan.co), an IDE chat-panel pull request (TrixtyAI/ide#172) and the WAI-ARIA `log` role. There is no formal standard for streamed AI output; this is current practice, not tested with every screen reader.

- `role="log"` is the right role for a chat transcript (implicit polite live region, history in reading order). But a streamed reply rewrites one node many times, and a live region then reads it in fragments (or repeats it).
- Common practice (and what chat products do): keep the streaming text **out** of the live region, announce a short status while it generates, and announce the result once when complete.

What `ChatPanel` does:

1. The list is `role="log"` with `aria-live="off"`: a labelled, focusable (`tabindex=0`, so it can be scrolled with the keyboard) transcript that screen reader users can read in order, without automatic announcements. It sets `aria-busy` while a reply is being produced.
2. A separate visually hidden `role="status"` (polite, atomic) announces: **"Thinking…"** while `busy`, **"The assistant is responding"** while a message is `streaming` (one announcement, not one per token), and **"Assistant: <full reply>"** once when the message becomes `complete` (or **"Error: …"** when it fails).
3. The user's own messages are never announced (they just typed them). Messages present on first render are history and are not announced.
4. The author ("You", "Assistant", "Error") is a visually hidden prefix of every message, since alignment and color are the only visual cue.

Not done: a "regenerate" action (only Retry for failed replies), and chunked announcements for very long replies.

#### Behavior

- **Composer.** Enter sends, Shift+Enter inserts a new line. Enter is ignored while an **IME composition** is active (`isComposing`, and `keyCode 229` for Safari), so committing a CJK candidate never sends. Whitespace-only text is not sent. The field is not disabled while the assistant works, so the user can prepare the next message; sending is disabled meanwhile.
- **Send / Stop.** One button changes its label and action (Send message, Stop generating), so keyboard focus is not lost when a reply starts. With no `onStop` it is disabled while working.
- **Scroll anchoring.** The list follows new content only while the user is within a small distance of the bottom. If they scroll up to read, nothing moves, and "Jump to latest" appears. Sending a message returns to the bottom. No smooth scrolling is used, so `prefers-reduced-motion` needs no special handling; the spinner is already static under reduced motion.
- **Suggested prompts** send immediately. The chat is owner-facing and nothing leaves it.

#### Send button: secondary by default

The panel normally sits beside the page's main task (an agent screen), and the screen already has its one primary action, so Send is `secondary`. When the chat is the main task of the page, pass `sendVariant="primary"`. One primary per screen.

#### Content policy: plain text by default

Messages render as **plain text with line breaks**. The design system never uses `dangerouslySetInnerHTML` and ships no markdown library. To show markdown, pass `renderContent` and return **React elements** from a renderer that sanitizes its input (a markdown-to-React library that does not allow raw HTML, with an allow-list of elements and URL schemes). `renderContent` runs for every message, including while it streams, so it must tolerate incomplete markdown. The story "CustomRenderer" shows the shape.

#### Accessibility

- Region named by its heading; composer named "Message"; prompts in a group named "Suggested prompts"; Clear and Retry are real buttons.
- Keyboard: Tab order is header (Clear), the log (scroll with arrows and Page keys), Jump to latest when shown, composer, the Send/Stop button. Prompts are buttons in the log while empty.
- Error messages use text ("Error:" prefix, hidden), a danger border and danger text: color is never the only cue.
- Forced colors: the borders and focus use system colors through the shared tokens (outlines are transparent, not removed).

#### Content rules

- Title and buttons are sentence case, verb plus object: "Clear conversation", "Send message", "Stop generating".
- Errors say how to fix: "The agent could not answer. Check your connection and try again."
- The agent never sends anything to a customer from this chat.

#### Examples

```tsx
function AgentChat() {
  const [items, setItems] = useState<ChatMessage[]>([]);
  const [busy, setBusy] = useState(false);
  // onSend: append the user message, set busy, then append an assistant message with
  // status 'streaming' and grow its content; set status 'complete' (or 'error') at the end.
  return (
    <ChatPanel
      items={items}
      busy={busy}
      intro="Test replies or ask for changes."
      prompts={['Summarize today’s questions']}
      onSend={ask}
      onStop={abort}
      onRetry={retry}
      onClear={() => setItems([])}
    />
  );
}
```

#### Related components

- Instead, see ApprovalCard: Customer-facing conversations: the chat is for the owner. Anything that goes to a customer must pass through an approval queue (`ApprovalCard`), never straight from the chat.
- Renders: Button, Spinner, Textarea, VisuallyHidden

### Checkbox

> A checkbox with a native `<input type="checkbox">` (so `name` / `value` take part in form
submission), an 18px box and an optional description. The whole label row is the click target.

State props follow React Aria: `isSelected`, `defaultSelected` and `onChange(isSelected)`.
`isIndeterminate` is visual and semantic ("mixed") until the user toggles it.

A checkbox with a native `<input type="checkbox">`, an 18px box and an optional description, plus a labelled group for several related checkboxes. Built on React Aria `CheckboxField` + `CheckboxButton` (the non-deprecated pair that supports a description and an error outside the label) and `CheckboxGroup`. Shared field behavior is in [Field](../Field/Field.md).

- Import: `import { Checkbox } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Checkbox/Checkbox.tsx`
- Stories (Storybook title `Components/Checkbox`): Default, Checked, Indeterminate, WithDescription, Required, Invalid, Disabled, ReadOnly, LongLabel, WithoutVisibleLabel, InAGroup, GroupHorizontal, GroupInvalid

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | `ReactNode` |  |  | Secondary text under the label. Linked with `aria-describedby`, not part of the name. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, for example "Accept the terms to continue". Shown while the checkbox is invalid and the error is displayed (after a submit attempt with the default native validation). Inside a `CheckboxGroup` put the error on the group instead. |
| `className` | `string` |  |  | Class name for the field root. |
| `messages` | `Partial<{ requiredMark: string; }>` |  |  | Message overrides for this instance (`requiredMark`). |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. Use `inputRef` for the `<input>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaToggleProps` (react-aria): `aria-controls`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `CheckboxFieldProps` (react-aria-components): `inputRef`
- From `CheckboxProps` (react-aria): `isIndeterminate`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `ToggleProps` (react-stately): `value`
- From `ToggleStateOptions` (react-stately): `defaultSelected`, `isSelected`, `onChange`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-checkbox-box-size`, `--ds-checkbox-radius`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-choice-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-fs-small`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-space-1`, `--ds-space-3`, `--ds-space-5`, `--ds-target-min`, `--ds-text`, `--ds-text-3`, `--ds-text-inverse`

#### When to use

- Independent yes/no choices, agreement ("I accept the terms"), selecting rows, picking several items from a list (`CheckboxGroup`).
- `isIndeterminate` for a parent that summarizes partly selected children.

#### When not to use

- An on/off setting that applies at once: `Switch`.
- One choice from several: `RadioGroup`.

#### Props (key ones)

| Prop                                                      | Notes                                                                                            |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `label`                                                   | Visible label. Without it pass `aria-label` or `aria-labelledby` (type error otherwise).         |
| `description`                                             | Secondary text under the label, linked by `aria-describedby`, not part of the name.              |
| `errorMessage`                                            | Error for a single checkbox (for example a required agreement). In a group, set it on the group. |
| `isSelected` / `defaultSelected` / `onChange(isSelected)` | React Aria naming for controlled and uncontrolled use.                                           |
| `isIndeterminate`                                         | Shows a minus; the native input is `indeterminate` until toggled.                                |
| `name`, `value`                                           | Submitted with the form while checked (`value` defaults to `on`).                                |
| `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly`     | Standard states.                                                                                 |
| `inputRef` / `ref`                                        | `inputRef` is the `<input>`, `ref` the field root.                                               |

`CheckboxGroup` takes `label`, `description`, `errorMessage`, `orientation` (`vertical` default, `horizontal`), `name`, `value`/`defaultValue`/`onChange(values: string[])`, `isRequired`, `isInvalid`, `isDisabled`. Each child `Checkbox` needs a `value`.

#### Look

- 18px box, radius from `--ds-checkbox-radius` (5px), `--ds-line-control` border (3:1 or better in every state), accent fill with a `--ds-text-inverse` check when selected, minus when indeterminate.
- Hover brightens the border; it never changes the fill.
- The whole row is the click target and is at least 24px tall (WCAG 2.5.8).
- A disabled group dims once as a whole; disabled single checkboxes use `--ds-opacity-disabled`.

#### Accessibility

- Space toggles the focused checkbox. Tab moves between checkboxes; each checkbox is a tab stop.
- Name comes from the label only; the description is `aria-describedby`.
- Group: `role="group"` named by the label, with the group description and error.
- Forced colors: borders and the check glyph use system colors; the glyph (check or minus) carries the state.

#### Example

```tsx
<Checkbox label="I accept the terms" name="terms" isRequired errorMessage="Accept the terms to continue." />

<CheckboxGroup label="Notify me about" name="topics" defaultValue={['orders']}>
  <Checkbox value="orders" label="New orders" />
  <Checkbox value="stock" label="Low stock" description="When a product drops below its minimum." />
</CheckboxGroup>
```

#### Related components

- Instead, see Switch: An on/off setting that applies at once: `Switch`.
- Instead, see RadioGroup: One choice from several: `RadioGroup`.
- Renders: FieldMessages, Icon, RequiredMark
- Used by: ActionList, DataTable

### CheckboxGroup

> A labelled `role="group"` of checkboxes that share one value (`string[]`), one `name`, and
one description and error. `value`, `defaultValue` and `onChange(values)` follow React Aria.

A checkbox with a native `<input type="checkbox">`, an 18px box and an optional description, plus a labelled group for several related checkboxes. Built on React Aria `CheckboxField` + `CheckboxButton` (the non-deprecated pair that supports a description and an error outside the label) and `CheckboxGroup`. Shared field behavior is in [Field](../Field/Field.md).

- Import: `import { CheckboxGroup } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Checkbox/CheckboxGroup.tsx`
- Stories (Storybook title `Components/Checkbox`): Default, Checked, Indeterminate, WithDescription, Required, Invalid, Disabled, ReadOnly, LongLabel, WithoutVisibleLabel, InAGroup, GroupHorizontal, GroupInvalid

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | The `Checkbox` elements of the group. Each needs a `value`. |
| `description` | `ReactNode` |  |  | Helper text under the label. Linked with `aria-describedby`. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text for the group, shown while it is invalid and the error is displayed. |
| `orientation` | `'vertical' \| 'horizontal'` |  | `'vertical'` | Layout of the checkboxes. Default `vertical`. |
| `className` | `string` |  |  | Class name for the group root. |
| `messages` | `Partial<{ requiredMark: string; }>` |  |  | Message overrides for this instance (`requiredMark`). |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the group root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- From `ValueBase` (@react-types/shared): `defaultValue`, `onChange`, `value`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-checkbox-box-size`, `--ds-checkbox-radius`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-choice-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-fs-small`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-space-1`, `--ds-space-3`, `--ds-space-5`, `--ds-target-min`, `--ds-text`, `--ds-text-3`, `--ds-text-inverse`

#### When to use

- Independent yes/no choices, agreement ("I accept the terms"), selecting rows, picking several items from a list (`CheckboxGroup`).
- `isIndeterminate` for a parent that summarizes partly selected children.

#### When not to use

- An on/off setting that applies at once: `Switch`.
- One choice from several: `RadioGroup`.

#### Props (key ones)

| Prop                                                      | Notes                                                                                            |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `label`                                                   | Visible label. Without it pass `aria-label` or `aria-labelledby` (type error otherwise).         |
| `description`                                             | Secondary text under the label, linked by `aria-describedby`, not part of the name.              |
| `errorMessage`                                            | Error for a single checkbox (for example a required agreement). In a group, set it on the group. |
| `isSelected` / `defaultSelected` / `onChange(isSelected)` | React Aria naming for controlled and uncontrolled use.                                           |
| `isIndeterminate`                                         | Shows a minus; the native input is `indeterminate` until toggled.                                |
| `name`, `value`                                           | Submitted with the form while checked (`value` defaults to `on`).                                |
| `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly`     | Standard states.                                                                                 |
| `inputRef` / `ref`                                        | `inputRef` is the `<input>`, `ref` the field root.                                               |

`CheckboxGroup` takes `label`, `description`, `errorMessage`, `orientation` (`vertical` default, `horizontal`), `name`, `value`/`defaultValue`/`onChange(values: string[])`, `isRequired`, `isInvalid`, `isDisabled`. Each child `Checkbox` needs a `value`.

#### Look

- 18px box, radius from `--ds-checkbox-radius` (5px), `--ds-line-control` border (3:1 or better in every state), accent fill with a `--ds-text-inverse` check when selected, minus when indeterminate.
- Hover brightens the border; it never changes the fill.
- The whole row is the click target and is at least 24px tall (WCAG 2.5.8).
- A disabled group dims once as a whole; disabled single checkboxes use `--ds-opacity-disabled`.

#### Accessibility

- Space toggles the focused checkbox. Tab moves between checkboxes; each checkbox is a tab stop.
- Name comes from the label only; the description is `aria-describedby`.
- Group: `role="group"` named by the label, with the group description and error.
- Forced colors: borders and the check glyph use system colors; the glyph (check or minus) carries the state.

#### Example

```tsx
<Checkbox label="I accept the terms" name="terms" isRequired errorMessage="Accept the terms to continue." />

<CheckboxGroup label="Notify me about" name="topics" defaultValue={['orders']}>
  <Checkbox value="orders" label="New orders" />
  <Checkbox value="stock" label="Low stock" description="When a product drops below its minimum." />
</CheckboxGroup>
```

#### Related components

- Instead, see Switch: An on/off setting that applies at once: `Switch`.
- Instead, see RadioGroup: One choice from several: `RadioGroup`.
- Renders: FieldMessages, Label

### ChoiceTiles

> Single-choice tiles: a `radiogroup` whose options are drawn as big buttons with a label and an
optional meta line. The group is one tab stop; arrow keys move focus and select, `Space`
selects (React Aria roving focus; arrows wrap at the ends like any radio group).
`value`, `defaultValue` and `onChange(value)` follow React Aria. A group needs a name: pass
`label`, `aria-label` or `aria-labelledby`.

For a few short options drawn as one bar, use `SegmentedControl`; for a plain list of
options, use `RadioGroup`.

Single-choice tiles: a labelled group where the options are drawn as large buttons with a label and an optional meta line. Built on React Aria `RadioGroup` with custom radio buttons, so it is a real `radiogroup` with roving focus.

- Handoff source: `components/erp/ChoiceTiles.jsx` (TODO `CMP-PAT-08`).

- Import: `import { ChoiceTiles } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/ChoiceTiles/ChoiceTiles.tsx`
- Stories (Storybook title `Components/ChoiceTiles`): Default, Selected, Medium, ThreeColumns, WithDetail, WithoutMeta, DisabledTile, DisabledGroup, WithDescription, Invalid, Required, LongText, NarrowContainer, RightToLeft, KeyboardSelection, Controlled, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `options` | `readonly ChoiceTilesOption[]` | yes |  | The tiles, in display order. Two to eight fit well. |
| `description` | `ReactNode` |  |  | Helper text under the label. Linked with `aria-describedby`. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while the group is invalid. |
| `columns` | `number` |  | `2` | Maximum number of columns. Default `2`. The grid collapses to fewer columns on narrow containers so a tile never gets narrower than `--ds-choice-tiles-min-width`. |
| `size` | `'md' \| 'lg'` |  | `'lg'` | Tile height: `md` 40px or `lg` 48px (default). |
| `className` | `string` |  |  | Class name for the group root. |
| `messages` | `Partial<{ requiredMark: string; }>` |  |  | Message overrides for this instance (`requiredMark`). |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the group root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- From `ValueBase` (@react-types/shared): `defaultValue`, `onChange`, `value`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `md`, `lg`

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-bg`, `--ds-choice-tiles-columns`, `--ds-choice-tiles-gap`, `--ds-choice-tiles-height-lg`, `--ds-choice-tiles-height-md`, `--ds-choice-tiles-min-width`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-1`, `--ds-space-3`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- A choice with 2 to 8 short options where each option deserves weight: delivery method, plan, size, payment type.
- When a secondary fact helps decide (a price, a duration, a code): use `meta`.

#### When not to use

- For a view mode or a small filter: use `SegmentedControl`.
- For a long list of options or long descriptions: use `RadioGroup` (with descriptions) or `Select`.
- For several selections at once: use `CheckboxGroup` or `TagGroup`.

#### Anatomy

```
div[role=radiogroup] aria-labelledby=label
  label                      (group label, from `label`)
  div.grid                   (responsive grid, at most `columns` columns)
    div > label.tile         (one per option; hidden native radio inside)
      label text
      meta                   (optional, mono; text or a short inline node)
      detail                 (optional second line, body font; the radio's description)
  description / error
```

#### Accessibility

- Semantics: `radiogroup` of native radio inputs; the tile is the radio's label.
- Keyboard: one tab stop; arrows (`←` `↑` previous, `→` `↓` next) move focus and select, wrapping at the ends; `Space` selects the focused tile. Disabled tiles are skipped.
- State is not color alone: the selected tile has a doubled (2px) accent border, a soft fill and ink text, and screen readers get "checked".
- Boundaries: unselected tiles use `--ds-line-control` (3:1) and hover brightens the border instead of changing the fill, so the 3:1 holds in every state. The meta line uses `--ds-text-2` (`--ds-text-3` fails 4.5:1 on the selected fill).
- Focus: accent border plus ring. Forced colors: the selected border uses `Highlight`.

- `detail` is linked with `aria-describedby`: the radio's name stays the label plus the meta, and the detail is read after it as the description. Use it for a short helpful sentence, not for essential text.

#### Content rules

- Labels in sentence case, one to three words. Put the differentiating fact in `meta`, not in the label.
- Keep the same shape across tiles: avoid `meta` on some tiles only.

#### Examples

```tsx
<ChoiceTiles
  label="Delivery"
  columns={2}
  options={[
    { value: 'standard', label: 'Standard', meta: '3-5 days' },
    { value: 'express', label: 'Express', meta: '1 day' },
  ]}
  value={method}
  onChange={setMethod}
/>
```

#### Related components

- Instead, see SegmentedControl: For a view mode or a small filter: use `SegmentedControl`.
- Instead, see RadioGroup: For a long list of options or long descriptions: use `RadioGroup` (with descriptions) or `Select`.
- Instead, see Select: For a long list of options or long descriptions: use `RadioGroup` (with descriptions) or `Select`.
- Instead, see CheckboxGroup: For several selections at once: use `CheckboxGroup` or `TagGroup`.
- Instead, see TagGroup: For several selections at once: use `CheckboxGroup` or `TagGroup`.
- Renders: FieldMessages, Label

### Citation

> An inline marker for a claim in an answer. It is a real link (`href="#..."`) that moves
focus to the matching source in the `SourceList`, so it works with a keyboard and a screen
reader: the name is "Source 2: Title", the visible text is the number.

The numbered list of sources an answer is based on (`SourceList`) and the inline markers that point to it (`Citation`). Import both from `loui-ds/patterns`.

- Import: `import { Citation } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/SourceList/SourceList.tsx`
- Stories (Storybook title `Patterns/SourceList`): Default, LongText, RightToLeft, WithCitations

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `number` | `number` | yes |  | Position of the source in the list, starting at 1. Shown as the marker text. |
| `title` | `string` | yes |  | Title of the source. Part of the accessible name ("Source 2: Title"). |
| `listId` | `string` | yes |  | Id of the `SourceList` the source belongs to. |
| `sourceId` | `string` | yes |  | Id of the source (`Source.id`). |
| `messages` | `Partial<{ title: string; citation: (number: number, title: string) => string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ SourceList: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `title` | `Sources` | Default heading of the source list. |
| `citation(number: number, title: string)` | `Source 2: {title}` | Accessible name of a citation marker: "Source 2: Title". |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-citation-size`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-line-control`, `--ds-radius-sm`, `--ds-source-list-gap`, `--ds-source-list-indent`, `--ds-source-list-padding`, `--ds-space-1`, `--ds-space-2`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`, `--ds-weight-semibold`

#### When to use

- An assistant answer that rests on documents, pages or records, and the owner should be able to check them.

#### When not to use

- Footnotes in long-form documents: use plain links.
- A list of results the user searched for: use a table or a list of cards.

#### Anatomy

```
p            ... a claim [2] ...        Citation: <a href="#s-source-b" aria-label="Source 2: Title">2</a>
section      named by its heading ("Sources")
  ol
    li       tabIndex=-1 (focus target)    title (link when it has a url) · domain (mono) · snippet
```

#### Accessibility

- A citation is a real link (`href="#..."`) named "Source 2: Title"; the visible text is the number, which the name contains.
- Activating it moves focus to the matching list item and scrolls it into view. It does not change the URL hash, so it does not fight your router. Without JavaScript the hash link still works.
- Source titles with a `url` are links that open in a new tab (with the external-link icon and a screen-reader note).
- The marker is 24 px square (WCAG 2.5.8).

#### Content rules

- Keep source order stable while the answer streams; append new sources at the end, so numbers already shown never change.
- Titles say what the page is, not "Click here". Snippets are short, plain text.

#### Example

```tsx
<p>
  Orders move through four statuses
  <Citation number={1} title="Order lifecycle" listId="answer-1" sourceId="lifecycle" />.
</p>
<SourceList
  id="answer-1"
  sources={[{ id: 'lifecycle', title: 'Order lifecycle', url: 'https://example.com/orders' }]}
/>
```

#### Related components

- Renders: Link

### Code

> Monospace code: inline in a sentence, or as a block (`pre` + `code`). A block that overflows
becomes a keyboard stop and a labelled region so it can be scrolled without a mouse.
It does not highlight syntax.

Monospace code: inline in a sentence, or a block (`pre` + `code`).

- Import: `import { Code } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Code/Code.tsx`
- Stories (Storybook title `Typography/Code`): Default, Block, BlockScrolls, InlineLongToken, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | `'inline' \| 'block'` |  | `'inline'` | `inline` (default) is a `code` element inside running text. `block` renders a `pre` with a `code` inside it, keeps the whitespace, and scrolls sideways instead of wrapping. |
| `aria-label` | `string` |  |  | Block only. Accessible name of the block when it scrolls and becomes a region. Defaults to "Code" from the message catalog; say what the code is when there are several ("Request body"). |
| `messages` | `Partial<{ blockLabel: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `inline`, `block`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Code: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `blockLabel` | `Code` | Accessible name of a scrollable code block (a labelled region), when the consumer gives none. |

#### Design tokens used

`--ds-accent`, `--ds-code-inline-padding-block`, `--ds-font-mono`, `--ds-fs-label`, `--ds-lh-small`, `--ds-line`, `--ds-line-control`, `--ds-line-subtle`, `--ds-radius-md`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-3`, `--ds-space-4`, `--ds-surface`, `--ds-text`

#### When to use

- Commands, identifiers, file names and short snippets in documentation or help text.
- A block for several lines, such as a request example.

#### When not to use

- For data values in the UI (IDs, amounts, shortcuts): use `Text mono`, or `Kbd` for a key.
- For syntax highlighting or a copy button: not part of this component.

#### Anatomy

```
code                 inline
pre > code           block (scrolls sideways, keeps whitespace)
```

#### Accessibility

- A block that overflows horizontally gets `tabindex="0"` and `role="region"` with a name, so keyboard users can scroll it (WCAG 2.1.1). A block that fits is a plain `pre`.
- Inline code wraps anywhere (`overflow-wrap: anywhere`) so a long token does not overflow at 320px.
- Block text is `--ds-text` on `--ds-surface` (≥ 4.5:1).

#### Internationalization

`blockLabel` has English and `pt-BR` ("Código") strings. Override per instance (`messages`), through `DSProvider`, or with `aria-label`.

#### Examples

```tsx
<p>Run <Code>pnpm check</Code> before you push.</p>

<Code variant="block" aria-label="Request example">
  {`curl -X POST https://api.example.com/v1/orders`}
</Code>
```

#### Related components

- Instead, see Kbd: For data values in the UI (IDs, amounts, shortcuts): use `Text mono`, or `Kbd` for a key.
- Used by: ToolCallStep

### ColorField

> A hex colour field: a text input in Geist Mono with a `Swatch` preview of the current colour,
built on React Aria `ColorField`. Type `#abc` or `aabbcc` and the value is normalised to
`#AABBCC` on blur or `Enter`; text that is not a colour is reverted on blur. `ArrowUp` /
`ArrowDown` step the value by one.

`value` / `defaultValue` accept a `#RRGGBB` string or a React Aria `Color`; `onChange`
receives a `Color` or `null` when the field is empty. Read the hex with
`color?.toString('hex')` (always `#RRGGBB`, upper case). The swatch is decorative: the
hex text next to it names the colour. A picker (area and sliders) is not part of this component.

A hex colour input with a live `Swatch` preview. Built on React Aria `ColorField` (hex mode), styled like [Input](../Input/Input.md). Task: GAP-024.

- Import: `import { ColorField } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/ColorField/ColorField.tsx`
- Stories (Storybook title `Components/ColorField`): Default, WithValue, Empty, NormalisesOnBlur, KeyboardContract, Required, Invalid, CustomError, DescriptionTone, Disabled, ReadOnly, Sizes, Controlled, Brazilian

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | `ReactNode` |  |  | Helper text under the control, linked with `aria-describedby`. |
| `descriptionTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the description: `success`, `warning`, `danger` or `accent` for a live check. The text carries the meaning; colour only reinforces it. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while the field is invalid and the error is displayed (see `Input`). Defaults to the catalog message "Enter a colour as #RRGGBB.". |
| `placeholder` | `string` |  |  | Text shown while the field is empty, for example `#RRGGBB`. Never a substitute for the label. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Control height: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `fullWidth` | `boolean` |  | `false` | Take the free space of a flex row (an `Inline`): the field grows to fill it and can shrink below its content width. Off by default. In a block context the field already spans the width. |
| `className` | `string` |  |  | Class name for the field root. |
| `inputClassName` | `string` |  |  | Class name for the `<input>` element. |
| `inputRef` | `Ref<HTMLInputElement>` |  |  | Ref to the `<input>` element. The `ref` prop points at the field root. |
| `messages` | `Partial<{ invalid: string; } & { requiredMark: string; }>` |  |  | Message overrides for this instance: `invalid`, `requiredMark`. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaColorFieldProps` (react-aria): `isWheelDisabled`
- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `ColorFieldProps` (react-stately): `onChange`
- From `ColorFieldProps` (react-aria-components): `colorSpace`
- From `DOMProps` (@react-types/shared): `id`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `TextInputDOMEvents` (@react-types/shared): `onBeforeInput`, `onCompositionEnd`, `onCompositionStart`, `onCompositionUpdate`, `onCopy`, `onCut`, `onInput`, `onPaste`, `onSelect`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- From `ValueBase` (@react-types/shared): `defaultValue`, `value`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ ColorField: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `invalid` | `Enter a colour as #RRGGBB.` | Error shown when the field is invalid and the consumer gave no `errorMessage`. |

#### Design tokens used

`--ds-field-control-padding-inline`, `--ds-font-mono`, `--ds-space-2`, `--ds-text-3`

#### When to use

- The user types or pastes a colour as a hex code: fabric colour, tag colour, brand colour in a settings form.

#### When not to use

- Choosing from a fixed palette: a hand-built set of options with `Swatch` and labels.
- Exploring colours visually (area, hue slider, eyedropper): a picker is not part of this component yet.
- A colour name or code that is not a hex value: `Input`.

#### Anatomy

`[ swatch | #RRGGBB ]` in one box (`sm` 32 / `md` 40 / `lg` 48), then description and error as in `Input`. The text is Geist Mono, shown upper case. The swatch is decorative (`aria-hidden`) and empty (dashed circle) when there is no value.

#### Props (key ones)

| Prop                                                          | Notes                                                                                           |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `label` / `aria-label` / `aria-labelledby`                    | One is required.                                                                                |
| `value` / `defaultValue` / `onChange(color)`                  | RAC naming. A `#RRGGBB` string or a `Color`. `onChange` receives a `Color`, or `null` if empty. |
| `validate`                                                    | Receives the `Color \| null`; return a message (or messages) to mark the field invalid.         |
| `size`                                                        | `sm` / `md` (default) / `lg`.                                                                   |
| `fullWidth`                                                   | In a flex row (`Inline`) the field takes the free space and can shrink. Off by default.         |
| `description`, `descriptionTone`, `errorMessage`              | As in `Input`. `errorMessage` defaults to the catalog `invalid` message.                        |
| `placeholder`                                                 | For example `#RRGGBB`. Never a substitute for the label.                                        |
| `name`, `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly` | Standard. `name` submits `#RRGGBB`.                                                             |
| `messages`                                                    | `invalid`, `requiredMark`.                                                                      |

##### Getting the hex

`onChange` gives a React Aria `Color`. The normalised string is `color?.toString('hex')`: always `#RRGGBB`, upper case (`null` when the field is empty). To store the value as a string, keep that string and pass it back as `value`.

```tsx
const [hex, setHex] = useState('#C2603E');
<ColorField label="Hex" value={hex} onChange={(color) => setHex(color?.toString('hex') ?? '')} />;
```

#### Behaviour

- Typing is free. On blur or `Enter` the text is parsed and normalised: `#abc` and `abc` become `#AABBCC`.
- Text that is not a colour is reverted to the last valid value on blur (React Aria). To flag an empty required field or a rule of your own (`validate`, `isInvalid`), the field shows the `invalid` message "Enter a colour as #RRGGBB." unless you pass `errorMessage`; an app-supplied `validate` message wins.
- An empty field reports `null`; the swatch is then empty.

#### Accessibility and keyboard

| Key                     | Behavior                                         |
| ----------------------- | ------------------------------------------------ |
| Typing                  | Any text; parsed and normalised on blur or Enter |
| `ArrowUp` / `ArrowDown` | Step the colour value by 1 (React Aria)          |

The input is a text input named by its label, with description and error linked by `aria-describedby` and `aria-invalid`. The swatch is `aria-hidden`: the hex text next to it carries the meaning, so colour is never the only carrier. Focus ring on the box, also in forced-colors.

#### Content rules

Label with the noun ("Hex", "Fabric colour"). Errors say how to fix: "Enter a colour as #RRGGBB."

#### Example

```tsx
<ColorField
  label="Hex"
  name="hex"
  defaultValue="#C2603E"
  description="Colour of the fabric as dyed."
/>
```

#### Design note (GAP-024)

Decision: wrap React Aria `ColorField` rather than keep a masked `Input` plus `Swatch` in every app. No new ADR: `react-aria-components` is already the behaviour layer (ADR-0001) and this adds no dependency. React Aria gives hex parsing, `#abc` expansion, stepping and form submission for free; the DS adds the field anatomy, the swatch preview, mono type and messages.

Out of scope, a later task: a colour picker (area, hue and channel sliders, eyedropper) as a popover composed with this field, and channel fields (`channel` prop) for HSL or RGB inputs.

#### Differences from the consumer workaround

- No hand-built `normalizeHex`, `isHex` or preview row: the field normalises and previews itself.
- The consumer disabled form validation and showed its own error; here the field uses `FieldError` and the catalog message, in en and pt-BR.

#### Related components

- Instead, see Swatch: Choosing from a fixed palette: a hand-built set of options with `Swatch` and labels.
- Instead, see Input: A colour name or code that is not a hex value: `Input`.
- Renders: FieldMessages, Label, Swatch

### ColorOption

> A selectable option that shows a color swatch and its name. It is a toggle button
(`aria-pressed`), so each option is chosen independently: put several in a
`role="group"` with an accessible name to pick any number of colors.
`isSelected` / `defaultSelected` / `onChange(isSelected)` follow React Aria.

Why a toggle and not a radio: the handoff uses it to pick several colors (a product's
available colors). To pick exactly one color, use `ChoiceTiles` or `RadioGroup` instead.

A selectable option that shows a color swatch and the color's name, with an optional short mark. It is a toggle button: each option is chosen on its own. Import it from `loui-ds/patterns`.

- Handoff source: `components/erp/ColorOption.jsx` (TODO `CMP-PAT-04`).

- Import: `import { ColorOption } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/ColorOption/ColorOption.tsx`
- Stories (Storybook title `Patterns/ColorOption`): Default, Selected, WithMark, SelectedWithMark, Disabled, DisabledSelected, LongLabel, LightColor, DarkColor, InAGroup, KeyboardToggle, RightToLeft, Focused, Default, Preselected, WithDescription, DisabledItem, DisabledGroup, Invalid, SingleSelection, Controlled, LongLabels, SingleColumn, Portuguese, RightToLeft, KeyboardRoving

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `color` | `string` | yes |  | The color to show, as `#rgb` or `#rrggbb`. |
| `label` | `string` | yes |  | Name of the color ("Navy"). It is the accessible name of the option and is always visible. |
| `mark` | `ReactNode` |  |  | Optional short text after the label (a count, "Default", a code). It is part of the accessible name. While the option is selected and no `mark` is given, a check is shown instead. |
| `className` | `string` |  |  | Class name for the button. |
| `ref` | `Ref<HTMLButtonElement>` |  |  | Ref to the underlying `<button>`. |

##### Inherited props

- From `AriaBaseButtonProps` (react-aria): `aria-controls`, `aria-disabled`, `aria-expanded`, `aria-haspopup`, `preventFocusOnPress`
- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `ButtonProps` (react-aria): `isDisabled`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `HoverEvents` (@react-types/shared): `onHoverChange`, `onHoverEnd`, `onHoverStart`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `SlotProps` (react-aria-components): `slot`
- From `ToggleButtonProps` (react-aria-components): `id`
- From `ToggleButtonProps` (react-aria): `defaultSelected`, `isSelected`, `onChange`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-bg`, `--ds-color-option-group-columns`, `--ds-color-option-group-gap`, `--ds-color-option-group-min-width`, `--ds-control-h-md`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-sans`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-meta`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-3`, `--ds-text`, `--ds-text-2`, `--ds-text-3`

#### When to use

- Choose any number of colors from a list: the colors available for an item, the colors to filter by.
- When the color name must be visible next to the swatch.

#### When not to use

- To choose exactly one color: use `ChoiceTiles` or `RadioGroup` (radio semantics).
- A free-form color input: use a color field.
- To display a color with no interaction: use `Swatch`.

#### Semantics decision: toggle, not radio

The option exposes `aria-pressed` (a toggle button), not a radio. The handoff uses it for multi-select ("which colors does this item come in?"), and a radio group would force a single answer and a roving tab stop. React Aria `ColorSwatchPicker` was evaluated and does not fit: it is a single-select listbox of bare swatches with generated color names and no room for a visible label or mark. For single choice, use `ChoiceTiles`.

Group several options with `ColorOptionGroup` (a named group with a shared `value`, error text and roving arrow keys, see `ColorOptionGroup.md`). Outside a group every option is its own tab stop.

#### Anatomy

```
button[aria-pressed]
  Swatch (decorative)
  label
  mark | check            (mark text if given, otherwise a check while selected)
```

#### Accessibility

- `aria-pressed` states the selection; the selected look is also a doubled accent border, a soft fill and a check (not color alone).
- The swatch is decorative because the label names the color.
- Boundaries use `--ds-line-control` (3:1); hover brightens the border, never the fill. Focus: accent border and ring. Forced colors: `Highlight` border when selected.

#### Content rules

- Label is the color name in sentence case ("Brick red"); `mark` is two or three words at most.

#### Examples

```tsx
<div role="group" aria-label="Available colors">
  <ColorOption color="#1f3a93" label="Navy" isSelected={on.navy} onChange={set('navy')} />
  <ColorOption color="#c0392b" label="Brick red" mark="12 left" />
</div>
```

#### Related components

- Instead, see ChoiceTiles: To choose exactly one color: use `ChoiceTiles` or `RadioGroup` (radio semantics).
- Instead, see RadioGroup: To choose exactly one color: use `ChoiceTiles` or `RadioGroup` (radio semantics).
- Instead, see Swatch: To display a color with no interaction: use `Swatch`.
- Renders: Icon, Swatch

### ColorOptionGroup

> A named group of `ColorOption`s that shares one value: the list of chosen option `id`s. It
adds the group name (`label`, `aria-label` or `aria-labelledby`), helper text, an error linked
with `aria-describedby`, per-option `isDisabled` (set it on the `ColorOption`) and one tab
stop with arrow keys between options (they stop at the ends, like `ToggleGroup`). `Space` and
`Enter` choose the focused option.

List the options alphabetically by label (AGENTS.md 5b); the group keeps the order you give.
Built on React Aria `ToggleButtonGroup`.

A selectable option that shows a color swatch and the color's name, with an optional short mark. It is a toggle button: each option is chosen on its own. Import it from `loui-ds/patterns`.

- Handoff source: `components/erp/ColorOption.jsx` (TODO `CMP-PAT-04`).

- Import: `import { ColorOptionGroup } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/ColorOption/ColorOptionGroup.tsx`
- Stories (Storybook title `Patterns/ColorOption`): Default, Selected, WithMark, SelectedWithMark, Disabled, DisabledSelected, LongLabel, LightColor, DarkColor, InAGroup, KeyboardToggle, RightToLeft, Focused, Default, Preselected, WithDescription, DisabledItem, DisabledGroup, Invalid, SingleSelection, Controlled, LongLabels, SingleColumn, Portuguese, RightToLeft, KeyboardRoving

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | The `ColorOption` children. Each needs an `id` that is unique in the group (its value). |
| `selectionMode` | `'single' \| 'multiple'` |  | `'multiple'` | `multiple` (default): any number of colors can be chosen (the group is a `toolbar` of toggle buttons). `single`: at most one color (a `radiogroup`). |
| `value` | `readonly string[]` |  |  | The `id`s of the chosen options (controlled). Pair with `onChange`. |
| `defaultValue` | `readonly string[]` |  |  | The `id`s of the options chosen at the start (uncontrolled). |
| `onChange` | `(value: string[]) => void` |  |  | Called with the `id`s of all chosen options after the user chooses or clears one. |
| `description` | `ReactNode` |  |  | Helper text under the options. Linked with `aria-describedby`. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while `isInvalid` is set. Linked with `aria-describedby`. |
| `isInvalid` | `boolean` |  | `false` | Marks the group invalid: danger border on the unselected options and the error text. |
| `columns` | `number` |  | `2` | Maximum number of columns. Default `2`. The grid collapses to fewer columns on narrow containers so an option never gets narrower than `--ds-color-option-group-min-width`. |
| `className` | `string` |  |  | Class name for the group root. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the element that holds the options. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-details`
- From `ToggleGroupProps` (react-stately): `isDisabled`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-bg`, `--ds-color-option-group-columns`, `--ds-color-option-group-gap`, `--ds-color-option-group-min-width`, `--ds-control-h-md`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-sans`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-meta`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-3`, `--ds-text`, `--ds-text-2`, `--ds-text-3`

#### When to use

- Choose any number of colors from a list: the colors available for an item, the colors to filter by.
- When the color name must be visible next to the swatch.

#### When not to use

- To choose exactly one color: use `ChoiceTiles` or `RadioGroup` (radio semantics).
- A free-form color input: use a color field.
- To display a color with no interaction: use `Swatch`.

#### Semantics decision: toggle, not radio

The option exposes `aria-pressed` (a toggle button), not a radio. The handoff uses it for multi-select ("which colors does this item come in?"), and a radio group would force a single answer and a roving tab stop. React Aria `ColorSwatchPicker` was evaluated and does not fit: it is a single-select listbox of bare swatches with generated color names and no room for a visible label or mark. For single choice, use `ChoiceTiles`.

Group several options with `ColorOptionGroup` (a named group with a shared `value`, error text and roving arrow keys, see `ColorOptionGroup.md`). Outside a group every option is its own tab stop.

#### Anatomy

```
button[aria-pressed]
  Swatch (decorative)
  label
  mark | check            (mark text if given, otherwise a check while selected)
```

#### Accessibility

- `aria-pressed` states the selection; the selected look is also a doubled accent border, a soft fill and a check (not color alone).
- The swatch is decorative because the label names the color.
- Boundaries use `--ds-line-control` (3:1); hover brightens the border, never the fill. Focus: accent border and ring. Forced colors: `Highlight` border when selected.

#### Content rules

- Label is the color name in sentence case ("Brick red"); `mark` is two or three words at most.

#### Examples

```tsx
<div role="group" aria-label="Available colors">
  <ColorOption color="#1f3a93" label="Navy" isSelected={on.navy} onChange={set('navy')} />
  <ColorOption color="#c0392b" label="Brick red" mark="12 left" />
</div>
```

#### Related components

- Instead, see ChoiceTiles: To choose exactly one color: use `ChoiceTiles` or `RadioGroup` (radio semantics).
- Instead, see RadioGroup: To choose exactly one color: use `ChoiceTiles` or `RadioGroup` (radio semantics).
- Instead, see Swatch: To display a color with no interaction: use `Swatch`.
- Renders: ErrorText, Label

### Combobox

> A text input with a filtered list of options in a popover (ARIA combobox pattern, built on
React Aria `ComboBox`): the input has `role="combobox"` with `aria-expanded`,
`aria-controls`, `aria-autocomplete="list"` and `aria-activedescendant`, so focus stays in
the input while the arrow keys move through the list.

Typing filters the options accent- and case-insensitively. `Enter` selects the highlighted
option, `Escape` closes the list and then restores the selected text, `ArrowDown` / `ArrowUp`
open the list and move, `Home` / `End` move the caret in the input (React Aria keeps them for
text editing). With `allowsCustomValue` the typed text itself is a valid value.

Use it for long lists (10 or more options); for fewer prefer `Select`. `onCreate` adds a
`Create "text"` row for text that matches no option (see Combobox.md).

A text input with a filtered list of options in a popover (ARIA combobox pattern). Built on React Aria `ComboBox` (`Input`, `Button`, `Popover`, `ListBox`). Shared field behavior is in [Field](../Field/Field.md). Task: CMP-INP-01.

- Import: `import { Combobox } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Combobox/Combobox.tsx`
- Stories (Storybook title `Components/Combobox`): Default, Open, KeyboardContract, WithDescriptionAndMeta, SelectWithPointer, WithSelection, Sections, DisabledOption, NoResults, CustomValue, Loading, AsyncFromServer, Required, Invalid, Disabled, ReadOnly, Sizes, LongText, WithLeading, CreateNew, FullWidthInRow

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `options` | `readonly (ComboboxOption \| ComboboxGroup)[]` | yes |  | The options, or groups of options. Keep the order you want users to see (see Combobox.md). |
| `value` | `string \| null` |  |  | The selected option `value`; `null` means nothing is selected. Pair with `onChange`. |
| `defaultValue` | `string \| null` |  |  | The initially selected `value` when uncontrolled. |
| `onChange` | `((value: string \| null) => void)` |  |  | Called with the selected `value`, or `null` when the selection is cleared. |
| `filter` | `false \| ((label: string, query: string, option: ComboboxOption) => boolean)` |  |  | How options are matched against the typed text. Default: accent- and case-insensitive "contains" on the label (`matchesSearch`), so `cafe` finds `Café`. Pass your own function, or `false` to show `options` as given: use it when the list is loaded from a server as the user types (listen to `onInputChange`, update `options`, set `isLoading` meanwhile).  The function receives the whole option as a third argument, so you can search by a field that is not the label (`option.value` as a code, `option.meta` as an SKU). Two-argument functions keep working. Options that share a label are matched together: give each option a distinct label when the filter looks at other fields. |
| `selectFirstOnEnter` | `boolean` |  | `false` | Press `Enter` with no option highlighted to select the first matching option (typing "tri" then `Enter` picks "Trimestral"). Default `false`: the WAI-ARIA editable combobox does not auto-select, so `Enter` without a highlighted option keeps the typed text (and submits the surrounding form). Turn it on for lookup fields where the typed text alone is never a valid value. Ignored while the list is closed, empty or has only disabled options. |
| `onCreate` | `((inputValue: string) => void)` |  |  | Turns on the "create new" row. While the typed text is not blank and matches no option label (accent- and case-insensitive), the list ends with a `Create "text"` row (message `createOption`). Choosing it (click, or `ArrowDown` then `Enter`) calls `onCreate` with the trimmed text and does not call `onChange`; the typed text is never replaced by the row's text. Add the option to `options` in the handler and set `value` to it: the input then shows its label. Pair it with a controlled `value`. If the handler selects nothing, the input empties when the list closes, as in any combobox without `allowsCustomValue`; with `allowsCustomValue` the typed text stays as the value. |
| `isLoading` | `boolean` |  | `false` | Shows a spinner in the box and, when there are no options yet, a "Loading" row instead of "No results". The consumer owns the data: see `filter={false}` and `onInputChange`. |
| `description` | `ReactNode` |  |  | Helper text under the control. Linked with `aria-describedby`. |
| `descriptionTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the description: `success`, `warning`, `danger` or `accent` for a live check such as "Matches" or "Over by $5". The text carries the meaning; colour only reinforces it. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while the field is invalid and the error is displayed. See `Input`. |
| `placeholder` | `string` |  |  | Text shown while the box is empty. Never a substitute for the label. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Control height: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `fullWidth` | `boolean` |  | `false` | Take the free space of a flex row (an `Inline`): the field grows to fill it and can shrink below its content width. Off by default. In a block context the field already spans the width. |
| `className` | `string` |  |  | Class name for the field root. |
| `popoverClassName` | `string` |  |  | Class name for the popover that holds the options. |
| `inputClassName` | `string` |  |  | Class name for the `<input>` element. |
| `inputRef` | `Ref<HTMLInputElement>` |  |  | Ref to the `<input>` element. The `ref` prop points at the field root. |
| `messages` | `Partial<{ noResults: string; loading: string; showOptions: string; createOption: (value: string) => string; } & { requiredMark: string; }>` |  |  | Message overrides for this instance: `noResults`, `loading`, `showOptions`, `createOption`, `requiredMark`. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaComboBoxProps` (react-aria): `shouldFocusWrap`
- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `CollectionBase` (@react-types/shared): `disabledKeys`
- From `ComboBoxProps` (react-stately): `allowsCustomValue`, `defaultInputValue`, `inputValue`, `menuTrigger`, `onInputChange`, `onOpenChange`
- From `DOMProps` (@react-types/shared): `id`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Combobox: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `noResults` | `No results` | Shown in the list when the typed text matches no option. |
| `loading` | `Loading` | Shown in the list while options are loading and there are none yet; also names the spinner. |
| `showOptions` | `Show options` | Accessible name of the button that opens the list. |
| `createOption(value: string)` | `Create “{value}”` | Last row of the list when `onCreate` is set and the typed text matches no option. |

#### Design tokens used

`--ds-accent`, `--ds-combobox-popover-max-height`, `--ds-field-control-padding-inline`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-sm`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-6`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-target-min`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tracking-caption`, `--ds-z-dropdown`

#### When to use

- Choosing from a long list (10 or more options): customers, products, cities.
- Choosing from a list or typing a new value (`allowsCustomValue`).
- Options loaded from a server as the user types (see Async).

#### When not to use

- 2 to 4 options: `RadioGroup`. 4 to 9 options: `Select`.
- Searching the whole app or a table: `SearchInput`.
- Several selections: not supported yet (multiple selection is P3).

#### Props (key ones)

| Prop                                                                                                                                   | Notes                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label` / `aria-label` / `aria-labelledby`                                                                                             | One is required.                                                                                                                                                                                                                                                                                 |
| `options`                                                                                                                              | `ComboboxOption[]` (`value`, `label`, `description`, `meta`, `leading`, `isDisabled`) or groups `{ id, label, options }`.                                                                                                                                                                        |
| `value` / `defaultValue` / `onChange(value)`                                                                                           | The selected option `value`, `null` for none.                                                                                                                                                                                                                                                    |
| `inputValue` / `defaultInputValue` / `onInputChange`                                                                                   | The text in the box (React Aria props, passed through).                                                                                                                                                                                                                                          |
| `allowsCustomValue`                                                                                                                    | The typed text is a valid value; the form then receives the text.                                                                                                                                                                                                                                |
| `filter`                                                                                                                               | Default accent- and case-insensitive "contains" on the label (`matchesSearch`). A function `(label, query, option) => boolean` (the whole option is the third argument, so you can search a code in `value` or `meta`; two-argument functions keep working), or `false` for no client filtering. |
| `onCreate(text)`                                                                                                                       | Adds a `Create “text”` row when the typed text matches no option; see Create new below.                                                                                                                                                                                                          |
| `fullWidth`                                                                                                                            | In an `Inline` row the field takes the free space (`flex: 1 1 auto`, can shrink). Off by default; in a block context the field already spans the width.                                                                                                                                          |
| `selectFirstOnEnter`                                                                                                                   | Default `false`. `Enter` with no option highlighted selects the first enabled match (typing "tri" then `Enter` picks "Trimestral").                                                                                                                                                              |
| `isLoading`                                                                                                                            | Spinner in the box; "Loading" row when there are no options yet.                                                                                                                                                                                                                                 |
| `menuTrigger`                                                                                                                          | `input` (default), `focus` or `manual`.                                                                                                                                                                                                                                                          |
| `description`, `descriptionTone`, `errorMessage`, `size`, `placeholder`, `name`, `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly` | As in `Select`.                                                                                                                                                                                                                                                                                  |
| `messages`                                                                                                                             | `noResults`, `loading`, `showOptions`, `createOption`, `requiredMark`.                                                                                                                                                                                                                           |

Option order is yours (see `Select.md`): sort with `sortByText` unless the order carries meaning.

#### Option leading (swatch, icon, avatar)

`leading` on an option puts a node before its label (a `Swatch`, an `Icon`, an `Avatar`). It is hidden from assistive technology: the option name stays its text (label, meta, description), so put anything that carries meaning in the text, never only in the node. While an option with `leading` is selected and the input shows its label, the same node appears at the start of the input (a colour picker shows the chosen colour); it disappears as soon as the text is edited.

```tsx
<Combobox
  label="Colour"
  options={[{ value: 'navy', label: 'Navy', leading: <Swatch color="#1f3a5f" decorative /> }]}
/>
```

#### Create new (`onCreate`)

While the typed text is not blank and matches no option label (accent- and case-insensitive), the list ends with a `Create “text”` row (message `createOption`; `Criar “text”` in pt-BR). It is a normal option: `ArrowDown` reaches it, `Enter` or a click chooses it. Choosing it calls `onCreate` with the trimmed text and does **not** call `onChange`, and the typed text is never replaced by the row's text. In the handler add the option to `options` and set `value` to it; the input then shows its label.

```tsx
<Combobox
  label="Label"
  options={labels}
  value={value}
  onChange={setValue}
  onCreate={(name) => {
    const created = { value: slug(name), label: name };
    setLabels((list) => [...list, created]);
    setValue(created.value);
  }}
/>
```

Keep `value` controlled. If the handler selects nothing, the input empties when the list closes, as in any combobox without `allowsCustomValue`; with `allowsCustomValue` the typed text stays as the value (there the Create row is rarely needed). The row is not offered when the field is read-only. Creating is reversible: offer Undo with `useUndoable`. The full flow (create, select, toast with Undo) is the `create-on-the-fly` recipe (`docs/recipes/create-on-the-fly.md`).

#### Async options (documented pattern; a full async list is P2)

Set `filter={false}`, keep the query from `onInputChange`, fetch, and pass the result as `options` with `isLoading` meanwhile. The component never fetches and does not virtualize; for thousands of options filter on the server.

#### Accessibility and keyboard

| Key                     | Behavior                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| Typing                  | Opens the list and filters                                                                       |
| `ArrowDown` / `ArrowUp` | Open the list (first / last option) and move; focus stays in the input (`aria-activedescendant`) |
| `Enter`                 | Select the highlighted option and close                                                          |
| `Escape`                | Close the list; pressed again, restore the selected text (clear with `allowsCustomValue`)        |
| `Home` / `End`          | Move the caret in the input (React Aria keeps them for text editing, not for the list)           |
| `Tab`                   | Commit and leave                                                                                 |

`Enter` with nothing highlighted keeps the typed text and selects nothing, as in the WAI-ARIA editable combobox. Turn on `selectFirstOnEnter` for lookup fields where the typed text alone is never a valid value (it does nothing while the list is closed, empty or has only disabled options; a highlighted option always wins).

Hotkeys: A consumer `onKeyDown` does not hide keys from `useHotkeys(..., { allowInEditable: true })` shortcuts: a key keeps bubbling unless your handler called `event.preventDefault()` on it. Recipe: `Enter` confirms and `Escape` cancels (both with `preventDefault()`), every other key stays a hotkey. See `docs/architecture/hotkeys.md`.

The input has `role="combobox"`, `aria-expanded`, `aria-controls`, `aria-autocomplete="list"`. The chevron button ("Show options") is out of the tab order. While the list is open React Aria hides the rest of the page from assistive technology. An option's accessible name contains label, meta and description. The empty state is a single option-like row so screen readers announce it.

#### Content rules

Label with the noun ("Customer"). Empty state text is "No results" (sentence case, no punctuation); localize with `messages`.

#### Example

```tsx
<Combobox
  label="Customer"
  name="customer"
  options={sortByText(customers, (c) => c.label, locale)}
  onChange={setCustomerId}
/>
```

#### Related components

- Instead, see RadioGroup: 2 to 4 options: `RadioGroup`. 4 to 9 options: `Select`.
- Instead, see Select: 2 to 4 options: `RadioGroup`. 4 to 9 options: `Select`.
- Instead, see SearchInput: Searching the whole app or a table: `SearchInput`.
- Renders: FieldMessages, Icon, Label, Spinner

### CommandPalette

> A command palette: a modal with a search field and a grouped list of commands, opened with
`Mod+K` (configurable). Built on React Aria `Autocomplete`, `SearchField` and `ListBox` inside a
`ModalOverlay`: the search field is a combobox that keeps focus while the arrow keys move
through the commands (`aria-activedescendant`), `Enter` runs the highlighted command and
closes, `Escape` closes and focus returns to where it was.

Search ignores case and accents and matches label, keywords and group. With `includeHotkeys`
it also lists the shortcuts registered through `useHotkeys`.

A modal search box that finds and runs commands from the keyboard. It opens with `Mod+K` (Command K on Apple platforms, Control K elsewhere), filters a grouped list as you type and runs the chosen command. It is the "⌘K for everything" of AGENTS.md section 5.

- Import: `import { CommandPalette } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/CommandPalette/CommandPalette.tsx`
- Stories (Storybook title `Components/CommandPalette`): Default, Open, Filtered, Empty, WithRecent, GivenOrder, LongLabels, WithRegisteredHotkeys, Controlled, PortugueseBrazil, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `commands` | `readonly Command[]` | yes |  | The commands. Search covers the label, the keywords and the group. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `((isOpen: boolean) => void)` |  |  | Called when the palette opens (from the hotkey) or closes (Escape, outside press, a command ran). |
| `hotkey` | `string \| false` |  | `Mod+K` | The shortcut that opens the palette, registered in the hotkey registry. Default `'Mod+K'`. It works while an input has focus. Pass `false` to open the palette only through `isOpen`. |
| `includeHotkeys` | `boolean` |  | `false` | Also list every shortcut registered with `useHotkeys` that has a `description`, as a command that runs its handler (grouped by the shortcut's `group`, or under "Shortcuts"). A registered shortcut whose description equals a command's label is listed once. Default `false`. |
| `recentIds` | `readonly string[]` |  |  | Ids of recently run commands, most recent first, shown under "Recent" while the search is empty. Persisting them is up to the app: collect them in `onRun`. |
| `maxRecent` | `number` |  | `5` | Most recent commands shown. Default `5`. |
| `onRun` | `((commandId: string) => void)` |  |  | Called after a command was chosen, with its id, so the app can update `recentIds`. |
| `sort` | `'alphabetical' \| 'given'` |  | `'alphabetical'` | Order of groups and commands. `alphabetical` (default) sorts both with the active locale, ignoring accents; `given` keeps the order of `commands` and lists groups in order of first use. |
| `placeholder` | `string` |  |  | Placeholder and accessible name of the search field. Default from messages: "Search or run a command". |
| `messages` | `Partial<{ title: string; placeholder: string; commands: string; recent: string; ungrouped: string; shortcuts: string; noResults: string; noResultsHint: string; openDescription: string; openGroup: string; resultCount: (n: number) => string; }>` |  |  | Message overrides for this instance. |
| `className` | `string` |  |  | Class name for the palette panel. |
| `ref` | `Ref<HTMLElement>` |  |  | Ref to the panel (`role="dialog"`). |

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ CommandPalette: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `title` | `Command palette` | Accessible name of the palette dialog. |
| `placeholder` | `Search or run a command` | Placeholder and accessible name of the search field. |
| `commands` | `Commands` | Accessible name of the list of commands. |
| `recent` | `Recent` | Heading of the group of recently run commands. |
| `ungrouped` | `Commands` | Heading for commands that have no `group`. |
| `shortcuts` | `Shortcuts` | Heading for registered shortcuts that have no `group` (when `includeHotkeys` is set). |
| `noResults` | `No commands found` | Shown when no command matches the search. |
| `noResultsHint` | `Try another search term.` | Second line of the empty state: what to do next. |
| `openDescription` | `Open the command palette` | Description of the shortcut that opens the palette, listed by `ShortcutsHelp`. |
| `openGroup` | `General` | Group of the shortcut that opens the palette. |
| `resultCount(n: number)` | `2 commands` | Spoken after each search: how many commands match. |

#### Design tokens used

`--ds-accent`, `--ds-command-palette-list-max-height`, `--ds-command-palette-offset-top`, `--ds-command-palette-width`, `--ds-control-h-lg`, `--ds-dialog-gutter`, `--ds-dialog-padding`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-body`, `--ds-fs-caption`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-body`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-overlay`, `--ds-radius-lg`, `--ds-radius-sm`, `--ds-shadow-dialog`, `--ds-space-1`, `--ds-space-2`, `--ds-space-4`, `--ds-space-5`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tracking-caption`, `--ds-weight-medium`

#### When to use

- An app with many actions or destinations that should all be reachable without the mouse: navigate, create, filter, switch.
- Together with `useHotkeys`, so every shortcut is also discoverable by name (`includeHotkeys`).

#### When not to use

- Searching data (orders, customers): use `SearchInput` with suggestions, or a results page. The palette runs commands; a command may open that search.
- Choosing a value in a form: use `Combobox` or `Select`.
- A short list of actions on one object: use `Menu`.

#### Anatomy

```
ModalOverlay (dims the page, dialog layer)
  Modal
    Dialog  role="dialog"  aria-label="Command palette"
      SearchField / Input  role="combobox"  (focus stays here)
      ListBox  role="listbox"  aria-label="Commands"
        Section "Recent"                (only while the search is empty)
        Section <group>
          Option  icon · label (match highlighted) · shortcut (Kbd)
      status    "3 commands"            (visually hidden live region)
```

#### Behavior

- Search matches the label, the `keywords` and the group, ignoring case and accents (`cafe` finds "Open café report"). The matching part of the label is highlighted. Disabled commands stay searchable but cannot run.
- The first command is highlighted when the palette opens and after each typed character, so `Enter` runs it at once. `ArrowUp` / `ArrowDown` move the highlight; focus stays in the field.
- `Enter` (or a click) runs the command and closes the palette. The command runs once the palette has unmounted, so a dialog it opens is not fought over by focus restoration.
- `Escape` always closes, even when the field has text (no "clear first" step), and focus returns to the element that had it.
- The search text resets every time the palette opens.
- Shortcuts of the page do not fire while the palette is open (see `docs/architecture/hotkeys.md`).
- `includeHotkeys`: a registered shortcut whose description equals a command's label is listed once (the command wins); the palette's own shortcut is not listed.

#### Accessibility

- A modal `dialog` named "Command palette". Focus is trapped, the page behind is inert, focus returns on close (React Aria).
- The field follows the WAI-ARIA combobox pattern with a listbox popup: `role="combobox"`, `aria-controls`, `aria-expanded="true"` and `aria-activedescendant` for the highlighted option. React Aria delays moving `aria-activedescendant` by about 500 ms while typing so screen readers are not interrupted by the highlight change.
- Groups are `role="group"` named by their heading. Disabled options are `aria-disabled`.
- After each search a visually hidden `role="status"` says how many commands match ("3 commands", "No commands found").
- Shortcuts are drawn with `Kbd`, which adds spoken key names ("Control Shift O") to the option's name.
- Keyboard: `Mod+K` opens, `↑ ↓` move, `Enter` runs, `Esc` closes. Hover highlights like the keyboard does.
- Motion honors `prefers-reduced-motion`; `forced-colors` gets a system border and highlight outline.

#### Content rules

- Labels are a verb plus an object in sentence case: "Create order", "Go to customers".
- Group names are nouns: "Navigation", "Orders". Use `keywords` for synonyms and other languages instead of long labels.
- Messages: `title`, `placeholder`, `commands`, `recent`, `ungrouped`, `shortcuts`, `noResults`, `noResultsHint`, `openDescription`, `openGroup`, `resultCount(n)`. English and pt-BR ship; override any of them per instance or through `DSProvider messages={{ CommandPalette: { ... } }}`.

#### Examples

```tsx
<HotkeyProvider>
  <CommandPalette
    commands={[
      {
        id: 'orders',
        label: 'Go to orders',
        group: 'Navigation',
        shortcut: '1',
        onAction: () => navigate('/orders'),
      },
      {
        id: 'new',
        label: 'Create order',
        group: 'Orders',
        keywords: ['invoice'],
        shortcut: 'F2',
        onAction: createOrder,
      },
    ]}
    includeHotkeys
    recentIds={recent}
    onRun={(id) => setRecent((ids) => [id, ...ids.filter((x) => x !== id)].slice(0, 5))}
  />
</HotkeyProvider>
```

Open it from a button instead of (or as well as) the hotkey:

```tsx
const [open, setOpen] = useState(false);
<Button onPress={() => setOpen(true)}>Commands</Button>
<CommandPalette commands={commands} isOpen={open} onOpenChange={setOpen} />
```

#### Related components

- Instead, see SearchInput: Searching data (orders, customers): use `SearchInput` with suggestions, or a results page. The palette runs commands; a command may open that search.
- Instead, see Combobox: Choosing a value in a form: use `Combobox` or `Select`.
- Instead, see Select: Choosing a value in a form: use `Combobox` or `Select`.
- Instead, see Menu: A short list of actions on one object: use `Menu`.
- Renders: Icon, Kbd, VisuallyHidden

### ConfirmDialog

> A destructive-action confirmation: an `alertdialog` with the question as the title, the
consequence in one sentence, a Cancel button and a confirm button that names the action.

Initial focus is on **Cancel**, so pressing Enter or Space right after the dialog opens never
confirms. Outside presses do not dismiss it (`Escape` and Cancel do), because the user has to
answer. Follow a confirmed delete with a `Toast` that offers Undo when the data can come back.

A modal dialog, and `ConfirmDialog` for destructive confirmations. Built on React Aria `DialogTrigger`, `ModalOverlay`, `Modal` and `Dialog`.

- Handoff source: `components/feedback/Dialog` (CMP-FBK-03). Overlay management: ARCH-005.

- Import: `import { ConfirmDialog } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Dialog/ConfirmDialog.tsx`
- Stories (Storybook title `Components/ConfirmDialog`): Default, ConfirmByKeyboard, EscapeCancels, ConfirmFlow, Open, Neutral, Pending, WithDetails, Default, Open, Medium, Large, WithoutBody, LongContent, LongTitle, InsideSheet, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | yes |  | The question, naming the object: "Delete order #1048?". Not "Are you sure?" and not "Confirm". |
| `description` | `ReactNode` | yes |  | The consequence, in one sentence: "The order and its 14 lines will be removed. This can't be undone." Required, because a confirmation without a consequence is only a speed bump. |
| `confirmLabel` | `string` | yes |  | Label of the confirming button. Names the action, verb plus object: "Delete order". Never "OK", "Yes" or "Confirm". |
| `onConfirm` | `() => void` | yes |  | Called when the user confirms. The dialog closes afterwards unless `closeOnConfirm` is `false`. |
| `children` | `ReactNode` |  |  | Optional extra content between the description and the buttons (for example a list of affected items). |
| `tone` | `'danger' \| 'neutral'` |  | `'danger'` | `danger` (default): red `danger-solid` button for a destructive action. `neutral`: the `primary` button. |
| `initialFocus` | `'cancel' \| 'confirm'` |  | `'cancel'` | Which button gets the initial focus. `cancel` (default) is the safe choice and the product principle for destructive actions; `confirm` is for non-destructive confirmations. |
| `closeOnConfirm` | `boolean` |  | `true` | Keep the dialog open after `onConfirm`, for example while an async request runs. Default `true` closes it. |
| `isPending` | `boolean` |  | `false` | Shows a spinner on the confirm button and ignores presses while a request runs. |
| `messages` | `Partial<{ cancel: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `size` | `'sm' \| 'md' \| 'lg'` |  |  | Maximum width: `sm` 420px (default), `md` 540px, `lg` 680px. Narrower on small screens. |
| `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | The element that opens the dialog (a `Button`). Optional: omit it and control the dialog with `isOpen`. Focus returns to the element that was focused when the dialog opened. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  |  | Initial open state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the dialog opens or closes. |
| `isDismissable` | `boolean` |  | `false` | Whether pressing the overlay closes the dialog. Default `true`; `ConfirmDialog` sets `false`. |
| `isKeyboardDismissDisabled` | `boolean` |  |  | Disables closing with `Escape`. Use it only while a request is running. |
| `className` | `string` |  |  | Class name for the dialog panel. |
| `ref` | `Ref<HTMLElement>` |  |  | Ref to the dialog panel. |

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`
- `tone`: `danger`, `neutral`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Dialog: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `cancel` | `Cancel` | Label of the button that dismisses a `ConfirmDialog` without doing anything. |

#### Design tokens used

`--ds-dialog-gutter`, `--ds-dialog-padding`, `--ds-dialog-width-lg`, `--ds-dialog-width-md`, `--ds-dialog-width-sm`, `--ds-duration`, `--ds-ease`, `--ds-font-sans`, `--ds-fs-heading`, `--ds-fs-small`, `--ds-lh-heading`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-overlay`, `--ds-radius-lg`, `--ds-shadow-dialog`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-weight-semibold`

#### When to use

- A short task or decision that blocks the page: edit a record in a small form, confirm a deletion.
- `ConfirmDialog`: every deletion. "Deleting always asks for confirmation" (AGENTS.md section 5).

#### When not to use

- Reversible actions (mark, link, change status): do them and offer **Undo** in a `Toast`. Do not confirm.
- Viewing or editing a record next to its list: use `Sheet`.
- Interactive content anchored to a control: use `Popover`.
- A message about the page: use `Alert`.
- Nesting dialogs more than two deep.

#### Anatomy

```
DialogTrigger
  trigger            Button                                (optional when controlled)
  ModalOverlay       --ds-overlay, z dialog
    Modal            raised surface, strong line, radius lg, dialog shadow, width sm | md | lg
      Dialog         role=dialog | alertdialog, aria-labelledby = title, aria-describedby = description
        header       h2 title (17/24, 600) · description (14/22, text-2)
        body         scrolls
        footer       actions aligned to the end; divider when there is a body
```

#### Accessibility

- Focus is **trapped** while open, **restored** to the element that opened it, the page behind is `inert`/`aria-hidden` and does not scroll (all React Aria).
- **Initial focus.** Plain `Dialog`: the dialog itself, or the child with `autoFocus` (put it on the first field). `ConfirmDialog`: **Cancel**, so pressing Enter or Space as soon as it opens never confirms. The handoff focused nothing.
- `Escape` closes **only the top-most layer**. A `Dialog` opened from a `Sheet` closes first and the Sheet stays (tested). Every overlay uses React Aria's shared layer stack instead of its own window listener (ARCH-005).
- Named by the title (`aria-labelledby`, from the `h2`) and described by the description (`aria-describedby`; not linked in the handoff).
- `ConfirmDialog` uses `alertdialog`, which screen readers announce with its description. A press outside does not dismiss it.
- Reduced motion: the 150 ms fade and 8 px rise are removed, so the dialog leaves the DOM immediately when it closes (tested). Forced colors: border in `CanvasText`.
- **Exit animation.** The dialog (and `ConfirmDialog`) stays mounted for the 150 ms fade-out and keeps rendering the props of its last open render during that time. Clearing the state that feeds the title, description, body or footer in the same update that closes it (`setOrder(null)`) does not make the panel animate out empty, so no `useLast`-style workaround is needed. If the tab is hidden the browser does not run animations and React Aria unmounts the dialog only once the tab is visible again.
- 320 px reflow: the dialog shrinks to the viewport less the 24 px gutter and the body scrolls.

##### Layers

Overlays are portaled to `body`, each with its own layer: sheet (40) < dialog (45) < dropdown (50) < popover (55) < toast (58) < tooltip (60). A `Select`, `Menu`, `Popover` or `Combobox` opened from inside a Dialog or Sheet therefore renders **above** it. This is safe because a modal blocks page-level popovers while it is open. Tests assert the order.

Controlled use without a `trigger` renders the overlay directly, without a `DialogTrigger`, so opening the dialog logs nothing to the console (GAP-022). Focus still returns to the element focused before it opened.

#### Content rules

- Title: a question for confirmations that names the object ("Delete order #1048?"), otherwise verb plus object or a noun phrase ("Edit customer"). Sentence case, no exclamation marks.
- Description: the consequence in one sentence ("The order and its 14 lines will be removed. This can't be undone.").
- Buttons: Cancel (secondary) then the action, verb plus object ("Save customer", "Delete order"). Never "OK" or "Yes". One primary action.
- After a confirmed delete show a `Toast` with **Undo** when the data can come back.

#### Examples

```tsx
<ConfirmDialog
  trigger={<Button variant="danger">Delete order</Button>}
  title="Delete order #1048?"
  description="The order and its 14 lines will be removed. This can't be undone."
  confirmLabel="Delete order"
  onConfirm={() => deleteOrder(1048)}
/>

<Dialog
  trigger={<Button>Edit customer</Button>}
  title="Edit customer"
  footer={({ close }) => (
    <>
      <Button onPress={close}>Cancel</Button>
      <Button variant="primary" onPress={save}>Save customer</Button>
    </>
  )}
>
  <Input label="Name" autoFocus />
</Dialog>
```

#### Related components

- Instead, see Sheet: Viewing or editing a record next to its list: use `Sheet`.
- Instead, see Popover: Interactive content anchored to a control: use `Popover`.
- Instead, see Alert: A message about the page: use `Alert`.
- Renders: Button

### Container

> Centers page content and limits its line length: a maximum inline size plus a side gutter.
It carries no landmark role; put it inside `main`.

Centers page content and limits its line length: a maximum inline size and a side gutter.

- Import: `import { Container } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Container/Container.tsx`
- Stories (Storybook title `Layout/Container`): Default, Small, Medium, Large, Full, NoGutter, Narrow, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg' \| 'full'` |  |  | Maximum inline size: `sm` 640px, `md` 960px, `lg` 1200px (`--ds-container-*`), or `full` for no maximum. Default is the page content maximum (`--ds-content-max`, 1200px). |
| `gutter` | `boolean` |  | `true` | Adds the content gutter (`--ds-content-gutter`, 24px) as inline padding. Default `true`. |
| `as` | `'div' \| 'article' \| 'aside' \| 'footer' \| 'form' \| 'header' \| 'li' \| 'main' \| 'nav' \| 'ol' \| 'section' \| 'ul'` |  | `'div'` | Element to render, `div` by default. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`, `full`

#### Design tokens used

`--ds-container-lg`, `--ds-container-md`, `--ds-container-sm`, `--ds-content-gutter`, `--ds-content-max`

#### When to use

- Inside the `main` of a page to keep content readable on wide screens.
- Settings pages and forms (`size="sm"` or `"md"`), dashboards (`"lg"`).

#### When not to use

- Inside `Card`, `Dialog` or `Sheet`: those set their own padding.
- For full-bleed content such as a table: use `size="full"` or skip the container.

#### Anatomy

```
div (max-inline-size, margin-inline: auto, padding-inline: gutter)
  children
```

#### Responsive behavior

The container is `inline-size: 100%` up to its maximum, so it narrows with the viewport and keeps its gutter down to 320px.

#### Accessibility

- Carries no landmark role. The page's single `main` comes from `AppShell` (or your own `<main>`); put the container inside it.
- Logical properties (`margin-inline`, `padding-inline`) make it direction-neutral.

#### Examples

```tsx
<main id="main">
  <Container size="md">
    <Heading level={1}>Settings</Heading>…
  </Container>
</main>
```

Inside `AppShell`, which already pads `main`, use `<Container gutter={false}>` or `<AppShell padded={false}>`.

#### Related components

- Instead, see Card: Inside `Card`, `Dialog` or `Sheet`: those set their own padding.
- Instead, see Dialog: Inside `Card`, `Dialog` or `Sheet`: those set their own padding.
- Instead, see Sheet: Inside `Card`, `Dialog` or `Sheet`: those set their own padding.

### CurrencyInput

> A money field. The value is an integer in minor units (ADR-0006) plus an ISO `currency`, never
a float. It uses the **digits-only typing model**: every digit you type shifts in from the
right (typing `1`, `2`, `3` gives `1.23`), separators are ignored, Backspace shifts the last
digit out, and the caret always stays at the end. Pasting is smarter: `12.50` and `12,50` both
paste as 12.50, read against the locale (see CurrencyInput.md). The box is mono and
right-aligned; the currency symbol is part of the text, where the locale puts it, so screen
readers announce it with the amount.

The form receives the integer minor units under `name`.

A money field. The value is an **integer in minor units** plus an ISO 4217 `currency` (ADR-0006), never a float. Built on [Input](../Input/Input.md); the formatting comes from `Intl` through `formatCurrency`-style helpers and `parseCurrencyInput` (see `docs/architecture/utilities.md`). Task: CMP-INP-05.

- Import: `import { CurrencyInput } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/CurrencyInput/CurrencyInput.tsx`
- Stories (Storybook title `Components/CurrencyInput`): Default, Filled, WithDescription, ToneMessage, Required, Invalid, Disabled, ReadOnly, AllowNegative, MaxDigits, Brazilian, ZeroAndThreeDigitCurrencies, Sizes, Controlled, WithPlaceholder, FullWidthInRow, AmountMode, AmountModeBrazilian, AmountModeYen

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `currency` | `string` | yes |  | ISO 4217 code of the currency (`'USD'`, `'BRL'`, `'JPY'`). It decides the number of fraction digits (JPY has 0, KWD has 3), the symbol and where the locale places it. |
| `value` | `number \| null` |  |  | The amount in **integer minor units** (ADR-0006): `123456` is `$1,234.56` in USD and `¥123456` in JPY. `null` is an empty field (nothing entered), which is different from `0`. |
| `defaultValue` | `number \| null` |  |  | The initial amount when uncontrolled. Defaults to empty (`null`). |
| `onChange` | `((minorUnits: number \| null) => void)` |  |  | Called with the new amount in minor units, or `null` when the field is emptied. |
| `allowNegative` | `boolean` |  | `false` | Accepts negative amounts. Type `-` anywhere to flip the sign. Default `false`. |
| `maxDigits` | `number` |  | `15` | Most digits the amount may have, fraction digits included (`15` is the maximum, the largest count that is always a safe integer). Typing beyond it is ignored. Default `15`. |
| `entryMode` | `'cents' \| 'amount'` |  | `'cents'` | How digits are typed. `'cents'` (default) shifts digits in from the right: `200` is 2.00. `'amount'` types whole units: `200` is 200.00, and the decimal mark (`.` or `,`) starts the fraction (`12,5` is 12.50). Both give integer minor units. See "Typing modes" in the docs. |
| `name` | `string` |  |  | Name for form submission. The form receives the **integer minor units** (`123456`), or an empty string when the field is empty, never the formatted text. |
| `description` | `ReactNode` |  |  | Helper text under the control. Linked with `aria-describedby`. |
| `descriptionTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the description: `success`, `warning`, `danger` or `accent` for a live check such as "Matches" or "Over by $5". The text carries the meaning; colour only reinforces it. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while the field is invalid and the error is displayed. See `Input`. |
| `placeholder` | `string` |  |  | Text shown while the field is empty (`value` is `null`), until the first digit is typed. |
| `size` | `'sm' \| 'md' \| 'lg'` |  |  | Control height: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `fullWidth` | `boolean` |  |  | Take the free space of a flex row (an `Inline`): the field grows to fill it and can shrink below its content width. Off by default. In a block context the field already spans the width. |
| `className` | `string` |  |  | Class name for the field root. |
| `inputClassName` | `string` |  |  | Class name for the `<input>` element. |
| `inputRef` | `Ref<HTMLInputElement>` |  |  | Ref to the `<input>` element. The `ref` prop points at the field root. |
| `messages` | `Partial<{ requiredMark: string; }>` |  |  | Message overrides for this instance (`requiredMark`). |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaTextFieldProps` (react-aria): `aria-activedescendant`, `aria-autocomplete`, `aria-controls`, `aria-haspopup`, `enterKeyHint`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `TextFieldProps` (react-aria-components): `isInvalid`
- From `TextInputDOMEvents` (@react-types/shared): `onBeforeInput`, `onCompositionEnd`, `onCompositionStart`, `onCompositionUpdate`, `onCopy`, `onCut`, `onInput`, `onPaste`, `onSelect`
- From `TextInputDOMProps` (@react-types/shared): `autoCorrect`, `spellCheck`
- From `Validation` (@react-types/shared): `isRequired`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### When to use

- Prices, totals, payments, adjustments: anywhere a person types an amount of money.
- Editing a price inline, in place of its text in a table row or list (see the `InlinePriceEdit` recipe).

#### When not to use

- Quantities or measures: `NumberField`.
- Showing an amount (not editing it): `formatCurrency(minorUnits, currency, locale)` from `loui-ds`.

#### Editing model: digits shift in from the right (decision)

Two models were considered:

1. **React Aria `NumberField` with `style: 'currency'`**. Reuses its parsing and stepping, but its editing model is "type a number, format on blur": locale decimal marks must be typed, the caret and text change on blur, and the value is a JS `number` in major units, so every boundary needs `Math.round(x * 100)` and float drift (`0.1 + 0.2`) becomes a bug source. Money in the handoff is also typed without separators.
2. **Digits-only typing** (the handoff model, implemented by `parseCurrencyInput`). Typing `1`, `2`, `3` gives `$1.23`; `1`, `2`, `3`, `4`, `5`, `6` gives `$1,234.56`. Separators and symbols are ignored, `Backspace` shifts the last digit out, the caret always stays at the end. The state is an integer from the first keystroke to the form value, so there is no floating point anywhere; the same code serves JPY (0 digits) and KWD (3 digits); no locale decimal mark has to be known to type.

**Decision: digits-only typing**, with a smarter **paste** (below). The trade-off: a person who types `12.5` gets `$1.25`, not `$12.50`. That is the point of the model (type `1250`), the field always shows what it will submit, and paste covers the decimal-writing habit.

#### Typing modes

`entryMode` chooses how typed digits are read. Both modes keep the value an integer in minor units, call `onChange` with integers or `null`, accept the same smart paste, and honor `maxDigits` and `allowNegative`.

|                     | `cents` (default)                                                    | `amount`                                                                                 |
| ------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Typing `200` in USD | `$2.00`                                                              | `$200.00`                                                                                |
| Model               | Digits shift in from the right; separators ignored; caret at the end | Digits are whole units; a decimal mark starts the fraction                               |
| Use for             | Cash-register style, fast numeric-keypad entry, POS                  | People who think in whole units, prices like "200", forms where users type decimal marks |

**Amount mode rules** (`parseCurrencyAmount`, string manipulation only, no floats):

- Digits are whole units until a decimal mark. The mark is the **last** `.` or `,` (or the locale's own decimal mark) when it is the only one of its kind and either it is the locale's decimal mark or it is followed by at most as many digits as the currency has (2 for USD/BRL, 3 for KWD). A mark followed by more digits is grouping and ignored, so users can mix habits: `12.5` and `12,5` both mean 12.50; `1,234.56` (en-US) and `1.234,56` (pt-BR) both mean 1234.56; `1,234` in USD is 1234.00.
- At most as many fraction digits as the currency has, and `maxDigits` counts minor-unit digits (`maxDigits: 5` allows up to 999.99). After the locale's decimal mark, extra digits are ignored while typing (`12.567` stays `12.56`), and a second locale decimal mark is ignored. JPY (0 digits) has no fraction: marks are ignored.
- Examples en-US USD: `200` is 20000, `12.5` is 1250, `12,50` is 1250. pt-BR BRL: `200` is 20000, `12,5` is 1250, `1.234,56` is 123456. JPY: `1500` is 1500. KWD en-US: `1.5` is 1500.
- **One reading per edit.** While you type, a mark that was read as the decimal mark keeps that reading until you delete it: pt-BR `12.90` stays 12,90 and one more digit is refused (the text stays `12.90`), instead of turning the `.` into a thousands mark and jumping to 12.905,00. The same holds for a foreign mark in either locale (en-US `12,50` then `7` is refused). So a consumer that saves on every keystroke never sees the order of magnitude change. Type grouped numbers without separators, or paste them: **paste** keeps the smart reading (`1.234,56` in pt-BR pastes as 1234.56). A second decimal mark is ignored.
- Digits beyond 15 are never cut: typing past the limit is ignored and a paste with more than 15 digits is ignored (the value stays as it was), because shortening it would change the amount.
- While focused the box edits **plain text** (no symbol) with normal caret editing, and keeps what you typed readable: `200,` stays `200,`. The existing amount is selected on focus, by keyboard or by a mouse click, so typing replaces it; while nothing has been edited yet a click on the already focused field keeps it selected (a lone caret at the start would put digits before the amount). After the first edit clicks place the caret normally and the mouse can select text. On blur the box shows the full currency format (`R$ 200,00`). `Backspace` edits the text, select all + `Delete` gives `null`, and a lone `-` (with `allowNegative`) is negative zero as in `cents` mode. The mobile keyboard is `decimal` (`text` with `allowNegative`).

#### Behavior

- `value` / `defaultValue` / `onChange` are **integer minor units** or `null` (empty, which is not `0`). `onChange` receives `null` when the field is emptied (select all, then `Delete`).
- Display: the currency's own format with the symbol where the locale puts it (`$1,234.56`, `R$ 1.234,56`, `1.234,56 €`, `¥1,234`), mono, tabular, right-aligned. The symbol is part of the text, so screen readers announce it with the amount.
- Caret (`cents` mode): always moved to the end after every edit and whenever you click or arrow into the text, so a click anywhere never lets digits land at the start. A range selection (Ctrl+A) is allowed so you can clear the field.
- `allowNegative`: type `-` anywhere to flip the sign; a lone `-` shows `-$0.00` (negative zero) and the next digit keeps the sign. Without it, minus signs are ignored.
- `maxDigits` (default and maximum 15, the largest count that is always a safe integer): typing beyond it is ignored. Large amounts are exact (`$9,999,999,999,999.99` is `999999999999999`).
- **Paste** reads the text against the locale: `12.50` and `12,50` both paste as 12.50; `1,234.56` in en-US and `1.234,56` in pt-BR are grouped thousands; a lone separator followed by exactly three digits is a thousands group (`1.234` is 1234 in pt-BR but 1.23 in en-US because `.` is the en-US decimal mark); extra fraction digits are rounded half up; symbols and spaces are dropped; text without digits is ignored.
- **Form**: `name` submits the **integer minor units** (`123456`) or an empty string, through a hidden input; it is not sent while the field is disabled. The visible text is never submitted.

#### Props (key ones)

| Prop                                                                                                                                   | Notes                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `currency`                                                                                                                             | Required ISO 4217 code.                                                                            |
| `value` / `defaultValue` / `onChange`                                                                                                  | `number \| null` in minor units.                                                                   |
| `allowNegative`, `maxDigits`                                                                                                           | See above.                                                                                         |
| `entryMode`                                                                                                                            | `'cents'` (default) or `'amount'`. See "Typing modes".                                             |
| `label` / `aria-label` / `aria-labelledby`                                                                                             | One is required.                                                                                   |
| `description`, `descriptionTone`, `errorMessage`, `size`, `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly`, `placeholder`, `name` | As in `Input`.                                                                                     |
| `placeholder`                                                                                                                          | Shown while `value` is `null`, also while focused, until the first digit is typed.                 |
| `fullWidth`                                                                                                                            | Take the free space of a flex row such as `Inline` (`flex: 1 1 auto`, can shrink). Off by default. |
| `onKeyDown`, `onFocus`, `onBlur`                                                                                                       | Event handlers, composed with the internal ones (see below).                                       |
| `inputRef`, `ref`, `className`, `inputClassName`, `messages`                                                                           | As in `Input`.                                                                                     |

#### Accessibility and keyboard

A text input (`inputmode="numeric"`, or `text` with `allowNegative` so a minus can be typed on mobile) named by the label, described by the description and the error. Digits type, `Backspace` removes the last digit, `-` flips the sign when allowed. There is no live region; the value is announced as typed. The border stays 3:1 in every state (shared Input styling).

Hotkeys: A consumer `onKeyDown` does not hide keys from `useHotkeys(..., { allowInEditable: true })` shortcuts: a key keeps bubbling unless your handler called `event.preventDefault()` on it. Recipe: `Enter` confirms and `Escape` cancels (both with `preventDefault()`), every other key stays a hotkey. See `docs/architecture/hotkeys.md`.

#### Events: `onKeyDown`, `onFocus`, `onBlur`

These come from the underlying text field and are **composed** with the internal handlers, never replaced:

- `onKeyDown`: runs for every key. A key your handler does not `preventDefault()` keeps bubbling to `useHotkeys` shortcuts and still types a digit. Call `preventDefault()` for the keys you take (`Enter`, `Escape`).
- `onFocus`: your handler runs first, then the caret moves to the end of the text.
- `onBlur`: your handler runs after the field resets a lone `-` (negative zero). `onChange` has already delivered the last typed value, so a blur handler may confirm it.

Inline price editing (`Enter` confirms, `Escape` cancels, blur confirms) is the recipe `inline-price-edit`.

#### Placeholder

While `value` is `null` the box is empty and shows `placeholder` in `--ds-text-3`, focused or not. It disappears with the first digit and returns when the field is emptied again (select all, then `Delete`). `0` is a value, not empty: it shows `$0.00`. Use the placeholder for a hint such as an inherited price, never as the label.

#### Content rules

Label the thing being priced ("Price per unit"). The currency symbol is automatic, never part of the label. Errors say how to fix: "Enter a price above zero."

#### Example

```tsx
<CurrencyInput
  label="Price per unit"
  currency="BRL"
  name="price"
  value={priceMinor}
  onChange={setPriceMinor}
/>
```

#### Related components

- Instead, see NumberField: Quantities or measures: `NumberField`.
- Renders: Input

### DataTable

> A data table with locale-aware sorting, row selection with a bulk action bar, client-side
pagination, loading and empty states. Built on React Aria `Table` (a real `<table>` with
grid keyboard navigation): the header cell of a sortable column is a press target with
`aria-sort`, and the selection checkboxes are labelled.

Sorting cycles ascending, descending, none, and is stable: rows that compare equal keep the
order you passed. Strings compare with the active locale (accent- and case-insensitive,
natural number order), numbers numerically. The table never reorders rows on its own;
lists are alphabetical by default in this design system, so pass sorted rows or `defaultSort`.

A table of records with locale-aware sorting, row selection with a bulk action bar, clickable rows, client-side pagination, loading and empty states. Built on React Aria `Table`: a real `<table>` with grid keyboard navigation, `aria-sort` on sortable headers and labelled selection checkboxes.

- Import: `import { DataTable } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/DataTable/DataTable.tsx`
- Stories (Storybook title `Components/DataTable`): Default, AlphabeticalByDefault, Sorting, KeyboardSort, Selection, SelectAllOnPage, KeyboardSelection, SingleSelection, Paginated, SortSelectPaginate, ClickableRows, SelectionAndRowAction, Loading, Empty, CustomEmpty, StickyHeader, LongText, EmptyWithMinimumColumnWidth, MinimumColumnWidth, WrappingColumns, HiddenHeaderLabel, ButtonInCell, Controlled, PortugueseBrazil

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `columns` | `readonly DataTableColumn<T>[]` | yes |  | Column definitions, in display order. |
| `rows` | `readonly T[]` | yes |  | The rows, in the order you want them shown until the user sorts. Lists are alphabetical by default in this design system (AGENTS.md rule 5b): sort the rows before passing them, or pass `defaultSort` for a text column. The table never reorders rows on its own. |
| `rowKey` | `string` |  | `'id' as keyof T & string` | Property of a row that holds its unique id. Default `id`. The value is converted to a string. |
| `selectionMode` | `'none' \| 'single' \| 'multiple'` |  | `'none'` | `none` (default), `single` or `multiple`. Selecting adds a checkbox column. |
| `selectedKeys` | `ReadonlySet<string>` |  |  | Selected row ids (controlled). Selection survives page changes; "select all" applies to the rows of the current page. |
| `defaultSelectedKeys` | `ReadonlySet<string>` |  |  | Selected row ids when uncontrolled. |
| `onSelectionChange` | `(keys: ReadonlySet<string>) => void` |  |  | Called with the new set of selected row ids. |
| `bulkActions` | `(selectedKeys: ReadonlySet<string>, clear: () => void) => ReactNode` |  |  | Content of the bulk action bar, shown while rows are selected: usually small `Button`s. `clear` empties the selection. |
| `sort` | `DataTableSort \| null` |  |  | Current sort (controlled). `null` means no sort. |
| `defaultSort` | `DataTableSort \| null` |  |  | Sort applied first when uncontrolled, for example `{ key: 'customer', direction: 'asc' }`. |
| `onSortChange` | `(sort: DataTableSort \| null) => void` |  |  | Called when the user changes the sort. Header presses cycle ascending, descending, none. |
| `pageSize` | `number \| false` |  | `10` | Rows per page; `false` shows all rows without pagination. Default `10`. Pagination appears only when there is more than one page. |
| `page` | `number` |  |  | Current page, 1-based (controlled). |
| `defaultPage` | `number` |  | `1` | Page shown first when uncontrolled. Default `1`. The page returns to 1 when the sort or the set of rows changes. |
| `onPageChange` | `(page: number) => void` |  |  | Called with the new page. |
| `onRowAction` | `(row: T) => void` |  |  | Called when the user activates a row (click, or Enter on the focused row). Adds a pointer cursor and hover style. |
| `activeKey` | `string` |  |  | Id of the active row (for example the one open in a side sheet). It gets the raised background and the ink bar. |
| `isLoading` | `boolean` |  | `false` | Replaces the rows with skeleton rows and announces "Loading rows". |
| `loadingRowCount` | `number` |  | `5` | Number of skeleton rows while loading. Default `5`. |
| `emptyState` | `ReactNode` |  |  | Content when there are no rows. Default: an `EmptyState` with built-in text. |
| `reserveBulkBarSpace` | `boolean` |  | `true` | Keeps the space of the bulk action bar free while nothing is selected, so the table does not jump down when the first row is selected (fixed positions). Turn off to let the table move up. Default `true`; only applies when `selectionMode` is not `none`. |
| `stickyHeader` | `boolean` |  | `false` | Keeps the header visible while the body scrolls. Set `maxHeight` to scroll inside the table; without it the header sticks to the page scroll. |
| `maxHeight` | `string \| number` |  |  | Maximum height of the table area before it scrolls (a number is px, or any CSS length). |
| `messages` | `Partial<{ selectRow: string; selection: string; selectAll: string; selectedCount: (count: number, formatted: string) => string; clearSelection: string; bulkActions: string; loading: string; emptyTitle: string; emptyDescription: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `aria-label` | `string` |  |  | Accessible name of the table. Required unless `aria-labelledby` is set. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the table (a visible heading). |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ DataTable: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `selectRow` | `Select row` | Accessible name of the checkbox that selects one row. React Aria appends the row name (see `getRowLabel`): "Select row ORD-1001". |
| `selection` | `Selection` | Hidden header text of the selection column in `single` mode, where there is no select-all checkbox. |
| `selectAll` | `Select all rows on this page` | Accessible name of the header checkbox. It selects the rows on the current page. |
| `selectedCount(count: number, formatted: string)` | `{formatted} selected` | Visible and announced selection summary. `formatted` is `count` formatted for the locale. |
| `clearSelection` | `Clear selection` | Button of the bulk action bar that clears the selection. |
| `bulkActions` | `Actions for selected rows` | Accessible name of the bulk action bar. |
| `loading` | `Loading rows` | Announced while the table shows loading rows. |
| `emptyTitle` | `No records found` | Title of the default empty state. |
| `emptyDescription` | `Try another filter or search term.` | Description of the default empty state. |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-data-table-active-bar-w`, `--ds-data-table-bulk-bar-h`, `--ds-data-table-cell-padding-inline`, `--ds-data-table-col-min-w`, `--ds-data-table-col-w`, `--ds-data-table-flex-count`, `--ds-data-table-gap`, `--ds-data-table-header-padding-block`, `--ds-data-table-max-h`, `--ds-data-table-min-w`, `--ds-data-table-selection-col-w`, `--ds-data-table-sticky-z-index`, `--ds-font-mono`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-strong`, `--ds-line-subtle`, `--ds-radius-md`, `--ds-row-h`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-surface-raised`, `--ds-surface-row-hover`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tracking-caption`, `--ds-weight-medium`

#### When to use

- Lists of records the user scans, sorts and acts on: orders, customers, invoices.
- Several columns of comparable data. For one line per record with a menu of actions use `ActionList`.

#### When not to use

- Fewer than three columns, or content that is mostly text: use `ActionList` or a plain list.
- Server-side sorting and paging over very large data sets: control `sort` and `page` yourself and pass the page rows with `pageSize={false}` (virtualization is not provided).
- Layout: this is a data grid, not a layout table.

#### Anatomy

```
div.root
  div[role=group]        bulk action bar (while rows are selected): "N selected", bulkActions, Clear selection
  div.scroll
    table[role=grid]     named by aria-label / aria-labelledby
      thead  th[aria-sort] caption-mono header per column (+ selection checkbox column)
      tbody  tr > td      row height --ds-row-h; active/selected: raised bg + 2px ink bar
  nav                    Pagination (only when there is more than one page)
  span[role=status]      visually hidden live region: "N selected" / "Loading rows"
```

#### Props (key ones)

| Prop                                                         | Type                                          | Default | Notes                                                                                                                                                    |
| ------------------------------------------------------------ | --------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columns`                                                    | `DataTableColumn<T>[]`                        | -       | `key`, `label`, `width`, `minWidth`, `truncate`, `hideLabel`, `align` (`start`/`end`), `mono`, `muted`, `sortable`, `sortValue`, `render`, `isRowHeader` |
| `rows`                                                       | `T[]`                                         | -       | Shown in the order given until the user sorts                                                                                                            |
| `rowKey`                                                     | `keyof T`                                     | `id`    | Unique id property; converted to a string                                                                                                                |
| `aria-label`                                                 | `string`                                      | -       | Required (or `aria-labelledby`)                                                                                                                          |
| `selectionMode`                                              | `none \| single \| multiple`                  | `none`  | Adds a checkbox column                                                                                                                                   |
| `selectedKeys` / `defaultSelectedKeys` / `onSelectionChange` | `ReadonlySet<string>`                         |         | Controlled / uncontrolled. Selection survives page changes                                                                                               |
| `bulkActions`                                                | `(keys, clear) => ReactNode`                  |         | Content of the bar shown while rows are selected                                                                                                         |
| `sort` / `defaultSort` / `onSortChange`                      | `{ key, direction: 'asc' \| 'desc' } \| null` | `null`  | Controlled / uncontrolled sort                                                                                                                           |
| `pageSize`                                                   | `number \| false`                             | `10`    | `false` disables pagination                                                                                                                              |
| `page` / `defaultPage` / `onPageChange`                      | `number`                                      | `1`     | Controlled / uncontrolled page                                                                                                                           |
| `onRowAction`                                                | `(row) => void`                               |         | Row click or Enter. Adds hover style and pointer cursor. A `Button` in a cell does not trigger it (see "Buttons inside cells")                           |
| `activeKey`                                                  | `string`                                      |         | Row open elsewhere (raised background + ink bar)                                                                                                         |
| `isLoading`                                                  | `boolean`                                     | `false` | Skeleton rows (`loadingRowCount`, default 5) and a live "Loading rows"                                                                                   |
| `emptyState`                                                 | `ReactNode`                                   |         | Default: `EmptyState` with built-in text                                                                                                                 |
| `reserveBulkBarSpace`                                        | `boolean`                                     | `true`  | Keeps the bulk bar space free so the table does not jump when the first row is selected                                                                  |
| `stickyHeader`, `maxHeight`                                  | `boolean`, `number \| string`                 |         | With `maxHeight` the body scrolls and the header stays; without it the header sticks to the page scroll                                                  |
| `messages`                                                   | `Partial<messages>`                           |         | Per-instance text overrides                                                                                                                              |

#### Column sizing

| Column prop | Type      | Default | Effect                                                                                                                                     |
| ----------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `width`     | `string`  | -       | CSS width (`96px`, `20%`). Columns without it share the remaining space equally                                                            |
| `minWidth`  | `string`  | -       | CSS minimum width (`120px`, `8rem`). The column is never narrower; a container that is too small scrolls horizontally instead of squashing |
| `truncate`  | `boolean` | `true`  | `true`: header and cells stay on one line and end in an ellipsis. `false`: they wrap and the row grows                                     |
| `hideLabel` | `boolean` | `false` | Hides the header text visually (icon-only or action columns). `label` stays the accessible name                                            |

- Both sizes go through CSS custom properties on the header cell (`--ds-data-table-col-w`, `--ds-data-table-col-min-w`). Browsers ignore `min-width` on cells in a fixed table layout, so when any column has a `minWidth` the table gets a minimum width (`--ds-data-table-min-w`): the sum of every column's own minimum (fixed columns at the larger of `width` and `minWidth`, flexible columns at their `minWidth`, a flexible column without `minWidth` at 0). Without any `minWidth` the layout is unchanged.
- **Flexible columns keep their own minimum.** Each flexible column is its `minWidth` plus an equal share of the space left after all minimums. Example in a 1000px container with `Order` (`width: 100px`), `Customer` (`minWidth: 240px`), `Status` (`minWidth: 80px`) and `Total` (no `minWidth`): 580px is left, so the widths are 100, 433, 273 and 193px. In a 200px container the table is 420px wide and scrolls: 100, 240, 80 and just the cell padding for `Total`. Give every flexible column that must stay readable a `minWidth`.
- Use fixed units (`px`, `rem`) for `width` and `minWidth` in a table with a `minWidth` column; percentages are not part of the minimum calculation, so in development the table logs one console warning (per table) naming the first column that has a `%` `width` or `minWidth` while any column has a `minWidth`. The scroll area is a size container (`container-type: inline-size`) because browsers treat a `calc()` mixing a percentage as `auto` in a fixed table layout; a container unit is a plain length.
- An empty table (no rows, not loading) drops the table minimum width, so the empty state never scrolls sideways. The header stays visible and its labels are cut with an ellipsis.
- A table with a `minWidth` column scrolls horizontally inside its own area (`overflow-x: auto`). A sticky header then sticks to that area, so also set `maxHeight` when using `stickyHeader`.
- Use `minWidth` for content that breaks when squeezed: a row of swatches, a badge, a code. A column with both `width` and `minWidth` is as wide as the larger of the two.
- Truncated text is not lost: the full text stays in the DOM (assistive technology reads it) and the truncated header label carries a `title`. Prefer `truncate: false` over a long truncated value that users need to read.
- **Headers never wrap by default.** The mono uppercase caption style is cut with an ellipsis in a narrow column ("SUPPL…"). Either give the column a `minWidth` that fits the label, or set `truncate: false` to allow a two-line header.
- **Icon-only columns:** set `hideLabel: true` and `sortable: false`. The header cell is named by `label` ("Row actions"), so a screen reader still announces it; never leave the label empty.

#### Sorting

- Pressing a sortable header cycles **ascending, descending, none**. `aria-sort` is `ascending`, `descending` or `none` on the header cell.
- Strings use `compareText` for the active locale: accent- and case-insensitive, natural number order (`Item 2` before `Item 10`). Numbers, booleans and dates compare numerically; numbers come before strings.
- The sort is **stable in both directions**: equal rows keep the order you passed (descending is not a reversed array). Empty values (`null`, `undefined`, `NaN`, invalid dates) always come last.
- Sorting covers all rows, not just the current page; the page returns to 1 when the sort or the set of rows changes (a new array with the same row ids does not reset the page).
- Use `sortValue` when the displayed text differs from the value to sort by, `sortable: false` for columns that are not a property of the row.

##### Alphabetical by default

Lists are alphabetical by default in this design system (AGENTS.md rule 5b; exceptions: tasks by urgency, dated records newest first). The table does not reorder rows on its own. Either pass rows already ordered, or set `defaultSort={{ key: 'customer', direction: 'asc' }}` (see the `AlphabeticalByDefault` story).

#### Selection

- Checkboxes are named "Select row {row header text}" and "Select all rows on this page"; the row header is the column marked `isRowHeader` (default: the first column), so choose the most descriptive one.
- "Select all" applies to the rows on the current page. Selection of other pages is kept. `bulkActions` receives only ids that still exist in `rows`.
- The bulk bar shows "N selected" (plural-aware) and a "Clear selection" button. A visually hidden polite `status` announces the count as it changes.
- `single` mode shows a checkbox per row but no select-all.

#### Buttons inside cells

A `Button` inside a cell handles its own press: the press does **not** also trigger `onRowAction` (covered by a test). This is a design decision, not a bug: a row can open a detail panel while its buttons run their own action ("Archive", "Open menu"). Keep the row action and the cell action distinct, give the Button an accessible name that includes the row ("Archive ORD-1001"), and do not repeat the row action in a Button.

#### Accessibility

- Grid keyboard model from React Aria: `Tab` enters the table (first row), arrow keys move between cells, rows and the header (Arrow Up from the first row), `Enter` or `Space` on a sortable header sorts, `Space` on a selection checkbox toggles, `Enter` on a row runs `onRowAction`, `Tab` leaves the table.
- Sortable headers expose `aria-sort`; the sort icon is decorative. Active sorted headers also use a stronger color, never color alone.
- Selection state is `aria-selected` on rows and the checked state of the checkboxes; the count is text.
- While loading the root has `aria-busy`, skeleton rows are not selectable and the first cell of each carries visually hidden "Loading rows".
- Forced colors: selected and active rows keep the bar (system `Highlight`); focus rings are outlines.
- Not provided: `aria-rowcount`/`aria-rowindex` for the rows of other pages (React Aria derives them from the rendered page). Pagination announces the range ("11–20 of 42").

#### Content rules

- Column labels in sentence case; CSS applies the uppercase mono caption style.
- Bulk actions are verb + object ("Archive orders"); destructive ones still confirm in a dialog.
- Empty text says what happened and what to do ("No records found. Try another filter or search term.").

#### Examples

```tsx
<DataTable
  aria-label="Orders"
  rows={orders}
  rowKey="id"
  defaultSort={{ key: 'customer', direction: 'asc' }}
  selectionMode="multiple"
  columns={[
    { key: 'id', label: 'Order', width: '120px', mono: true, muted: true },
    { key: 'customer', label: 'Customer', isRowHeader: true },
    {
      key: 'status',
      label: 'Status',
      width: '120px',
      render: (r) => <Badge tone="success">{r.status}</Badge>,
    },
    {
      key: 'total',
      label: 'Total',
      width: '120px',
      align: 'end',
      mono: true,
      render: (r) => formatCurrency(r.total, 'USD', locale),
    },
  ]}
  bulkActions={(keys, clear) => (
    <Button
      size="sm"
      onPress={() => {
        archive(keys);
        clear();
      }}
    >
      Archive orders
    </Button>
  )}
  onRowAction={(row) => openOrder(row.id)}
/>
```

#### Related components

- Instead, see ActionList: Fewer than three columns, or content that is mostly text: use `ActionList` or a plain list.
- Renders: Button, Checkbox, EmptyState, Icon, Pagination, Skeleton, VisuallyHidden

### DatePicker

> A date field with a calendar popover (React Aria `DatePicker`). The value is a
`YYYY-MM-DD` string (no time zone, so the day never shifts); the typed segments, the
placeholder, month and weekday names and the first day of the week all follow the
`DSProvider` locale. Type the date (arrows or digits per segment) or open the calendar;
"Today" and "Clear" sit under the grid.

The form receives the ISO date under `name`. Range selection is not part of this component.

`DatePicker` is a date field (typed segments) with a calendar popover and "Today" / "Clear" buttons. `Calendar` is the standalone month grid. Built on React Aria `DatePicker`, `DateInput`, `DateSegment`, `Calendar`, `CalendarGrid`, `CalendarCell`, `Popover`. Task: CMP-INP-02.

- Import: `import { DatePicker } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/DatePicker/DatePicker.tsx`
- Stories (Storybook title `Components/DatePicker`): Default, CalendarKeyboard, Open, PickDate, EscapeRestoresFocus, WithValue, MinAndMax, Required, Invalid, Disabled, ReadOnly, Brazilian, Sizes, StandaloneCalendar, FullWidthInRow

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | `string \| null` |  |  | The date as `YYYY-MM-DD` (no time zone), or `null` for none. Pair with `onChange`. |
| `defaultValue` | `string \| null` |  |  | The initial date when uncontrolled. |
| `onChange` | `((value: string \| null) => void)` |  |  | Called with the new date as `YYYY-MM-DD` once every segment is filled, or `null` from the Clear button. An incomplete date is not reported. |
| `min` | `string` |  |  | Earliest selectable date (`YYYY-MM-DD`). Typing an earlier date makes the field invalid. |
| `max` | `string` |  |  | Latest selectable date (`YYYY-MM-DD`). |
| `description` | `ReactNode` |  |  | Helper text under the control. Linked with `aria-describedby`. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while the field is invalid and the error is displayed. See `Input`. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Control height: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `fullWidth` | `boolean` |  | `false` | Take the free space of a flex row (an `Inline`): the field grows to fill it and can shrink below its content width. Off by default. In a block context the field already spans the width. |
| `className` | `string` |  |  | Class name for the field root. |
| `popoverClassName` | `string` |  |  | Class name for the popover that holds the calendar. |
| `messages` | `Partial<{ today: string; clear: string; openCalendar: string; } & { requiredMark: string; } & Partial<{ previousMonth: string; nextMonth: string; }>>` |  |  | Message overrides for this instance: `today`, `clear`, `openCalendar`, `previousMonth`, `nextMonth`, `requiredMark`. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaDatePickerProps` (react-aria): `autoComplete`
- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `DatePickerBase` (react-stately): `firstDayOfWeek`, `pageBehavior`
- From `DatePickerStateOptions` (react-stately): `shouldCloseOnSelect`
- From `DOMProps` (@react-types/shared): `id`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `OverlayTriggerProps` (react-stately): `isOpen`, `onOpenChange`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ DatePicker: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `today` | `Today` | Footer button that picks today's date. |
| `clear` | `Clear` | Footer button that empties the field. |
| `openCalendar` | `Open calendar` | Accessible name of the button that opens the calendar. |

#### Design tokens used

`--ds-accent`, `--ds-calendar-cell-size`, `--ds-calendar-today-ring-width`, `--ds-calendar-weekday-height`, `--ds-field-control-padding-inline`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-sm`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-target-min`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-text-inverse`, `--ds-weight-medium`, `--ds-weight-semibold`, `--ds-z-dropdown`

#### When to use

- A single calendar date: delivery, due date, birthday.
- `Calendar` alone for inline planners and for composing your own picker.

#### When not to use

- A date range: not supported yet (range picker is P2).
- A time of day or a timestamp: the value has no time and no time zone.
- Dates years away from now: typing the segments is faster than the grid.

#### Value contract

`value`, `defaultValue`, `onChange`, `min` and `max` are **ISO strings `YYYY-MM-DD`** (the `ISODate` type of `src/utils/date`), never `Date`. Conversion to React Aria's `CalendarDate` happens inside the component (`@internationalized/date`, see below), so the day cannot shift with the viewer's time zone. Invalid strings are treated as "no date". `onChange` receives a string only once every segment is filled, or `null` from the Clear button; an incomplete date is not reported. The form receives the ISO string under `name`.

#### Props (key ones)

| Prop                                                                                                 | Notes                                                                                                                           |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `label` / `aria-label` / `aria-labelledby`                                                           | One is required.                                                                                                                |
| `value` / `defaultValue` / `onChange`                                                                | ISO string or `null`.                                                                                                           |
| `min`, `max`                                                                                         | ISO strings. Outside days are disabled in the grid; typed dates outside are invalid. "Today" is disabled when today is outside. |
| `description`, `errorMessage`, `size`, `name`, `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly` | As in `Select`.                                                                                                                 |
| `fullWidth`                                                                                          | Take the free space of a flex row such as `Inline` (`flex: 1 1 auto`, can shrink). Off by default.                              |
| `messages`                                                                                           | `today`, `clear`, `openCalendar`, `previousMonth`, `nextMonth`, `requiredMark`.                                                 |

`Calendar` takes `value`, `defaultValue`, `onChange(iso)`, `min`, `max`, `isDisabled`, `isReadOnly`, `autoFocus`, `messages`, and requires `aria-label` or `aria-labelledby`.

#### Locale

Segment order and separators, placeholders (`dd/mm/aaaa`), month names, weekday letters and the first day of the week come from the `DSProvider` locale through React Aria; there are no hard-coded names. Only the button texts are in the message catalog (`Calendar` key for the month buttons, `DatePicker` for the rest).

#### Accessibility and keyboard

| Key (calendar grid)               | Behavior                                                      |
| --------------------------------- | ------------------------------------------------------------- |
| Arrows                            | Previous / next day, previous / next week                     |
| `PageUp` / `PageDown`             | Previous / next month                                         |
| `Shift+PageUp` / `Shift+PageDown` | Previous / next year                                          |
| `Home` / `End`                    | First / last day of the **month** (React Aria; APG says week) |
| `Enter` / `Space`                 | Select the focused day                                        |
| `Escape`                          | Close the popover, focus returns to the button                |

In the field: digits fill the segment and move to the next; arrows change a segment's value; `Backspace` clears a segment; `Tab` moves between segments. Each day is named with its full date ("Wednesday, October 28, 2026", "Today, ..."), so the grid is usable without sight. Today has a ring (`--ds-text-3`), the selected day an accent fill with `--ds-text-inverse`; disabled days are dimmed and `aria-disabled`.

#### Content rules

Label with the date's role ("Delivery date"). Errors say how to fix: "Choose a date after today."

#### Example

```tsx
<DatePicker
  label="Delivery date"
  name="delivery"
  min="2026-10-30"
  value={date}
  onChange={setDate}
/>
```

#### Dependency note

The component imports `@internationalized/date`, which React Aria already depends on. It is not a direct dependency of this package yet, so under pnpm's strict layout it must be added to `package.json` (`pnpm add @internationalized/date@^3.12.4`, already in the lockfile as a transitive dependency).

#### Related components

- Renders: Button, FieldMessages, Icon, Label

### Description

> Helper text under a field (the handoff `hint`). Linked to the control with
`aria-describedby` by the surrounding React Aria field. It stays visible when an error shows.
With `tone` it becomes a toned message ("Matches", "Over by $5"); the tone adds colour only,
the announcement is the same text.

Shared building blocks that make every form control (`Input`, `Textarea`, `Select`, `Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`) look and behave the same: the same label, description and error styles, the same spacing, the same required marker, the same disabled treatment and the same validation timing. Tickets: ARCH-008, ARCH-009, part of GAP-003.

Most code never imports from `Field` directly: use the ready-made controls. Use the pieces when you compose a field that has no ready-made component yet (for example a custom picker built on a React Aria field).

- Import: `import { Description } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Field/Field.tsx`
- Stories (Storybook title `Components/Field`): Anatomy, ErrorsAfterSaveAttempt, RealtimeValidation, StandaloneErrorText

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |  |
| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  | `'neutral'` | Tints the text for a live check (`success` "Matches", `warning` "Over by $5", `danger` "Short by $5"). Default `neutral`. The words carry the meaning: colour only reinforces it, so never rely on the tone alone. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLElement>` |  |  |  |

#### Variants, sizes and tones

- `tone`: `neutral`, `accent`, `success`, `warning`, `danger`

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-1`, `--ds-success`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-weight-medium`

#### Exports

| Export                                 | What it is                                                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Label`                                | React Aria `Label` with the field label style (13/18, medium). `isRequired` appends the required marker.                                                                       |
| `Description`                          | React Aria `Text slot="description"`, 13/18 in `--ds-text-3`. Linked to the control with `aria-describedby`. `tone` tints it (see Toned description).                          |
| `FieldError`                           | React Aria `FieldError`: renders only while the field is invalid and the error is displayed. The message is in a `role="alert"` element. 13/18 in `--ds-danger`.               |
| `ErrorText`                            | Standalone error text for a group with no field around it. Same look as `FieldError`; `id` (generated by default), `announce` adds `role="alert"`. Renders nothing when empty. |
| `FieldMessages`                        | `Description` (with `descriptionTone`) followed by `FieldError`. Every control renders it under its box.                                                                       |
| `RequiredMark`                         | The marker alone, for fields whose label is not a `Label`.                                                                                                                     |
| `FieldMessageTone`                     | Type: `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'`, the tone of a description.                                                                                |
| `FieldLabelingProps`, `WithLabel`      | Types. `FieldLabelingProps` makes "label, `aria-label` or `aria-labelledby`" mandatory. `WithLabel<P>` helps type stories.                                                     |
| `FieldErrorMessage`, `FieldValidation` | Types for the `errorMessage` prop (a node or a function of the validation result).                                                                                             |

#### Anatomy and spacing

```
Label                       13/18 medium, --ds-text
  gap: --ds-field-gap (6px)
Control box                 border --ds-line-control, radius md, height 32/40/48
  gap: --ds-field-gap
Description                 13/18, --ds-text-3
Error                       13/18, --ds-danger
```

The description stays visible when an error shows (the handoff replaced the hint with the error). Constraints such as "8 characters or more" remain useful while the user fixes the value, and both texts are linked to the control.

#### Toned description (GAP-039)

A live check under a field ("Matches", "Over by $5", "Short by $5") is a description with a tone, not an error: the field stays valid and no `role="alert"` is added.

```tsx
<CurrencyInput
  label="Amount received"
  currency="USD"
  description="Short by $5.00"
  descriptionTone="danger"
/>
```

- `descriptionTone` (`neutral` default, `accent`, `success`, `warning`, `danger`) is supported by `Input`, `Textarea`, `Select`, `Combobox`, `NumberField`, `CurrencyInput` and `SegmentedControl`; `Description` and `FieldMessages` take `tone` / `descriptionTone`.
- The text carries the meaning; the tone only reinforces it. Write the words yourself ("Over by $5", not a bare "$5") and never rely on colour alone. The tone sets `data-tone` on the description element and nothing else changes: the description is announced exactly as before through `aria-describedby`.
- Colours are the signal tokens `--ds-accent`, `--ds-success`, `--ds-warning`, `--ds-danger`, which pass 4.5:1 on `--ds-bg`, `--ds-surface` and `--ds-surface-raised` (see `contrast-pairs.json`).
- Use `errorMessage` when the value must be fixed before submitting; use a toned description for information that can be left as it is.
- Other fields built on `FieldMessages` (`Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`, `ChoiceTiles`, `DatePicker`, `TagInput`) do not expose `descriptionTone` yet.

#### One state model (ARCH-009)

| State     | Look                                                                                                                       | Semantics                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Default   | `--ds-line-control` border, `--ds-bg` fill                                                                                 |                                                    |
| Hover     | Border brightens to `--ds-text-3`. The fill never changes, so the border stays at 3:1 or more.                             |                                                    |
| Focus     | Accent border and the 3px focus ring (`--ds-focus-ring`); forced-colors gets a system outline                              |                                                    |
| Invalid   | Danger border and danger focus ring                                                                                        | `aria-invalid`, error linked by `aria-describedby` |
| Read only | `--ds-surface` fill, same border                                                                                           | `readonly`; focusable, submitted with the form     |
| Disabled  | Label and control at `--ds-opacity-disabled`, dashed border, `--ds-surface` fill; description and error stay full strength | `disabled`; not focusable, not submitted           |
| Required  | Marker after the label                                                                                                     | `required` / `aria-required` on the control        |

Form-control borders use `--ds-line-control` and stay at 3:1 or better against the page in every state (WCAG 1.4.11). The suites assert this per state.

#### Required marker

`Label isRequired` appends the text of the `requiredMark` message (`*` by default) inside the label. The marker is `aria-hidden`: the control itself exposes "required", so announcing the marker too would repeat it. Override the text per instance (`messages={{ requiredMark: '(required)' }}`) or app-wide:

```tsx
<DSProvider locale="pt-BR" messages={{ Field: { requiredMark: '(obrigatório)' } }}>
```

#### Validation behavior: native (default), and why

React Aria fields validate in one of two modes:

- `validationBehavior="native"` (React Aria's default, kept here): the browser's constraint validation. Constraints such as `required`, `type`, `pattern` and `minLength` block submission. The error is **not displayed until the user tries to submit**; then focus moves to the first invalid field and the error appears. Custom `validate` rules report when the user commits the field (leaves it) and again on submit.
- `validationBehavior="aria"`: only ARIA attributes are set; nothing blocks submission, and the error follows every keystroke.

**Decision: `native` is the default for all fields.** It implements the product rule _errors appear only after a save attempt_ without extra code, it works without JavaScript hydration problems (the browser blocks the submit), it puts `required` on the real control and it moves focus to the first problem. `aria` suits fields that need live feedback (a username availability check, a counter): opt in per field with `validationBehavior="aria"`. A consumer that renders its own `Form` can set the mode for every field below it.

Rules for authors:

- Provide an `errorMessage` that says how to fix the problem ("Enter a complete email address."). Without one, React Aria shows the browser's own message, in the browser's language. A static `errorMessage` replaces only that browser text: a message the app supplied (a `validate` rule or `validationErrors` on a `Form`) is shown instead (GAP-009).
- To control `isInvalid` yourself (for example after a server response), pass `isInvalid` and `errorMessage`; the error shows at once.
- The error text is announced when it appears (`role="alert"`) and read again when focus lands on the field.
- Putting `<form>` in the page is enough; no wrapper component is required.

#### Errors outside a field: `ErrorText`

| Use                   | When                                                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `FieldError`          | Inside a React Aria field (`Input`, `Select`, `CheckboxGroup`, ...): validation is wired for you.                     |
| `ErrorText`           | A group of controls you built by hand (colour options, rows) with no field around it. Light, inline, under the group. |
| `Alert tone="danger"` | An error about the whole page, form or request ("Could not save the order"). Heavy, boxed.                            |

`ErrorText` renders whenever it has content, so you decide when it shows. It is not a live region by default: link it with `aria-describedby`, and move focus to the first invalid control on submit so the message is read. Set `announce` when the error appears with no focus move (it adds `role="alert"`). `aria-invalid` is not allowed on `role="group"`; if the group has a role that supports it (`radiogroup`, `listbox`), set it together with `aria-describedby`.

```tsx
const errorId = useId();
<div
  role="group"
  aria-labelledby={labelId}
  aria-describedby={error ? errorId : undefined}
>
  {options}
</div>
<ErrorText id={errorId}>{error}</ErrorText>
```

#### Accessibility

- Every control needs an accessible name: `label`, `aria-label` or `aria-labelledby`. The types enforce it; a development warning covers untyped callers.
- `Description` and `FieldError` are linked with `aria-describedby`; the order is description, then error.
- Disabled fields are exempt from contrast requirements; everything else meets 4.5:1 for text and 3:1 for borders.

#### Related components

- Used by: FileUpload, Radio, RadioGroup

### Dialog

> A modal dialog built on React Aria `DialogTrigger`, `ModalOverlay`, `Modal` and `Dialog`.

React Aria traps focus, restores it to the trigger on close, locks page scroll, hides the
rest of the page from assistive technology and closes only the top-most layer on `Escape`
(a Dialog opened from a Sheet closes first). Initial focus goes to the dialog itself unless
a child has `autoFocus`; for destructive confirmations use `ConfirmDialog`, which focuses
Cancel.

A modal dialog, and `ConfirmDialog` for destructive confirmations. Built on React Aria `DialogTrigger`, `ModalOverlay`, `Modal` and `Dialog`.

- Handoff source: `components/feedback/Dialog` (CMP-FBK-03). Overlay management: ARCH-005.

- Import: `import { Dialog } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Dialog/Dialog.tsx`
- Stories (Storybook title `Components/ConfirmDialog`): Default, ConfirmByKeyboard, EscapeCancels, ConfirmFlow, Open, Neutral, Pending, WithDetails, Default, Open, Medium, Large, WithoutBody, LongContent, LongTitle, InsideSheet, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | yes |  | Heading of the dialog and its accessible name. A question for a confirmation ("Delete order #1048?"), otherwise a noun phrase or a verb plus object ("Edit customer"). |
| `description` | `ReactNode` |  |  | One or two sentences under the title. It is linked to the dialog with `aria-describedby`, so screen readers read it right after the title. |
| `children` | `ReactNode \| ((options: DialogRenderOptions) => ReactNode)` |  |  | Body of the dialog. A function receives `close`. |
| `footer` | `ReactNode \| ((options: DialogRenderOptions) => ReactNode)` |  |  | Actions, aligned to the end of the footer. Cancel (secondary) before the confirming action; one primary action at most. A function receives `close`. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'sm'` | Maximum width: `sm` 420px (default), `md` 540px, `lg` 680px. Narrower on small screens. |
| `role` | `'dialog' \| 'alertdialog'` |  | `'dialog'` | `dialog` (default), or `alertdialog` for a message that needs an answer before the user continues, such as a destructive confirmation. `ConfirmDialog` uses `alertdialog`. |
| `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | The element that opens the dialog (a `Button`). Optional: omit it and control the dialog with `isOpen`. Focus returns to the element that was focused when the dialog opened. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  |  | Initial open state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the dialog opens or closes. |
| `isDismissable` | `boolean` |  | `true` | Whether pressing the overlay closes the dialog. Default `true`; `ConfirmDialog` sets `false`. |
| `isKeyboardDismissDisabled` | `boolean` |  |  | Disables closing with `Escape`. Use it only while a request is running. |
| `className` | `string` |  |  | Class name for the dialog panel. |
| `ref` | `Ref<HTMLElement>` |  |  | Ref to the dialog panel. |

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop.

| Key | English default | Notes |
| --- | --- | --- |
| `cancel` | `Cancel` | Label of the button that dismisses a `ConfirmDialog` without doing anything. |

#### Design tokens used

`--ds-dialog-gutter`, `--ds-dialog-padding`, `--ds-dialog-width-lg`, `--ds-dialog-width-md`, `--ds-dialog-width-sm`, `--ds-duration`, `--ds-ease`, `--ds-font-sans`, `--ds-fs-heading`, `--ds-fs-small`, `--ds-lh-heading`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-overlay`, `--ds-radius-lg`, `--ds-shadow-dialog`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-weight-semibold`

#### When to use

- A short task or decision that blocks the page: edit a record in a small form, confirm a deletion.
- `ConfirmDialog`: every deletion. "Deleting always asks for confirmation" (AGENTS.md section 5).

#### When not to use

- Reversible actions (mark, link, change status): do them and offer **Undo** in a `Toast`. Do not confirm.
- Viewing or editing a record next to its list: use `Sheet`.
- Interactive content anchored to a control: use `Popover`.
- A message about the page: use `Alert`.
- Nesting dialogs more than two deep.

#### Anatomy

```
DialogTrigger
  trigger            Button                                (optional when controlled)
  ModalOverlay       --ds-overlay, z dialog
    Modal            raised surface, strong line, radius lg, dialog shadow, width sm | md | lg
      Dialog         role=dialog | alertdialog, aria-labelledby = title, aria-describedby = description
        header       h2 title (17/24, 600) · description (14/22, text-2)
        body         scrolls
        footer       actions aligned to the end; divider when there is a body
```

#### Accessibility

- Focus is **trapped** while open, **restored** to the element that opened it, the page behind is `inert`/`aria-hidden` and does not scroll (all React Aria).
- **Initial focus.** Plain `Dialog`: the dialog itself, or the child with `autoFocus` (put it on the first field). `ConfirmDialog`: **Cancel**, so pressing Enter or Space as soon as it opens never confirms. The handoff focused nothing.
- `Escape` closes **only the top-most layer**. A `Dialog` opened from a `Sheet` closes first and the Sheet stays (tested). Every overlay uses React Aria's shared layer stack instead of its own window listener (ARCH-005).
- Named by the title (`aria-labelledby`, from the `h2`) and described by the description (`aria-describedby`; not linked in the handoff).
- `ConfirmDialog` uses `alertdialog`, which screen readers announce with its description. A press outside does not dismiss it.
- Reduced motion: the 150 ms fade and 8 px rise are removed, so the dialog leaves the DOM immediately when it closes (tested). Forced colors: border in `CanvasText`.
- **Exit animation.** The dialog (and `ConfirmDialog`) stays mounted for the 150 ms fade-out and keeps rendering the props of its last open render during that time. Clearing the state that feeds the title, description, body or footer in the same update that closes it (`setOrder(null)`) does not make the panel animate out empty, so no `useLast`-style workaround is needed. If the tab is hidden the browser does not run animations and React Aria unmounts the dialog only once the tab is visible again.
- 320 px reflow: the dialog shrinks to the viewport less the 24 px gutter and the body scrolls.

##### Layers

Overlays are portaled to `body`, each with its own layer: sheet (40) < dialog (45) < dropdown (50) < popover (55) < toast (58) < tooltip (60). A `Select`, `Menu`, `Popover` or `Combobox` opened from inside a Dialog or Sheet therefore renders **above** it. This is safe because a modal blocks page-level popovers while it is open. Tests assert the order.

Controlled use without a `trigger` renders the overlay directly, without a `DialogTrigger`, so opening the dialog logs nothing to the console (GAP-022). Focus still returns to the element focused before it opened.

#### Content rules

- Title: a question for confirmations that names the object ("Delete order #1048?"), otherwise verb plus object or a noun phrase ("Edit customer"). Sentence case, no exclamation marks.
- Description: the consequence in one sentence ("The order and its 14 lines will be removed. This can't be undone.").
- Buttons: Cancel (secondary) then the action, verb plus object ("Save customer", "Delete order"). Never "OK" or "Yes". One primary action.
- After a confirmed delete show a `Toast` with **Undo** when the data can come back.

#### Examples

```tsx
<ConfirmDialog
  trigger={<Button variant="danger">Delete order</Button>}
  title="Delete order #1048?"
  description="The order and its 14 lines will be removed. This can't be undone."
  confirmLabel="Delete order"
  onConfirm={() => deleteOrder(1048)}
/>

<Dialog
  trigger={<Button>Edit customer</Button>}
  title="Edit customer"
  footer={({ close }) => (
    <>
      <Button onPress={close}>Cancel</Button>
      <Button variant="primary" onPress={save}>Save customer</Button>
    </>
  )}
>
  <Input label="Name" autoFocus />
</Dialog>
```

#### Related components

- Instead, see Sheet: Viewing or editing a record next to its list: use `Sheet`.
- Instead, see Popover: Interactive content anchored to a control: use `Popover`.
- Instead, see Alert: A message about the page: use `Alert`.
- Used by: ShortcutsHelp

### Divider

> A 1px line that separates groups of content, built on React Aria `Separator`
(`<hr>`, or `role="separator"` with `aria-orientation` when vertical). Prefer spacing to
separate related things; use a divider where the content changes topic.

A 1px line that separates groups of content. Built on React Aria `Separator`.

- Import: `import { Divider } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Divider/Divider.tsx`
- Stories (Storybook title `Layout/Divider`): Default, Subtle, Strong, Dashed, DashedOnPaper, Vertical, Weights

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` |  | `'horizontal'` | `horizontal` (default) separates stacked content; `vertical` separates items in a row and needs a parent with a height. |
| `variant` | `'subtle' \| 'default' \| 'strong' \| 'dashed'` |  | `'default'` | Line weight by token: `subtle` (`--ds-line-subtle`, internal dividers), `default` (`--ds-line`, between cards and sections) or `strong` (`--ds-line-strong`, around controls and overlays). `dashed` is a 1px dashed `--ds-line-strong` rule for a total row or a receipt tear line (AGENTS.md section 7). Default `default`. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLElement>` |  |  | Ref to the separator element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `DOMProps` (@react-types/shared): `id`
- From `SeparatorProps` (react-aria): `elementType`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `subtle`, `default`, `strong`, `dashed`

#### Design tokens used

`--ds-line`, `--ds-line-strong`, `--ds-line-subtle`

#### When to use

- Between sections of a panel or a menu-like list where the topic changes.
- Vertically, between inline groups in a toolbar.

#### When not to use

- To separate closely related items: use spacing.
- Around every field or row: borders-first hierarchy comes from surfaces, not a line between everything.
- To wrap a Card in a Card: use a divider inside one card instead.

#### Anatomy

```
hr (1px line)          horizontal
div[role=separator]    vertical, with aria-orientation
```

#### Accessibility

- Rendered by React Aria: a horizontal divider is an `<hr>`; a vertical one has `role="separator"` and `aria-orientation="vertical"`.
- It is a thematic break for assistive technology, so do not use it as a pure visual rule between unrelated things.
- Line colors are borders, not text; `forced-colors` paints them with `CanvasText`.

#### Dashed rule

`variant="dashed"` is the "total row" rule of AGENTS.md section 7: a 1px dashed line in `--ds-line-strong`, for the line above a total or a tear line on a receipt preview. It works on the dark surfaces and inside the paper scope (`data-theme="paper"`, where the line becomes the paper rule). In `forced-colors` it is drawn with `CanvasText`. Like the other variants it is a decorative border, not a text or control boundary.

#### Examples

```tsx
<Stack gap={4}>
  <Section />
  <Divider />
  <Section />
</Stack>

<Inline>
  <Button>Bold</Button>
  <Divider orientation="vertical" />
  <Button>Link</Button>
</Inline>
```

### DonutMeter

> A circular meter for one proportion: how much of a whole is used, done or filled (storage
used, goal reached, stock level). The percentage is printed in the center, formatted with
`Intl` for the active locale. Built on React Aria `Meter` (`role="meter"` with
`aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext`).

It needs an accessible name: a visible `label` (printed under the ring), `aria-label` or
`aria-labelledby`. For a task that makes progress use `Progress`; for a bar use `Meter`;
for one proportion among several use `ProportionBar`.

A circular meter for one proportion: how much of a whole is used, done or filled (storage used, goal reached, stock level). The percentage is printed in the center, formatted with `Intl` for the active locale. Built on React Aria `Meter` (`role="meter"`). It is a separate component from `Progress`/`Meter`, in its own folder, and does not change them.

- TODO `GAP-007`.

- Import: `import { DonutMeter } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/DonutMeter/DonutMeter.tsx`
- Stories (Storybook title `Components/DonutMeter`): Default, Small, Large, Neutral, Success, Warning, Danger, Empty, Full, CustomRange, CustomCenter, WithoutCenterValue, AriaLabelOnly, LongLabel, Portuguese, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  | `'accent'` | Color of the ring: `accent` (default), `neutral`, `success`, `warning` or `danger`. Color is never the only signal: the percentage is printed in the center and the label says what it is. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Diameter token: `sm` 48px, `md` 72px (default), `lg` 96px. |
| `showValue` | `boolean` |  | `true` | Prints the percentage in the center. On by default. Turn it off when the center is empty on purpose. |
| `centerLabel` | `ReactNode` |  |  | Replaces the percentage in the center ("12" over "days"). Visual only: screen readers get `valueLabel` (or the percentage) as the value of the meter. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the meter element. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `DOMProps` (@react-types/shared): `id`
- From `ProgressBarBaseProps` (react-aria): `formatOptions`, `maxValue`, `minValue`, `value`, `valueLabel`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`
- `tone`: `neutral`, `accent`, `success`, `warning`, `danger`

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-donut-meter-color`, `--ds-donut-meter-size-lg`, `--ds-donut-meter-size-md`, `--ds-donut-meter-size-sm`, `--ds-donut-meter-stroke-w`, `--ds-donut-meter-value`, `--ds-duration-progress`, `--ds-ease`, `--ds-font-mono`, `--ds-fs-heading`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-fs-num`, `--ds-lh-heading`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-lh-num`, `--ds-space-2`, `--ds-success`, `--ds-surface-hover`, `--ds-text`, `--ds-text-2`, `--ds-warning`, `--ds-weight-medium`

#### When to use

- One share of a known total, as a compact visual in a card or a table cell.
- When the center number is the main message and the ring supports it.

#### When not to use

- Progress of a task that is running: use `Progress`.
- A bar in a column or a row: use `Meter` (`Progress` module).
- Several parts of a whole: use `ProportionBar` (a legend with share, value and count columns). One part of a known total as a bar, with the remainder named, is also `ProportionBar` with one segment and `total`. Percentages next to a ring or chart series: `Legend` with `showShare`.
- A trend over time: use `Sparkline` or `Chart`.

#### Anatomy

```
div[role=meter] aria-valuenow/min/max/valuetext
  div.ring
    svg[aria-hidden]   (track circle + filled circle)
    span.center        (percentage or centerLabel)
  label                (optional, under the ring)
```

#### Accessibility

- `role="meter"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext` from React Aria. An accessible name is required (types and a development warning). The drawing is hidden from assistive technology; the center text is covered by `aria-valuetext`.
- Color is never the only signal: the percentage is printed in the center. The ring and track keep 3:1 against the surface in every tone.
- Motion: the ring animates 300ms; none under `prefers-reduced-motion`. Forced colors: track `GrayText`, ring `CanvasText`.
- Not interactive and not focusable.

#### Content rules

- Label: what is measured, in sentence case ("Storage used"). The unit and total belong in `valueLabel` ("6.2 of 10 GB").
- Pair a tone change with text that says why ("Almost full").

#### Examples

```tsx
<DonutMeter label="Storage used" value={62} />

<DonutMeter
  label="Storage"
  value={6.2}
  maxValue={10}
  valueLabel="6.2 of 10 GB"
  tone="warning"
  size="lg"
/>

<DonutMeter aria-label="Trial" value={40} centerLabel="12 d" valueLabel="12 days left" />
```

#### Related components

- Instead, see Progress: Progress of a task that is running: use `Progress`.
- Instead, see Meter: A bar in a column or a row: use `Meter` (`Progress` module).
- Instead, see ProportionBar: Several parts of a whole: use `ProportionBar` (a legend with share, value and count columns). One part of a known total as a bar, with the remainder named, is also `ProportionBar` with one segment and `total`. Percentages next to a ring or chart series: `Legend` with `showShare`.
- Instead, see Legend: Several parts of a whole: use `ProportionBar` (a legend with share, value and count columns). One part of a known total as a bar, with the remainder named, is also `ProportionBar` with one segment and `total`. Percentages next to a ring or chart series: `Legend` with `showShare`.
- Instead, see Sparkline: A trend over time: use `Sparkline` or `Chart`.
- Instead, see Chart: A trend over time: use `Sparkline` or `Chart`.

### Drawer

> A non-modal side panel for filters, inspectors and secondary navigation. It sits next to the
content in the page flow: there is no scrim, the page stays interactive, focus is not trapped
and the page is not made inert. Place it as a sibling of the main content inside a flex or grid
container; it renders nothing while closed.

Use `Sheet` instead when the panel is a task that must be finished or dismissed first
(editing one record): that one is modal.

`Escape` closes the drawer while focus is inside it and returns focus to the trigger.

A non-modal side panel that sits next to the content, for filters, inspectors and secondary navigation. There is no scrim, the page stays interactive and focus is not trapped. Generic: it lives in the core entry point.

- Import: `import { Drawer } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Drawer/Drawer.tsx`
- Stories (Storybook title `Components/Drawer`): Default, AtStart, Small, Large, Region, Unpadded, LongContent, Rtl, OpenAndCloseWithKeyboard

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | yes |  | Heading of the drawer and its accessible name. |
| `children` | `ReactNode \| ((options: DrawerRenderOptions) => ReactNode)` |  |  | Body of the drawer; it scrolls when it is taller than the drawer. A function receives `close`. |
| `footer` | `ReactNode \| ((options: DrawerRenderOptions) => ReactNode)` |  |  | Footer actions, aligned to the end. A function receives `close`. |
| `placement` | `'start' \| 'end'` |  | `'end'` | Edge the drawer sits against: `end` (default) or `start`. Both follow the writing direction. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Width: `sm` 280px, `md` 320px (default), `lg` 400px. It never exceeds its container. |
| `padded` | `boolean` |  | `true` | Pads the body. Turn it off for a table or a full-bleed list. Default `true`. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the drawer opens or closes through the user (close button or `Escape`). |
| `autoFocus` | `boolean` |  | `true` | Moves focus into the drawer when it opens after the first render. A drawer that is open on first render never takes focus. Default `true`; turn it off for a panel that should stay beside the page without interrupting what the user is doing. |
| `role` | `'complementary' \| 'region'` |  | `'complementary'` | Landmark role. `complementary` (default) for content that supports the page (filters, inspectors); `region` for a section the user may want to find in the landmark list. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `2` | Level of the title heading. Default `2`. |
| `messages` | `Partial<{ close: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `className` | `string` |  |  | Class name for the drawer panel. |
| `ref` | `Ref<HTMLElement>` |  |  | Ref to the drawer panel. |

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Drawer: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `close` | `Close panel` | Name of the close button in the Drawer header. |

#### Design tokens used

`--ds-drawer-from`, `--ds-drawer-padding`, `--ds-drawer-shift`, `--ds-drawer-width`, `--ds-drawer-width-lg`, `--ds-drawer-width-md`, `--ds-drawer-width-sm`, `--ds-duration`, `--ds-ease`, `--ds-font-sans`, `--ds-fs-heading`, `--ds-fs-small`, `--ds-lh-heading`, `--ds-lh-small`, `--ds-line`, `--ds-line-subtle`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-surface`, `--ds-text`, `--ds-topbar-h`, `--ds-weight-semibold`

#### Drawer or Sheet

|          | Drawer                                                                   | Sheet                                                      |
| -------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- |
| Modality | Non-modal: page stays usable                                             | Modal: page is `inert`, scroll locked                      |
| Layout   | In the page flow, beside the content                                     | Overlay above the page, with a scrim                       |
| Focus    | Not trapped; Tab leaves the drawer                                       | Trapped and restored                                       |
| Use for  | Filters, inspector for the current selection, secondary navigation, help | Viewing or editing one record, a task to finish or dismiss |

Rule of thumb: if the user should keep working in the page while the panel is open, use a `Drawer`. If the panel is a task that needs a decision before going back, use a `Sheet`.

#### When not to use

- A short confirmation or form: `Dialog`.
- A few controls anchored to a button: `Popover`.
- Top-level navigation: `Sidebar`.

#### Anatomy

```
aside (role complementary | region, aria-labelledby = title)
  header     --ds-topbar-h tall: heading + close IconButton
  body       scrolls; padded or not
  footer     optional, end-aligned actions
```

Place the drawer as a sibling of the main content in a flex or grid container. It renders nothing while closed and does not animate out.

#### Accessibility

- A named landmark (`complementary` by default, `region` on request) labelled by its title.
- Not modal: nothing is hidden from assistive technology and Tab moves freely between the drawer and the page.
- When the drawer opens after first render, focus moves to the panel (it is programmatically focusable, `tabIndex=-1`), so the next Tab reaches its first control. A drawer that is open on first render never takes focus; set `autoFocus={false}` to keep focus where it is.
- `Escape` closes the drawer when focus is inside it (and when no inner overlay handled it) and focus returns to the element that had it before the drawer opened, normally the trigger. Closing from the close button does the same.
- If the consumer closes a controlled drawer from outside (for example a toolbar toggle), focus is left where the user put it.
- Slide-in is a short fade plus 16 px move (`--ds-drawer-shift`); it is removed under `prefers-reduced-motion` and mirrors in right-to-left layouts (`:dir(rtl)`). Borders and padding use logical properties.
- The width is capped by its container (`max-inline-size: 100%`), so on narrow containers it fills the width instead of overflowing.

#### Content rules

- Title: the purpose in sentence case ("Filters", "Order details").
- Footer buttons are verb plus object ("Apply filters", "Clear filters"). Use one primary action.

#### Examples

```tsx
const [open, setOpen] = useState(false);

<div style={{ display: 'flex' }}>
  <main>
    <Button onPress={() => setOpen(true)}>Open filters</Button>
  </main>
  <Drawer
    title="Filters"
    isOpen={open}
    onOpenChange={setOpen}
    footer={({ close }) => (
      <Button variant="primary" onPress={close}>
        Apply filters
      </Button>
    )}
  >
    <Input label="Customer" />
  </Drawer>
</div>;
```

#### Related components

- Instead, see Dialog: A short confirmation or form: `Dialog`.
- Instead, see Popover: A few controls anchored to a button: `Popover`.
- Instead, see Sidebar: Top-level navigation: `Sidebar`.
- Renders: IconButton

### DueIndicator

> A due date with a status in words: "Mar 9  Overdue by 3 days", "Due today", "Due in 5 days",
"Paid", "Paid Oct 30". A dot and the text color follow the tone (`danger` overdue, `warning`
within a week, `neutral` later, `success` paid), but the status is always text, never color
alone. Pass `label` + `tone` instead of `date` for free-text chips ("Pickup at 2 pm").

The urgency comes from `dueStatus`, the wording from messages and `Intl` (`formatRelativeDays`),
the date from `formatDate`. Day arithmetic is calendar-based, so daylight-saving changes never
shift the count.

A due date with a status in words and a tone dot: "Mar 9 Overdue by 3 days", "Due today", "Due in 5 days", "Paid", "Paid Oct 30". Color reinforces the status; the text always states it.

- Handoff source: `components/erp/DueIndicator.jsx` (TODO `CMP-PAT-07`).

- Import: `import { DueIndicator } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/DueIndicator/DueIndicator.tsx`
- Stories (Storybook title `Components/DueIndicator`): Default, Overdue, DueToday, DueTomorrow, Later, Paid, PaidWithDate, DateObject, DateTimeString, LabelAndTone, WithoutDate, LongDate, AcrossDaylightSaving, AllTones, Portuguese, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `date` | `DueDateInput` |  |  | The due date: `YYYY-MM-DD` (`ISODate`, never shifted by a time zone), a `Date` or an ISO date-time string (`2026-10-31T23:30:00-03:00`). A `Date` or date-time maps to the **local** calendar day of the viewer. Invalid values throw in development. |
| `today` | `DueDateInput` |  |  | The current day, same accepted forms as `date`. Defaults to the user's local day at render time. Pass it to make output deterministic (tests, stories, server rendering). |
| `paid` | `boolean` |  |  | The item is settled: shows "Paid" in the success tone, whatever the date. |
| `paidDate` | `DueDateInput` |  |  | The day the item was paid (same forms as `date`). Implies `paid` and shows "Paid Oct 30" from the `paidOn` message, formatted with `dateStyle`. |
| `showDate` | `boolean` |  |  | Shows the formatted date before the status. Default `true`. |
| `dateStyle` | `'short' \| 'medium' \| 'long' \| 'full' \| 'monthDay' \| 'monthYear'` |  |  | Format of the date (`formatDate` styles). Default `monthDay` ("Mar 9"). |
| `label` | `string` |  |  | The status text ("Pickup at 2 pm"). It carries the meaning; the tone only reinforces it. |
| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the dot and the text. |
| `messages` | `Partial<{ overdue: (days: number) => string; due: (relative: string) => string; paid: string; paidOn: (date: string) => string; }>` |  |  | Message overrides for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `tone`: `neutral`, `accent`, `success`, `warning`, `danger`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ DueIndicator: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `overdue(days: number)` | `Overdue by 2 days` | Status of a date in the past. `days` is a positive whole number. |
| `due(relative: string)` | `Due {relative}` | Status of a date today or later. `relative` is the locale's relative time from `formatRelativeDays` ("today", "tomorrow", "in 3 days"). |
| `paid` | `Paid` | Status of a settled item: the due date no longer matters. |
| `paidOn(date: string)` | `Paid {date}` | Status of an item paid on a known day. `date` is already formatted for the locale ("Oct 30"). Word it without grammatical gender so it fits any item ("Paid", not "Paga"). |

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-due-indicator-dot-size`, `--ds-due-indicator-gap`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-label`, `--ds-lh-label`, `--ds-radius-pill`, `--ds-success`, `--ds-text`, `--ds-text-2`, `--ds-warning`, `--ds-weight-medium`

#### When to use

- A deadline in a list row, a card or a detail header (invoice due, task due, renewal).
- When urgency should be readable at a glance without relying on color.

#### When not to use

- A timestamp of something that already happened: format it with `formatDate` / `formatRelativeDays`.
- A workflow status that is not date-driven: use `Badge`.

#### Anatomy

```
span[data-tone=danger|warning|neutral|success]
  span.dot          (aria-hidden)
  time[datetime]    formatDate(date, locale, dateStyle)     (showDate)
  span.status       "Overdue by 3 days" | "Due today" | "Due in 5 days" | "Paid"
```

#### Time zones

- `YYYY-MM-DD` is a calendar day with no time zone and takes a fast path: it is used as written and never shifted.
- A `Date` or an ISO date-time string (`2026-10-31T23:30:00-03:00`, `2026-10-31T23:30:00Z`) is an instant. It is converted to the **viewer's local calendar day** with `toISODate`, so `2026-11-01T01:30:00Z` is Oct 31 in Sao Paulo and Nov 1 in Berlin. A date-time without an offset is read as local time.
- Only strings that contain a time part (`YYYY-MM-DDTHH...` or `YYYY-MM-DD HH...`) are parsed with `new Date()`. If the due day must not depend on the viewer, send `YYYY-MM-DD`.
- `today` follows the same rules. Unparsable date-times and malformed dates throw in development.

#### Free-text form

For chips whose text is not date-driven ("Due today", "Pickup at 2 pm", "Waiting for you"), pass `label` and `tone`. It renders the same dot and text; no date is shown and no wording is generated, so translate `label` yourself.

```tsx
<DueIndicator label="Pickup at 2 pm" tone="neutral" />
<DueIndicator label="Waiting for you" tone="accent" />
```

#### Paid date and locales

`paidDate` calls the `paidOn(date)` message with the date already formatted by `formatDate` for the active locale. The default is `Paid ${date}` (en) and `Pagamento em ${date}` (pt-BR), which avoids gendered agreement ("Paga em" / "Pago em" would have to match the item). Override it per instance (`messages`), per provider or in a locale catalog:

```tsx
<DueIndicator
  date="2026-03-01"
  paidDate="2026-03-08"
  messages={{ paidOn: (date) => `Settled on ${date}` }}
/>
```

#### Accessibility

- The status is text (`Overdue by 3 days`), so color is never the only signal; the dot is `aria-hidden`.
- The date is a `<time datetime>` element.
- Contrast: the status uses `--ds-danger`, `--ds-warning`, `--ds-success` or `--ds-text-2` on the page background, all above 4.5:1.
- Forced colors: the dot and the text fall back to `CanvasText`.

#### Content rules

- "Overdue by 3 days", "Due today", "Due tomorrow", "Due in 5 days", "Paid". Sentence case, no exclamation marks.
- Dates and relative wording come from `Intl` for the active locale; never build them by hand.

#### Examples

```tsx
<DueIndicator date={invoice.dueISO} paid={invoice.paid} />

// A Date or date-time maps to the local calendar day
<DueIndicator date={order.dueAt} paidDate={order.paidAt} />

// Deterministic output
<DueIndicator date="2026-03-14" today="2026-03-10" dateStyle="long" />
```

#### Related components

- Instead, see Badge: A workflow status that is not date-driven: use `Badge`.

### EmptyState

> Tells the user that there is nothing to show, why, and what to do next. The copy follows
"what happened + what to do".

A typographic placeholder for a list, table or panel that has nothing to show. It says what happened and what the user can do about it.

- Import: `import { EmptyState } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/EmptyState/EmptyState.tsx`
- Stories (Storybook title `Components/EmptyState`): Default, WithActions, Compact, WithoutBorder, WithIcon, TitleOnly, LongText, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | yes |  | What happened, in one short sentence: "No orders found". Rendered as a heading (see `headingLevel`). |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `2` | Heading level of the title (`h1` to `h6`). Pick the level that fits the page outline. Default `2`. |
| `description` | `ReactNode` |  |  | What the user can do about it: "Try another filter or search term." |
| `icon` | `ReactNode` |  |  | Optional icon above the title. Decorative: it is hidden from assistive technology. No illustrations. |
| `action` | `ReactNode` |  |  | The primary action, usually a `Button`. Rendered after the secondary action. |
| `secondaryAction` | `ReactNode` |  |  | A second, lower-emphasis action. |
| `compact` | `boolean` |  | `false` | Less padding and a smaller title, for use inside a card, a panel or a table. |
| `bordered` | `boolean` |  | `true` | Dashed border. Set to `false` when the empty state already sits inside a bordered container. Default `true`. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-empty-state-compact-padding-block`, `--ds-empty-state-compact-padding-inline`, `--ds-empty-state-description-max-w`, `--ds-empty-state-padding-block`, `--ds-empty-state-padding-inline`, `--ds-fs-heading`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-heading`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-strong`, `--ds-radius-lg`, `--ds-space-2`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-semibold`

#### When to use

- A list, table or search has no results.
- A feature has no data yet and the user can create some.

#### When not to use

- While data is loading: use `Skeleton`.
- When loading failed: use `Alert` with a retry action.
- For a short inline note inside a field: use the field's description.

#### Anatomy

```
div.root (dashed border, centered)
  span[aria-hidden]  icon (optional)
  h{headingLevel}    title
  p                  description (optional)
  div                secondaryAction, action
```

#### Copy: what happened + what to do

Title: say what is missing, in sentence case, without apologies or exclamation marks. Description: tell the user the next step, in one sentence.

| Situation        | Title             | Description                                              | Action        |
| ---------------- | ----------------- | -------------------------------------------------------- | ------------- |
| Filtered to zero | No orders found   | Try another filter or search term.                       | Clear filters |
| First use        | No orders yet     | Orders created here or in the store appear in this list. | Create order  |
| Cleared inbox    | Nothing to review | New approvals appear here as they arrive.                | (none)        |

Avoid "Oops", "Sorry", blame ("You have no orders") and filler ("There is nothing to show here at the moment").

#### Accessibility

- The title is a real heading: choose `headingLevel` so the outline stays sequential. The heading lets screen reader users find the empty region by navigating headings.
- The icon is decorative and hidden from assistive technology; the text carries the meaning.
- The component does not announce itself. If the empty state replaces content after a user action (for example a search), announce the result count in your own live region.
- Actions are ordinary buttons or links with their own names; order in the DOM is secondary then primary, matching the visual order.

#### Examples

```tsx
<EmptyState
  title="No orders found"
  description="Try another filter or search term."
  action={<Button>Clear filters</Button>}
/>

<EmptyState compact bordered={false} headingLevel={3} title="No comments" />
```

#### Related components

- Instead, see Skeleton: While data is loading: use `Skeleton`.
- Instead, see Alert: When loading failed: use `Alert` with a retry action.
- Used by: ActionList, DataTable

### ErrorText

> Standalone error text for a group of controls that has no React Aria field around it (a
hand-built set of colour options, a list of rows). Same look as `FieldError`, but it needs no
field context and renders whenever it has content: you decide when it shows. Link it from
the group with `aria-describedby` , see Field.md. Use `FieldError` inside
a field and `Alert` for an error about the whole page or form.

Shared building blocks that make every form control (`Input`, `Textarea`, `Select`, `Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`) look and behave the same: the same label, description and error styles, the same spacing, the same required marker, the same disabled treatment and the same validation timing. Tickets: ARCH-008, ARCH-009, part of GAP-003.

Most code never imports from `Field` directly: use the ready-made controls. Use the pieces when you compose a field that has no ready-made component yet (for example a custom picker built on a React Aria field).

- Import: `import { ErrorText } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Field/Field.tsx`
- Stories (Storybook title `Components/Field`): Anatomy, ErrorsAfterSaveAttempt, RealtimeValidation, StandaloneErrorText

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` |  |  | The message. Renders nothing when empty (`null`, `undefined`, `false` or `''`). |
| `id` | `string` |  |  | Element id. Defaults to a generated one; pass your own to link the group with `aria-describedby={id}` (and `aria-errormessage={id}`). |
| `announce` | `boolean` |  | `false` | Announces the message when it appears by rendering it as `role="alert"`. Off by default: the group links the text with `aria-describedby`, and focus normally moves to the first invalid control on submit, which reads it. Turn it on for an error that appears with no focus move (for example after a server response). |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLParagraphElement>` |  |  |  |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-1`, `--ds-success`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-weight-medium`

#### Exports

| Export                                 | What it is                                                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Label`                                | React Aria `Label` with the field label style (13/18, medium). `isRequired` appends the required marker.                                                                       |
| `Description`                          | React Aria `Text slot="description"`, 13/18 in `--ds-text-3`. Linked to the control with `aria-describedby`. `tone` tints it (see Toned description).                          |
| `FieldError`                           | React Aria `FieldError`: renders only while the field is invalid and the error is displayed. The message is in a `role="alert"` element. 13/18 in `--ds-danger`.               |
| `ErrorText`                            | Standalone error text for a group with no field around it. Same look as `FieldError`; `id` (generated by default), `announce` adds `role="alert"`. Renders nothing when empty. |
| `FieldMessages`                        | `Description` (with `descriptionTone`) followed by `FieldError`. Every control renders it under its box.                                                                       |
| `RequiredMark`                         | The marker alone, for fields whose label is not a `Label`.                                                                                                                     |
| `FieldMessageTone`                     | Type: `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'`, the tone of a description.                                                                                |
| `FieldLabelingProps`, `WithLabel`      | Types. `FieldLabelingProps` makes "label, `aria-label` or `aria-labelledby`" mandatory. `WithLabel<P>` helps type stories.                                                     |
| `FieldErrorMessage`, `FieldValidation` | Types for the `errorMessage` prop (a node or a function of the validation result).                                                                                             |

#### Anatomy and spacing

```
Label                       13/18 medium, --ds-text
  gap: --ds-field-gap (6px)
Control box                 border --ds-line-control, radius md, height 32/40/48
  gap: --ds-field-gap
Description                 13/18, --ds-text-3
Error                       13/18, --ds-danger
```

The description stays visible when an error shows (the handoff replaced the hint with the error). Constraints such as "8 characters or more" remain useful while the user fixes the value, and both texts are linked to the control.

#### Toned description (GAP-039)

A live check under a field ("Matches", "Over by $5", "Short by $5") is a description with a tone, not an error: the field stays valid and no `role="alert"` is added.

```tsx
<CurrencyInput
  label="Amount received"
  currency="USD"
  description="Short by $5.00"
  descriptionTone="danger"
/>
```

- `descriptionTone` (`neutral` default, `accent`, `success`, `warning`, `danger`) is supported by `Input`, `Textarea`, `Select`, `Combobox`, `NumberField`, `CurrencyInput` and `SegmentedControl`; `Description` and `FieldMessages` take `tone` / `descriptionTone`.
- The text carries the meaning; the tone only reinforces it. Write the words yourself ("Over by $5", not a bare "$5") and never rely on colour alone. The tone sets `data-tone` on the description element and nothing else changes: the description is announced exactly as before through `aria-describedby`.
- Colours are the signal tokens `--ds-accent`, `--ds-success`, `--ds-warning`, `--ds-danger`, which pass 4.5:1 on `--ds-bg`, `--ds-surface` and `--ds-surface-raised` (see `contrast-pairs.json`).
- Use `errorMessage` when the value must be fixed before submitting; use a toned description for information that can be left as it is.
- Other fields built on `FieldMessages` (`Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`, `ChoiceTiles`, `DatePicker`, `TagInput`) do not expose `descriptionTone` yet.

#### One state model (ARCH-009)

| State     | Look                                                                                                                       | Semantics                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Default   | `--ds-line-control` border, `--ds-bg` fill                                                                                 |                                                    |
| Hover     | Border brightens to `--ds-text-3`. The fill never changes, so the border stays at 3:1 or more.                             |                                                    |
| Focus     | Accent border and the 3px focus ring (`--ds-focus-ring`); forced-colors gets a system outline                              |                                                    |
| Invalid   | Danger border and danger focus ring                                                                                        | `aria-invalid`, error linked by `aria-describedby` |
| Read only | `--ds-surface` fill, same border                                                                                           | `readonly`; focusable, submitted with the form     |
| Disabled  | Label and control at `--ds-opacity-disabled`, dashed border, `--ds-surface` fill; description and error stay full strength | `disabled`; not focusable, not submitted           |
| Required  | Marker after the label                                                                                                     | `required` / `aria-required` on the control        |

Form-control borders use `--ds-line-control` and stay at 3:1 or better against the page in every state (WCAG 1.4.11). The suites assert this per state.

#### Required marker

`Label isRequired` appends the text of the `requiredMark` message (`*` by default) inside the label. The marker is `aria-hidden`: the control itself exposes "required", so announcing the marker too would repeat it. Override the text per instance (`messages={{ requiredMark: '(required)' }}`) or app-wide:

```tsx
<DSProvider locale="pt-BR" messages={{ Field: { requiredMark: '(obrigatório)' } }}>
```

#### Validation behavior: native (default), and why

React Aria fields validate in one of two modes:

- `validationBehavior="native"` (React Aria's default, kept here): the browser's constraint validation. Constraints such as `required`, `type`, `pattern` and `minLength` block submission. The error is **not displayed until the user tries to submit**; then focus moves to the first invalid field and the error appears. Custom `validate` rules report when the user commits the field (leaves it) and again on submit.
- `validationBehavior="aria"`: only ARIA attributes are set; nothing blocks submission, and the error follows every keystroke.

**Decision: `native` is the default for all fields.** It implements the product rule _errors appear only after a save attempt_ without extra code, it works without JavaScript hydration problems (the browser blocks the submit), it puts `required` on the real control and it moves focus to the first problem. `aria` suits fields that need live feedback (a username availability check, a counter): opt in per field with `validationBehavior="aria"`. A consumer that renders its own `Form` can set the mode for every field below it.

Rules for authors:

- Provide an `errorMessage` that says how to fix the problem ("Enter a complete email address."). Without one, React Aria shows the browser's own message, in the browser's language. A static `errorMessage` replaces only that browser text: a message the app supplied (a `validate` rule or `validationErrors` on a `Form`) is shown instead (GAP-009).
- To control `isInvalid` yourself (for example after a server response), pass `isInvalid` and `errorMessage`; the error shows at once.
- The error text is announced when it appears (`role="alert"`) and read again when focus lands on the field.
- Putting `<form>` in the page is enough; no wrapper component is required.

#### Errors outside a field: `ErrorText`

| Use                   | When                                                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `FieldError`          | Inside a React Aria field (`Input`, `Select`, `CheckboxGroup`, ...): validation is wired for you.                     |
| `ErrorText`           | A group of controls you built by hand (colour options, rows) with no field around it. Light, inline, under the group. |
| `Alert tone="danger"` | An error about the whole page, form or request ("Could not save the order"). Heavy, boxed.                            |

`ErrorText` renders whenever it has content, so you decide when it shows. It is not a live region by default: link it with `aria-describedby`, and move focus to the first invalid control on submit so the message is read. Set `announce` when the error appears with no focus move (it adds `role="alert"`). `aria-invalid` is not allowed on `role="group"`; if the group has a role that supports it (`radiogroup`, `listbox`), set it together with `aria-describedby`.

```tsx
const errorId = useId();
<div
  role="group"
  aria-labelledby={labelId}
  aria-describedby={error ? errorId : undefined}
>
  {options}
</div>
<ErrorText id={errorId}>{error}</ErrorText>
```

#### Accessibility

- Every control needs an accessible name: `label`, `aria-label` or `aria-labelledby`. The types enforce it; a development warning covers untyped callers.
- `Description` and `FieldError` are linked with `aria-describedby`; the order is description, then error.
- Disabled fields are exempt from contrast requirements; everything else meets 4.5:1 for text and 3:1 for borders.

#### Related components

- Used by: ColorOptionGroup

### FieldError

> Error text of a field. Renders only while the field is invalid and the error is *displayed*:
with the default `validationBehavior="native"` that is after a submit attempt (see Field.md).
The message sits in a `role="alert"` element so it is announced when it appears; on submit focus also
moves to the first invalid field, which reads it again through `aria-describedby`.

Shared building blocks that make every form control (`Input`, `Textarea`, `Select`, `Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`) look and behave the same: the same label, description and error styles, the same spacing, the same required marker, the same disabled treatment and the same validation timing. Tickets: ARCH-008, ARCH-009, part of GAP-003.

Most code never imports from `Field` directly: use the ready-made controls. Use the pieces when you compose a field that has no ready-made component yet (for example a custom picker built on a React Aria field).

- Import: `import { FieldError } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Field/Field.tsx`
- Stories (Storybook title `Components/Field`): Anatomy, ErrorsAfterSaveAttempt, RealtimeValidation, StandaloneErrorText

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `FieldErrorMessage` |  |  | The message. A function receives the validation result and decides everything. A static message replaces only the browser's own constraint text; an error the app supplied (a `validate` rule, or `validationErrors` on a `Form`) is shown instead of it. Without children, the validation errors are shown (the browser's message for native constraints). |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLElement>` |  |  |  |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-1`, `--ds-success`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-weight-medium`

#### Exports

| Export                                 | What it is                                                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Label`                                | React Aria `Label` with the field label style (13/18, medium). `isRequired` appends the required marker.                                                                       |
| `Description`                          | React Aria `Text slot="description"`, 13/18 in `--ds-text-3`. Linked to the control with `aria-describedby`. `tone` tints it (see Toned description).                          |
| `FieldError`                           | React Aria `FieldError`: renders only while the field is invalid and the error is displayed. The message is in a `role="alert"` element. 13/18 in `--ds-danger`.               |
| `ErrorText`                            | Standalone error text for a group with no field around it. Same look as `FieldError`; `id` (generated by default), `announce` adds `role="alert"`. Renders nothing when empty. |
| `FieldMessages`                        | `Description` (with `descriptionTone`) followed by `FieldError`. Every control renders it under its box.                                                                       |
| `RequiredMark`                         | The marker alone, for fields whose label is not a `Label`.                                                                                                                     |
| `FieldMessageTone`                     | Type: `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'`, the tone of a description.                                                                                |
| `FieldLabelingProps`, `WithLabel`      | Types. `FieldLabelingProps` makes "label, `aria-label` or `aria-labelledby`" mandatory. `WithLabel<P>` helps type stories.                                                     |
| `FieldErrorMessage`, `FieldValidation` | Types for the `errorMessage` prop (a node or a function of the validation result).                                                                                             |

#### Anatomy and spacing

```
Label                       13/18 medium, --ds-text
  gap: --ds-field-gap (6px)
Control box                 border --ds-line-control, radius md, height 32/40/48
  gap: --ds-field-gap
Description                 13/18, --ds-text-3
Error                       13/18, --ds-danger
```

The description stays visible when an error shows (the handoff replaced the hint with the error). Constraints such as "8 characters or more" remain useful while the user fixes the value, and both texts are linked to the control.

#### Toned description (GAP-039)

A live check under a field ("Matches", "Over by $5", "Short by $5") is a description with a tone, not an error: the field stays valid and no `role="alert"` is added.

```tsx
<CurrencyInput
  label="Amount received"
  currency="USD"
  description="Short by $5.00"
  descriptionTone="danger"
/>
```

- `descriptionTone` (`neutral` default, `accent`, `success`, `warning`, `danger`) is supported by `Input`, `Textarea`, `Select`, `Combobox`, `NumberField`, `CurrencyInput` and `SegmentedControl`; `Description` and `FieldMessages` take `tone` / `descriptionTone`.
- The text carries the meaning; the tone only reinforces it. Write the words yourself ("Over by $5", not a bare "$5") and never rely on colour alone. The tone sets `data-tone` on the description element and nothing else changes: the description is announced exactly as before through `aria-describedby`.
- Colours are the signal tokens `--ds-accent`, `--ds-success`, `--ds-warning`, `--ds-danger`, which pass 4.5:1 on `--ds-bg`, `--ds-surface` and `--ds-surface-raised` (see `contrast-pairs.json`).
- Use `errorMessage` when the value must be fixed before submitting; use a toned description for information that can be left as it is.
- Other fields built on `FieldMessages` (`Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`, `ChoiceTiles`, `DatePicker`, `TagInput`) do not expose `descriptionTone` yet.

#### One state model (ARCH-009)

| State     | Look                                                                                                                       | Semantics                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Default   | `--ds-line-control` border, `--ds-bg` fill                                                                                 |                                                    |
| Hover     | Border brightens to `--ds-text-3`. The fill never changes, so the border stays at 3:1 or more.                             |                                                    |
| Focus     | Accent border and the 3px focus ring (`--ds-focus-ring`); forced-colors gets a system outline                              |                                                    |
| Invalid   | Danger border and danger focus ring                                                                                        | `aria-invalid`, error linked by `aria-describedby` |
| Read only | `--ds-surface` fill, same border                                                                                           | `readonly`; focusable, submitted with the form     |
| Disabled  | Label and control at `--ds-opacity-disabled`, dashed border, `--ds-surface` fill; description and error stay full strength | `disabled`; not focusable, not submitted           |
| Required  | Marker after the label                                                                                                     | `required` / `aria-required` on the control        |

Form-control borders use `--ds-line-control` and stay at 3:1 or better against the page in every state (WCAG 1.4.11). The suites assert this per state.

#### Required marker

`Label isRequired` appends the text of the `requiredMark` message (`*` by default) inside the label. The marker is `aria-hidden`: the control itself exposes "required", so announcing the marker too would repeat it. Override the text per instance (`messages={{ requiredMark: '(required)' }}`) or app-wide:

```tsx
<DSProvider locale="pt-BR" messages={{ Field: { requiredMark: '(obrigatório)' } }}>
```

#### Validation behavior: native (default), and why

React Aria fields validate in one of two modes:

- `validationBehavior="native"` (React Aria's default, kept here): the browser's constraint validation. Constraints such as `required`, `type`, `pattern` and `minLength` block submission. The error is **not displayed until the user tries to submit**; then focus moves to the first invalid field and the error appears. Custom `validate` rules report when the user commits the field (leaves it) and again on submit.
- `validationBehavior="aria"`: only ARIA attributes are set; nothing blocks submission, and the error follows every keystroke.

**Decision: `native` is the default for all fields.** It implements the product rule _errors appear only after a save attempt_ without extra code, it works without JavaScript hydration problems (the browser blocks the submit), it puts `required` on the real control and it moves focus to the first problem. `aria` suits fields that need live feedback (a username availability check, a counter): opt in per field with `validationBehavior="aria"`. A consumer that renders its own `Form` can set the mode for every field below it.

Rules for authors:

- Provide an `errorMessage` that says how to fix the problem ("Enter a complete email address."). Without one, React Aria shows the browser's own message, in the browser's language. A static `errorMessage` replaces only that browser text: a message the app supplied (a `validate` rule or `validationErrors` on a `Form`) is shown instead (GAP-009).
- To control `isInvalid` yourself (for example after a server response), pass `isInvalid` and `errorMessage`; the error shows at once.
- The error text is announced when it appears (`role="alert"`) and read again when focus lands on the field.
- Putting `<form>` in the page is enough; no wrapper component is required.

#### Errors outside a field: `ErrorText`

| Use                   | When                                                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `FieldError`          | Inside a React Aria field (`Input`, `Select`, `CheckboxGroup`, ...): validation is wired for you.                     |
| `ErrorText`           | A group of controls you built by hand (colour options, rows) with no field around it. Light, inline, under the group. |
| `Alert tone="danger"` | An error about the whole page, form or request ("Could not save the order"). Heavy, boxed.                            |

`ErrorText` renders whenever it has content, so you decide when it shows. It is not a live region by default: link it with `aria-describedby`, and move focus to the first invalid control on submit so the message is read. Set `announce` when the error appears with no focus move (it adds `role="alert"`). `aria-invalid` is not allowed on `role="group"`; if the group has a role that supports it (`radiogroup`, `listbox`), set it together with `aria-describedby`.

```tsx
const errorId = useId();
<div
  role="group"
  aria-labelledby={labelId}
  aria-describedby={error ? errorId : undefined}
>
  {options}
</div>
<ErrorText id={errorId}>{error}</ErrorText>
```

#### Accessibility

- Every control needs an accessible name: `label`, `aria-label` or `aria-labelledby`. The types enforce it; a development warning covers untyped callers.
- `Description` and `FieldError` are linked with `aria-describedby`; the order is description, then error.
- Disabled fields are exempt from contrast requirements; everything else meets 4.5:1 for text and 3:1 for borders.

### FieldMessages

> Description followed by the error: the footer every field renders under its control.

Shared building blocks that make every form control (`Input`, `Textarea`, `Select`, `Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`) look and behave the same: the same label, description and error styles, the same spacing, the same required marker, the same disabled treatment and the same validation timing. Tickets: ARCH-008, ARCH-009, part of GAP-003.

Most code never imports from `Field` directly: use the ready-made controls. Use the pieces when you compose a field that has no ready-made component yet (for example a custom picker built on a React Aria field).

- Import: `import { FieldMessages } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Field/Field.tsx`
- Stories (Storybook title `Components/Field`): Anatomy, ErrorsAfterSaveAttempt, RealtimeValidation, StandaloneErrorText

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | `ReactNode` |  |  |  |
| `descriptionTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the description, see `Description`. |
| `errorMessage` | `FieldErrorMessage` |  |  |  |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-1`, `--ds-success`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-weight-medium`

#### Exports

| Export                                 | What it is                                                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Label`                                | React Aria `Label` with the field label style (13/18, medium). `isRequired` appends the required marker.                                                                       |
| `Description`                          | React Aria `Text slot="description"`, 13/18 in `--ds-text-3`. Linked to the control with `aria-describedby`. `tone` tints it (see Toned description).                          |
| `FieldError`                           | React Aria `FieldError`: renders only while the field is invalid and the error is displayed. The message is in a `role="alert"` element. 13/18 in `--ds-danger`.               |
| `ErrorText`                            | Standalone error text for a group with no field around it. Same look as `FieldError`; `id` (generated by default), `announce` adds `role="alert"`. Renders nothing when empty. |
| `FieldMessages`                        | `Description` (with `descriptionTone`) followed by `FieldError`. Every control renders it under its box.                                                                       |
| `RequiredMark`                         | The marker alone, for fields whose label is not a `Label`.                                                                                                                     |
| `FieldMessageTone`                     | Type: `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'`, the tone of a description.                                                                                |
| `FieldLabelingProps`, `WithLabel`      | Types. `FieldLabelingProps` makes "label, `aria-label` or `aria-labelledby`" mandatory. `WithLabel<P>` helps type stories.                                                     |
| `FieldErrorMessage`, `FieldValidation` | Types for the `errorMessage` prop (a node or a function of the validation result).                                                                                             |

#### Anatomy and spacing

```
Label                       13/18 medium, --ds-text
  gap: --ds-field-gap (6px)
Control box                 border --ds-line-control, radius md, height 32/40/48
  gap: --ds-field-gap
Description                 13/18, --ds-text-3
Error                       13/18, --ds-danger
```

The description stays visible when an error shows (the handoff replaced the hint with the error). Constraints such as "8 characters or more" remain useful while the user fixes the value, and both texts are linked to the control.

#### Toned description (GAP-039)

A live check under a field ("Matches", "Over by $5", "Short by $5") is a description with a tone, not an error: the field stays valid and no `role="alert"` is added.

```tsx
<CurrencyInput
  label="Amount received"
  currency="USD"
  description="Short by $5.00"
  descriptionTone="danger"
/>
```

- `descriptionTone` (`neutral` default, `accent`, `success`, `warning`, `danger`) is supported by `Input`, `Textarea`, `Select`, `Combobox`, `NumberField`, `CurrencyInput` and `SegmentedControl`; `Description` and `FieldMessages` take `tone` / `descriptionTone`.
- The text carries the meaning; the tone only reinforces it. Write the words yourself ("Over by $5", not a bare "$5") and never rely on colour alone. The tone sets `data-tone` on the description element and nothing else changes: the description is announced exactly as before through `aria-describedby`.
- Colours are the signal tokens `--ds-accent`, `--ds-success`, `--ds-warning`, `--ds-danger`, which pass 4.5:1 on `--ds-bg`, `--ds-surface` and `--ds-surface-raised` (see `contrast-pairs.json`).
- Use `errorMessage` when the value must be fixed before submitting; use a toned description for information that can be left as it is.
- Other fields built on `FieldMessages` (`Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`, `ChoiceTiles`, `DatePicker`, `TagInput`) do not expose `descriptionTone` yet.

#### One state model (ARCH-009)

| State     | Look                                                                                                                       | Semantics                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Default   | `--ds-line-control` border, `--ds-bg` fill                                                                                 |                                                    |
| Hover     | Border brightens to `--ds-text-3`. The fill never changes, so the border stays at 3:1 or more.                             |                                                    |
| Focus     | Accent border and the 3px focus ring (`--ds-focus-ring`); forced-colors gets a system outline                              |                                                    |
| Invalid   | Danger border and danger focus ring                                                                                        | `aria-invalid`, error linked by `aria-describedby` |
| Read only | `--ds-surface` fill, same border                                                                                           | `readonly`; focusable, submitted with the form     |
| Disabled  | Label and control at `--ds-opacity-disabled`, dashed border, `--ds-surface` fill; description and error stay full strength | `disabled`; not focusable, not submitted           |
| Required  | Marker after the label                                                                                                     | `required` / `aria-required` on the control        |

Form-control borders use `--ds-line-control` and stay at 3:1 or better against the page in every state (WCAG 1.4.11). The suites assert this per state.

#### Required marker

`Label isRequired` appends the text of the `requiredMark` message (`*` by default) inside the label. The marker is `aria-hidden`: the control itself exposes "required", so announcing the marker too would repeat it. Override the text per instance (`messages={{ requiredMark: '(required)' }}`) or app-wide:

```tsx
<DSProvider locale="pt-BR" messages={{ Field: { requiredMark: '(obrigatório)' } }}>
```

#### Validation behavior: native (default), and why

React Aria fields validate in one of two modes:

- `validationBehavior="native"` (React Aria's default, kept here): the browser's constraint validation. Constraints such as `required`, `type`, `pattern` and `minLength` block submission. The error is **not displayed until the user tries to submit**; then focus moves to the first invalid field and the error appears. Custom `validate` rules report when the user commits the field (leaves it) and again on submit.
- `validationBehavior="aria"`: only ARIA attributes are set; nothing blocks submission, and the error follows every keystroke.

**Decision: `native` is the default for all fields.** It implements the product rule _errors appear only after a save attempt_ without extra code, it works without JavaScript hydration problems (the browser blocks the submit), it puts `required` on the real control and it moves focus to the first problem. `aria` suits fields that need live feedback (a username availability check, a counter): opt in per field with `validationBehavior="aria"`. A consumer that renders its own `Form` can set the mode for every field below it.

Rules for authors:

- Provide an `errorMessage` that says how to fix the problem ("Enter a complete email address."). Without one, React Aria shows the browser's own message, in the browser's language. A static `errorMessage` replaces only that browser text: a message the app supplied (a `validate` rule or `validationErrors` on a `Form`) is shown instead (GAP-009).
- To control `isInvalid` yourself (for example after a server response), pass `isInvalid` and `errorMessage`; the error shows at once.
- The error text is announced when it appears (`role="alert"`) and read again when focus lands on the field.
- Putting `<form>` in the page is enough; no wrapper component is required.

#### Errors outside a field: `ErrorText`

| Use                   | When                                                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `FieldError`          | Inside a React Aria field (`Input`, `Select`, `CheckboxGroup`, ...): validation is wired for you.                     |
| `ErrorText`           | A group of controls you built by hand (colour options, rows) with no field around it. Light, inline, under the group. |
| `Alert tone="danger"` | An error about the whole page, form or request ("Could not save the order"). Heavy, boxed.                            |

`ErrorText` renders whenever it has content, so you decide when it shows. It is not a live region by default: link it with `aria-describedby`, and move focus to the first invalid control on submit so the message is read. Set `announce` when the error appears with no focus move (it adds `role="alert"`). `aria-invalid` is not allowed on `role="group"`; if the group has a role that supports it (`radiogroup`, `listbox`), set it together with `aria-describedby`.

```tsx
const errorId = useId();
<div
  role="group"
  aria-labelledby={labelId}
  aria-describedby={error ? errorId : undefined}
>
  {options}
</div>
<ErrorText id={errorId}>{error}</ErrorText>
```

#### Accessibility

- Every control needs an accessible name: `label`, `aria-label` or `aria-labelledby`. The types enforce it; a development warning covers untyped callers.
- `Description` and `FieldError` are linked with `aria-describedby`; the order is description, then error.
- Disabled fields are exempt from contrast requirements; everything else meets 4.5:1 for text and 3:1 for borders.

#### Related components

- Used by: Checkbox, CheckboxGroup, ChoiceTiles, ColorField, Combobox, DatePicker, Input, NumberField, Radio, RadioGroup, Select, Switch, TagInput, Textarea

### FieldSet

> Groups related fields under a caption: a real `fieldset` with a `legend`, an optional
description, and disabled propagation. Use it for a set of fields that answer one question
(an address, notification channels), not for every section of a form.

A group of related fields under a caption: a real `fieldset` with a `legend`, an optional description and disabled propagation.

- Import: `import { FieldSet } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/FieldSet/FieldSet.tsx`
- Stories (Storybook title `Components/FieldSet`): Default, WithDescription, Disabled, WithRadioGroup, LongText, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `legend` | `ReactNode` | yes |  | Caption of the group, required. It is the `legend`: screen readers announce it before each field in the group ("Billing address, Street"). Write it in sentence case; CSS makes it a mono caption. |
| `description` | `ReactNode` |  |  | Optional help for the whole group, linked to the fieldset with `aria-describedby`. |
| `isDisabled` | `boolean` |  | `false` | Disables every native control inside (inputs, selects, textareas, buttons), the way `<fieldset disabled>` does: they cannot be focused or submitted and dim together. Controls that are not native elements (menus, custom widgets) are not affected: disable those individually. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-field-set-gap`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-opacity-disabled`, `--ds-text-2`, `--ds-text-3`, `--ds-tracking-caption`, `--ds-weight-medium`

#### When to use

- A set of fields that answer one question: an address, a date range, notification channels.
- A group that should be disabled together.

#### When not to use

- For every section of a form: a heading is enough to organize a long form.
- For a single `RadioGroup` or `CheckboxGroup`: they already render a labelled group.

#### Anatomy

```
fieldset
  legend        mono caption, uppercase by CSS
  p             description (optional)
  div           the fields, stacked with --ds-field-set-gap
```

#### Accessibility

- A `fieldset` + `legend` is announced as a named group; screen readers read the legend before each field ("Billing address, Street").
- `isDisabled` uses the native attribute, so inputs, selects, textareas and buttons inside cannot be focused or submitted, and are skipped by constraint validation. Controls that are not native elements (menus, custom widgets) are **not** affected: disable those yourself.
- The legend uses `--ds-text-2` (the faint `--ds-text-3` is too low-contrast for a name).

#### Legend or label

The two names look different on purpose:

| Name                                                    | Looks like                                     | Use it for                                           |
| ------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------- |
| `Label` (of `Input`, `Select`, `SegmentedControl`, ...) | 13/18 medium sentence-case text in `--ds-text` | Naming one field                                     |
| `FieldSet` `legend`                                     | Mono uppercase caption in `--ds-text-2`        | Naming a group of fields, like the title of a `Card` |

The legend is a section caption, one level above the field labels it contains, so a group never reads as one more field. A single `SegmentedControl`, `RadioGroup` or `CheckboxGroup` is already a labelled group: give it a `label` and do not wrap it in a `FieldSet`. Use a `FieldSet` when several fields answer one question ("Billing address").

#### Content rules

- Legends are short nouns in sentence case ("Billing address"); CSS uppercases them. Descriptions say what the group is for, not how to fill each field.

#### Examples

```tsx
<FieldSet legend="Billing address" description="Shown on every invoice.">
  <Input label="Street" name="street" />
  <Input label="City" name="city" />
</FieldSet>

<FieldSet legend="Shipping address" isDisabled>…</FieldSet>
```

#### Related components

- Instead, see RadioGroup: For a single `RadioGroup` or `CheckboxGroup`: they already render a labelled group.
- Instead, see CheckboxGroup: For a single `RadioGroup` or `CheckboxGroup`: they already render a labelled group.

### FileUpload

> A drop zone with a "Choose files" button and the list of added files (React Aria `DropZone`
and `FileTrigger`). Dragging is a pointer shortcut; the button is the keyboard and click way
in. Files are validated (type, size, count) as they arrive and the errors are shown under the
zone; added, removed and rejected files are announced politely. The component keeps no upload
state: pass `progress` to show a bar per file.

A drop zone with a "Choose files" button and the list of added files. Built on React Aria `DropZone` and `FileTrigger`; progress bars use [Progress](../Progress/Progress.md). The component validates and lists files; it uploads nothing. Task: CMP-INP-03.

- Import: `import { FileUpload } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/FileUpload/FileUpload.tsx`
- Stories (Storybook title `Components/FileUpload`): Default, WithFiles, Validation, SingleFile, WithProgress, Disabled, LongFileName

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | `ReactNode` |  |  | Helper text under the drop zone, for the rules: "PNG, JPG or PDF up to 10 MB". Linked to the zone. |
| `accept` | `readonly string[]` |  |  | Accepted types: MIME types (`image/png`), wildcards (`image/*`) or extensions (`.pdf`). Files of other types are rejected with an error message. Also filters the file dialog. |
| `maxSize` | `number` |  |  | Largest file in bytes. Larger files are rejected with an error message. |
| `maxFiles` | `number` |  |  | Most files in the list. `1` switches to single-file mode: choosing or dropping a file replaces the current one. Default: no limit. |
| `value` | `readonly File[]` |  |  | The files, when controlled. Pair with `onChange`. |
| `defaultValue` | `readonly File[]` |  |  | The initial files when uncontrolled. |
| `onChange` | `((files: File[]) => void)` |  |  | Called with the full list after files are added or removed. |
| `onReject` | `((rejections: FileRejection[]) => void)` |  |  | Called with the files that were not added and why (wrong type, too large, too many). |
| `progress` | `ReadonlyMap<File, number>` |  |  | Upload progress per file, 0 to 100, supplied by you (the component uploads nothing and never invents progress). A file with a value under 100 shows a progress bar; 100 shows "Done"; a file without an entry shows only its size. |
| `name` | `string` |  |  | Name for form submission: the selected files are submitted as `File` entries under this name (multiple entries when several files). |
| `isDisabled` | `boolean` |  | `false` | Disables choosing, dropping and removing. |
| `className` | `string` |  |  | Class name for the root. |
| `messages` | `Partial<{ dropZone: string; dropLabel: (multiple: boolean) => string; choose: (multiple: boolean) => string; listLabel: string; remove: (name: string) => string; uploading: (name: string) => string; ... 9 more ...; removed: (name: string) => string; }>` |  |  | Message overrides for this instance. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ FileUpload: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `dropZone` | `Drop zone` | Accessible name of the drop target itself (React Aria adds a keyboard stop on it that accepts pasted files). |
| `dropLabel(multiple: boolean)` | `Drop a file here` | Text of the drop target, which names it for assistive technology. |
| `choose(multiple: boolean)` | `Choose a file` | The button that opens the file dialog (the keyboard and click alternative to dragging). |
| `listLabel` | `Added files` | Accessible name of the list of added files. |
| `remove(name: string)` | `Remove {name}` | Accessible name of the remove button of a file. |
| `uploading(name: string)` | `Uploading {name}` | Accessible name of the progress bar of a file that is uploading. |
| `done` | `Done` | Status text of a file whose progress reached 100. |
| `unitB` | `B` | Size units shown after the number. |
| `unitKB` | `KB` |  |
| `unitMB` | `MB` |  |
| `unitGB` | `GB` |  |
| `wrongType(name: string)` | `"{name}" is not an accepted file type.` | Error: the file type is not accepted. |
| `tooLarge(name: string, max: string)` | `"{name}" is larger than {max}.` | Error: the file is larger than the limit (already formatted, e.g. "10 MB"). |
| `tooMany(max: number, skipped: number)` | `Only 2 files can be added. 2 not added.` | Error: files over the count limit were not added. |
| `added(n: number)` | `2 files added` | Live announcement after files were added. |
| `removed(name: string)` | `Removed {name}` | Live announcement after a file was removed. |

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-bg`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-file-upload-dropzone-padding-block`, `--ds-file-upload-dropzone-padding-inline`, `--ds-file-upload-item-padding-block`, `--ds-file-upload-item-padding-inline`, `--ds-font-mono`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-md`, `--ds-space-2`, `--ds-space-3`, `--ds-success`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-weight-medium`

#### When to use

- Attaching one or several files to a record or form.

#### When not to use

- Image galleries, cropping or previews: a product pattern.
- A hidden uploader inside a button: use `FileTrigger` from React Aria directly.

#### Props (key ones)

| Prop                                         | Notes                                                                                                                                                       |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` / `aria-label` / `aria-labelledby`   | One is required. The root is a `group` named by it.                                                                                                         |
| `description`                                | The rules in words ("PNG, JPG or PDF up to 10 MB"), linked to the zone.                                                                                     |
| `accept`                                     | MIME types, wildcards (`image/*`) or extensions (`.pdf`). Also filters the file dialog.                                                                     |
| `maxSize`                                    | Bytes. Larger files are rejected.                                                                                                                           |
| `maxFiles`                                   | Count. `1` is single-file mode: a new file replaces the current one.                                                                                        |
| `value` / `defaultValue` / `onChange(files)` | The full `File[]` after every add or remove.                                                                                                                |
| `onReject(rejections)`                       | `{ file, reason: 'type' \| 'size' \| 'count' }[]` for files not added.                                                                                      |
| `progress`                                   | `Map<File, number>` (0 to 100), yours. Under 100 shows a bar, 100 shows "Done", no entry shows only the size.                                               |
| `name`                                       | Submits the files with the form (`FormData.getAll(name)` returns `File`s) through a hidden file input.                                                      |
| `isDisabled`, `className`, `ref`, `messages` | `messages`: `dropZone`, `dropLabel`, `choose`, `listLabel`, `remove`, `uploading`, `done`, `unit*`, `wrongType`, `tooLarge`, `tooMany`, `added`, `removed`. |

#### Behavior

- Errors are listed under the zone and replaced on the next add or removal. Sizes are formatted with `formatNumber` for the locale and unit messages (`1.5 MB`, pt-BR `1,5 MB`; steps of 1024).
- Polite live region (`role="status"`) announces "2 files added" (with the error texts), "Removed name.pdf". Pluralized per locale.
- Each file row: name (truncated), size or "Done · size", and a ghost button "Remove {name}".
- `progress` is never simulated by the component. The handoff's random progress exists only in the "WithProgress" story, driven by a timer.

#### Accessibility and keyboard

| Key                         | Behavior                                                                                     |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `Tab`                       | Zone (React Aria's own stop: `Ctrl/Cmd+V` pastes files there), Choose button, Remove buttons |
| `Enter` / `Space` on Choose | Opens the file dialog: the keyboard and click alternative to dragging                        |
| `Enter` / `Space` on Remove | Removes the file                                                                             |

Dragging is only a pointer shortcut; nothing depends on it. While files are dragged over it the zone gets an accent border and soft fill (also an outline in forced colors). The list is a `ul` named "Added files".

#### Content rules

`description` states the limits in one sentence. Error texts name the file and the limit and are produced from messages ("\"big.pdf\" is larger than 1 MB.").

#### Example

```tsx
<FileUpload
  label="Attachments"
  description="PDF up to 10 MB."
  accept={['.pdf']}
  maxSize={10 * 1024 * 1024}
  name="attachments"
  value={files}
  onChange={setFiles}
  progress={progress}
/>
```

#### Manual verification

Dropping files is automated: `FileUpload.test.tsx` performs a native drag of real files through the Chrome DevTools Protocol (`commands.dropFiles`, defined in `tests/browser-commands`), because React Aria rejects synthetic `DragEvent`s. Pasting is not automatable, so check it by hand before a release that touches this component (TEST-017):

1. Copy a file in the operating system file manager (Explorer, Finder), or copy an image.
2. Tab to the drop zone (the first stop, named "Drop zone") so it has focus.
3. Press `Ctrl+V` (`Cmd+V` on macOS). The file should be added to the list and announced ("1 file added.").
4. Repeat with Chrome, Firefox and Safari. Record any browser where the file is not added.

Why it cannot be automated: the paste handler of React Aria reads each item through `webkitGetAsEntry()`, which returns `null` for a synthetic `DataTransfer` and for an image written to the clipboard by a script (verified in Chromium: `kind: file`, `type: image/png`, entry `null`), so the item is skipped. Only a file copied by the operating system can be tested, and no browser API can put one on the clipboard.

#### Related components

- Renders: Button, Description, IconButton, Progress, VisuallyHidden

### Form

> A form built on React Aria `Form`: native validation by default, server errors through
`validationErrors`, a vertical rhythm of `--ds-form-gap` between its children, and an
optional error summary. Fields inside inherit the form's `validationBehavior`.

Put exactly one primary action in it, at the end ("Save changes"), and keep submit enabled:
a disabled submit gives no way to learn what is wrong.

A form built on React Aria `Form`: native validation by default, server errors, a consistent vertical rhythm and an optional error summary.

- Import: `import { Form } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Form/Form.tsx`
- Stories (Storybook title `Components/Form`): Default, WithErrorSummary, ServerErrors, ServerRoundTrip, WithFieldSets, AriaValidation, LongText, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `validationBehavior` | `'native' \| 'aria'` |  | `'native'` | Native validation (default) uses the browser's constraint validation: a failed submit focuses the first invalid field. `aria` marks fields invalid with ARIA only and never blocks the submit; use it when the server is the only validator. |
| `validationErrors` | `ValidationErrors` |  |  | Errors from the server, keyed by the field `name`. The matching fields become invalid and show the message; the first one takes focus (or the summary does, with `errorSummary`). Clear them (pass `undefined`) when the user edits the field or submits again. |
| `errorSummary` | `boolean` |  | `false` | Shows a `FormErrorSummary` at the top of the form. After a failed submit it takes focus and lists the invalid fields as links. Default `false`. To place the summary elsewhere, leave this off and render `FormErrorSummary` inside the form yourself. |
| `id` | `string` |  |  | The `id` of the `<form>`. Other elements link to it with the `form` attribute, for example a submit button in a `Sheet` footer: `<Button type="submit" form="order-form">`. |
| `onKeyDown` | `KeyboardEventHandler<HTMLFormElement>` |  |  | Key handlers on the `<form>`. They receive every key pressed inside a field (the events bubble), so a form-level shortcut such as `Ctrl+Enter` can live here. The form adds no key handling of its own, so yours never replaces anything. |
| `onKeyUp` | `KeyboardEventHandler<HTMLFormElement>` |  |  | Key-up handler on the `<form>`; see `onKeyDown`. |
| `onFocus` | `FocusEventHandler<HTMLFormElement>` |  |  | Fires when focus enters the form or moves between its fields (React `focus` bubbles). |
| `onBlur` | `FocusEventHandler<HTMLFormElement>` |  |  | Fires when focus leaves a field in the form; check `relatedTarget` to detect leaving the form. |
| `children` | `ReactNode` |  |  | The fields and actions of the form. |
| `messages` | `Partial<{ summaryTitle: (count: number) => string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLFormElement>` |  |  | Ref to the `<form>` element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `FormProps` (@react-types/shared): `action`, `autoCapitalize`, `autoComplete`, `encType`, `method`, `onInvalid`, `onReset`, `onSubmit`, `role`, `target`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Form: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `summaryTitle(count: number)` | `Fix 2 fields before saving` | Title of the error summary shown after a failed submit. `count` is the number of invalid fields. |

#### Design tokens used

`--ds-danger`, `--ds-danger-line`, `--ds-danger-soft`, `--ds-focus-ring-danger`, `--ds-font-sans`, `--ds-form-gap`, `--ds-form-summary-gap`, `--ds-form-summary-padding`, `--ds-fs-small`, `--ds-lh-small`, `--ds-radius-lg`, `--ds-space-5`, `--ds-text`, `--ds-text-2`, `--ds-weight-semibold`

#### When to use

- Any set of fields submitted together: create or edit a record, settings, sign-in.
- When you want a failed submit to move focus to the first problem and to list all problems.

#### When not to use

- A single search box or an auto-saving inline edit: use the field alone.
- A filter bar that updates as you type: no submit, no form.

#### Anatomy

```
form (flex column, gap --ds-form-gap)
  FormErrorSummary   (errorSummary prop, or placed by hand)
  children           fields, FieldSets, actions
```

#### Submitting from outside the form

Give the form an `id` and point a submit button at it with the `form` attribute. The browser then submits (and validates) the form natively, so the button can live anywhere in the document, such as the footer of a `Sheet`, which sits outside the body that holds the form:

```tsx
<Sheet
  title="New customer"
  footer={
    <Button type="submit" form="customer-form" variant="primary">
      Save customer
    </Button>
  }
>
  <Form id="customer-form" aria-label="New customer" onSubmit={save}>
    �
  </Form>
</Sheet>
```

Enter inside a field submits the form as usual, and a failed native validation focuses the first invalid field (or the summary). See the `SheetForm` recipe.

Keep consumer handlers (`onKeyDown`, `onFocus`, �) to what the form level needs, such as `Ctrl+Enter` to save. The form registers no React key or focus handler, so yours never replace an internal one. A handler on the form also sees keys from fields, so `event.key === 'Enter'` there is not a submit: let the browser submit instead.

#### Validation flow

1. The user presses the submit button. With native validation the browser blocks an invalid submit and fires `invalid` on each invalid field.
2. React Aria displays the errors (`FieldError`) and focuses the **first invalid field**, whose error is read through `aria-describedby`.
3. With `errorSummary`, focus goes to the **summary** instead: a `role="alert"` box, "Fix 2 fields before saving", listing each invalid field as a link that focuses it.
4. Fixing a field (on blur, when React Aria commits the edit) updates the summary; it disappears when nothing is left.
5. Server errors: set `validationErrors` after the request; the matching fields show their message and the summary (if on) lists them and takes focus. Clear them on the next submit or edit.

Keep the submit button enabled: a disabled submit gives no way to learn what is wrong.

#### Accessibility

- The summary is `role="alert"` with `tabindex="-1"`, so it is announced and can take focus programmatically. The links use the field label (the required marker is excluded) and the field's error text.
- Radio and checkbox groups count once, under the group's label.
- Give the form a name (`aria-label` or `aria-labelledby`) when it should be a landmark.

#### Content rules

- The summary title is "Fix {n} fields before saving" (pluralized; "Fix 1 field before saving"). `pt-BR` has "Corrija {n} campos antes de salvar".
- Field messages say how to fix the problem ("Enter a complete email address."). A static `errorMessage` text replaces only the browser's own constraint text ("Please fill out this field"); a server error from `validationErrors` (or a `validate` message) is shown instead of it. Use the function form when you need full control: `errorMessage={(v) => v.validationDetails.valueMissing ? 'Enter a name.' : v.validationErrors.join(' ')}`.

#### Examples

```tsx
<Form aria-label="Profile" errorSummary onSubmit={save} validationErrors={errors}>
  <Input label="Full name" name="name" isRequired />
  <FieldSet legend="Contact">
    <Input label="Email" name="email" type="email" isRequired />
  </FieldSet>
  <Button type="submit" variant="primary">
    Save changes
  </Button>
</Form>
```

### FormErrorSummary

> The error summary of a `Form`: after a failed submit (or new server errors) it takes focus,
is announced (`role="alert"`), says how many fields need fixing, and lists them as links that
move focus to the field. It renders nothing while the form is valid. Place it inside a
`Form`, or turn it on with the form's `errorSummary` prop.

A form built on React Aria `Form`: native validation by default, server errors, a consistent vertical rhythm and an optional error summary.

- Import: `import { FormErrorSummary } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Form/Form.tsx`
- Stories (Storybook title `Components/Form`): Default, WithErrorSummary, ServerErrors, ServerRoundTrip, WithFieldSets, AriaValidation, LongText, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` |  |  | Class name for the summary. |

#### Design tokens used

`--ds-danger`, `--ds-danger-line`, `--ds-danger-soft`, `--ds-focus-ring-danger`, `--ds-font-sans`, `--ds-form-gap`, `--ds-form-summary-gap`, `--ds-form-summary-padding`, `--ds-fs-small`, `--ds-lh-small`, `--ds-radius-lg`, `--ds-space-5`, `--ds-text`, `--ds-text-2`, `--ds-weight-semibold`

#### When to use

- Any set of fields submitted together: create or edit a record, settings, sign-in.
- When you want a failed submit to move focus to the first problem and to list all problems.

#### When not to use

- A single search box or an auto-saving inline edit: use the field alone.
- A filter bar that updates as you type: no submit, no form.

#### Anatomy

```
form (flex column, gap --ds-form-gap)
  FormErrorSummary   (errorSummary prop, or placed by hand)
  children           fields, FieldSets, actions
```

#### Submitting from outside the form

Give the form an `id` and point a submit button at it with the `form` attribute. The browser then submits (and validates) the form natively, so the button can live anywhere in the document, such as the footer of a `Sheet`, which sits outside the body that holds the form:

```tsx
<Sheet
  title="New customer"
  footer={
    <Button type="submit" form="customer-form" variant="primary">
      Save customer
    </Button>
  }
>
  <Form id="customer-form" aria-label="New customer" onSubmit={save}>
    �
  </Form>
</Sheet>
```

Enter inside a field submits the form as usual, and a failed native validation focuses the first invalid field (or the summary). See the `SheetForm` recipe.

Keep consumer handlers (`onKeyDown`, `onFocus`, �) to what the form level needs, such as `Ctrl+Enter` to save. The form registers no React key or focus handler, so yours never replace an internal one. A handler on the form also sees keys from fields, so `event.key === 'Enter'` there is not a submit: let the browser submit instead.

#### Validation flow

1. The user presses the submit button. With native validation the browser blocks an invalid submit and fires `invalid` on each invalid field.
2. React Aria displays the errors (`FieldError`) and focuses the **first invalid field**, whose error is read through `aria-describedby`.
3. With `errorSummary`, focus goes to the **summary** instead: a `role="alert"` box, "Fix 2 fields before saving", listing each invalid field as a link that focuses it.
4. Fixing a field (on blur, when React Aria commits the edit) updates the summary; it disappears when nothing is left.
5. Server errors: set `validationErrors` after the request; the matching fields show their message and the summary (if on) lists them and takes focus. Clear them on the next submit or edit.

Keep the submit button enabled: a disabled submit gives no way to learn what is wrong.

#### Accessibility

- The summary is `role="alert"` with `tabindex="-1"`, so it is announced and can take focus programmatically. The links use the field label (the required marker is excluded) and the field's error text.
- Radio and checkbox groups count once, under the group's label.
- Give the form a name (`aria-label` or `aria-labelledby`) when it should be a landmark.

#### Content rules

- The summary title is "Fix {n} fields before saving" (pluralized; "Fix 1 field before saving"). `pt-BR` has "Corrija {n} campos antes de salvar".
- Field messages say how to fix the problem ("Enter a complete email address."). A static `errorMessage` text replaces only the browser's own constraint text ("Please fill out this field"); a server error from `validationErrors` (or a `validate` message) is shown instead of it. Use the function form when you need full control: `errorMessage={(v) => v.validationDetails.valueMissing ? 'Enter a name.' : v.validationErrors.join(' ')}`.

#### Examples

```tsx
<Form aria-label="Profile" errorSummary onSubmit={save} validationErrors={errors}>
  <Input label="Full name" name="name" isRequired />
  <FieldSet legend="Contact">
    <Input label="Email" name="email" type="email" isRequired />
  </FieldSet>
  <Button type="submit" variant="primary">
    Save changes
  </Button>
</Form>
```

### Grid

> A CSS grid with equal columns: a fixed `columns` count, or an auto-fill grid that keeps each
item at least `minItemWidth` wide (the responsive choice for card grids). Gaps are space
token keys.

A grid of equal columns: either a fixed number, or as many as fit with a minimum item width.

- Import: `import { Grid } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Grid/Grid.tsx`
- Stories (Storybook title `Layout/Grid`): Default, TwoColumns, AutoFillMedium, AutoFillSmall, AutoFillLarge, NarrowContainer, LongText, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12` |  |  | A fixed number of equal columns (1 to 12). Items can shrink below their content width. |
| `minItemWidth` | `'sm' \| 'md' \| 'lg'` |  |  | Fills the row with as many equal columns as fit, each at least this wide: `sm` 160px, `md` 240px, `lg` 320px (`--ds-grid-min-item-*`). Collapses to one column on narrow screens. |
| `gap` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 12 \| 16 \| '1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '8' \| '12' \| '16'` |  | `4` | Space between rows and columns, as a key of the space scale (a number or its string form). Default `4`. |
| `as` | `'div' \| 'article' \| 'aside' \| 'footer' \| 'form' \| 'header' \| 'li' \| 'main' \| 'nav' \| 'ol' \| 'section' \| 'ul'` |  | `'div'` | Element to render, `div` by default. Use `ul` or `ol` for a list of `li` children: the list reset is applied and `role="list"` keeps the list semantics in Safari. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-grid-columns`, `--ds-grid-gap`, `--ds-grid-min-item-lg`, `--ds-grid-min-item-md`, `--ds-grid-min-item-sm`, `--ds-space-4`

#### When to use

- A page of cards or stats: `minItemWidth` reflows from many columns to one without media queries.
- A form laid out in two or three equal columns: `columns`.

#### When not to use

- For one column of content: use `Stack`.
- For a row that wraps and does not need aligned columns: use `Inline`.
- For tabular data: use `DataTable`.

#### Anatomy

```
div (grid, gap)
  children (one per cell)
```

#### Responsive behavior

- `minItemWidth` uses `repeat(auto-fill, minmax(min(<width>, 100%), 1fr))`: in a container narrower than the minimum, the grid is one column and never overflows.
- `columns` does not collapse by itself. For a layout that changes by screen size, prefer `minItemWidth`, or switch `columns` from the app with a media query or `useMediaQuery`.

#### Accessibility

- No semantics of its own; use `as="ul"` when the cells are list items.
- Source order is visual order for the row-first reading direction. Do not rely on CSS placement to reorder content.
- Cells can shrink (`minmax(0, 1fr)`), so long words wrap instead of widening a column.

#### Examples

```tsx
<Grid minItemWidth="md" gap={4}>
  <StatCard … />
  <StatCard … />
  <StatCard … />
</Grid>

<Grid columns={2} gap={4}>
  <Input label="First name" />
  <Input label="Last name" />
</Grid>
```

#### Related components

- Instead, see Stack: For one column of content: use `Stack`.
- Instead, see Inline: For a row that wraps and does not need aligned columns: use `Inline`.
- Instead, see DataTable: For tabular data: use `DataTable`.

### Heading

> A heading whose semantic level and visual size are separate choices, so the document outline
stays correct while the design picks the size.

A heading whose semantic level (`h1` to `h6`) and visual size are separate choices.

- Import: `import { Heading } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Heading/Heading.tsx`
- Stories (Storybook title `Typography/Heading`): Default, Display, Title, HeadingSize, LevelIndependentOfSize, LongText, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `2` | Semantic level, `h1` to `h6`. It sets the page outline for assistive technology and has nothing to do with how big the text looks: keep levels sequential and use one `h1` per page. Default `2`. |
| `size` | `'title' \| 'display' \| 'heading'` |  |  | Visual size, independent of `level`: `display` (34px, page hero), `title` (22px) or `heading` (17px). Default: `title` for level 1, `heading` for the others. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `title`, `display`, `heading`

#### Design tokens used

`--ds-font-sans`, `--ds-fs-display`, `--ds-fs-heading`, `--ds-fs-title`, `--ds-lh-display`, `--ds-lh-heading`, `--ds-lh-title`, `--ds-text`, `--ds-tracking-display`, `--ds-tracking-title`, `--ds-weight-semibold`

#### When to use

- Any heading in page content. The level builds the outline; the size is chosen for the design.

#### When not to use

- For the page title inside the header: `TopBar` renders its own heading.
- For a card caption: `Card` renders its title as a mono caption heading.
- For bold text that is not a heading: use `Text`.

#### Anatomy

```
h{level}  (semibold, size from the type scale)
```

#### Accessibility

- Keep levels sequential and use one `h1` per page. Pick the level for the outline, then the size for the look: an `h1` can use `size="heading"`, an `h4` can use `size="display"`.
- Headings use `text-wrap: balance` and break long words, so they wrap at 320px.
- Color is `--ds-text` (≥ 4.5:1 on every base surface).

#### Content rules

- Sentence case. Short and specific ("Recent orders"), no trailing punctuation.

#### Examples

```tsx
<Heading level={1} size="display">Orders</Heading>
<Heading level={2}>Recent</Heading>
<Heading level={3} size="title">Details</Heading>
```

#### Related components

- Instead, see TopBar: For the page title inside the header: `TopBar` renders its own heading.
- Instead, see Card: For a card caption: `Card` renders its title as a mono caption heading.
- Instead, see Text: For bold text that is not a heading: use `Text`.

### Icon

> An inline SVG icon (Lucide, bundled) that inherits the text color and draws a 1.5px stroke.
Decorative by default; pass `label` to make it a meaningful image.

An inline SVG icon from the curated Lucide set. It inherits the text color, draws a 1.5px stroke and is hidden from assistive technology unless you give it a `label`.

- Replaces: the runtime `unpkg.com/lucide-static` CSS-mask loading (ICON-001), text glyphs used as icons (ICON-002) and the ad hoc icon rules (ICON-003).
- Built on: `lucide-react`, bundled and tree-shakeable. No network access, no CDN.

- Import: `import { Icon } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Icon/Icon.tsx`
- Stories (Storybook title `Components/Icon`): Default, Sizes, WithLabel, InheritsColor, DirectionalRtl, Gallery

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `icon` | `LucideIcon` | yes |  | The icon to draw, one of the curated set exported from this package (for example `SearchIcon`). |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` |  | `'md'` | Size token: `xs` 12px, `sm` 14px, `md` 18px (default), `lg` 20px. |
| `label` | `string` |  |  | Accessible name. Omit it when the icon only decorates text that already names the control (the icon is then hidden from assistive technology). Set it only when the icon carries meaning on its own, outside a control that has its own name. |
| `directional` | `boolean` |  | `false` | Mirror the icon horizontally in right-to-left languages. Set it for icons that point in a reading direction (chevrons, arrows); leave it off for symmetric or universal icons. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `xs`, `sm`, `md`, `lg`

#### Design tokens used

`--ds-icon-lg`, `--ds-icon-md`, `--ds-icon-sm`, `--ds-icon-stroke-width`, `--ds-icon-xs`

#### When to use

- Next to a text label to reinforce it (button leading slot, menu item, alert, input affordance).
- Inside `IconButton`, which supplies the accessible name.
- On its own only when it carries meaning that no nearby text states. Then set `label`.

#### When not to use

- As the only carrier of meaning or status. Color and shape never replace text.
- For filled, colored or multi-color icons, emoji or Unicode glyphs. Use the set below.
- For a loading indicator that moves: use `Spinner`.
- For an icon that is not in the set. Add it to `icons.ts` with a documented use first.

#### Anatomy

A single `<svg>` (24x24 viewBox) with a `currentColor` stroke and no fill. Size and stroke come from tokens: `--ds-icon-xs|sm|md|lg` and `--ds-icon-stroke-width`.

#### The curated set

Import icons from the package, not from `lucide-react`: `import { Icon, SearchIcon } from 'loui-ds'`.

`iconSet` maps the kebab-case names below to the components and `iconNames` documents the use of each. Both are the source of the allow-list in the manifest (AI-002).

archive, arrow-down, arrow-left, arrow-right, arrow-up, bell, bot, calendar, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-up-down, circle-alert, circle-check, circle-x, copy, ellipsis, external-link, filter, info, link, loader, menu, message, minus, pencil, plus, printer, refresh, search, sparkles, star, thumbs-down, thumbs-up, trash, triangle-alert, users, x.

Generic actions added by GAP-028: `trash` (delete, always behind a confirmation), `pencil` (edit), `printer`, `archive`, `bell`, `link`, `filter`, `users`, `bot` and `sparkles`. Sort is already covered by `arrow-up`, `arrow-down` and `chevrons-up-down`. Domain icons (truck, wallet, cart, WhatsApp) belong to the consuming product, not to this set; a product keeps its own icons next to the core set and passes them to `Icon` (any Lucide-compatible component works).

#### Accessibility

- Decorative by default: `aria-hidden="true"` and `focusable="false"`.
- With `label`: `role="img"` and `aria-label`. Use short, specific names ("Saved", not "check icon").
- An icon inside a control never names the control. Put the name on the control (`IconButton label`).
- Forced colors: the stroke is `currentColor`, so it follows the system text color.
- Contrast: icons that convey meaning need 3:1 against their background (WCAG 1.4.11).
- Reduced motion: icons do not animate.

#### Content rules

- Labels are sentence case and describe the meaning ("Saved"), never the picture ("Green check").
- No emoji or text glyphs as icons (AGENTS.md section 7).

#### Examples

```tsx
import { Button, CircleCheckIcon, ChevronRightIcon, Icon, PlusIcon } from 'loui-ds';

<Button leading={<Icon icon={PlusIcon} size="sm" />}>Create order</Button>;

<Icon icon={CircleCheckIcon} label="Paid" />;

<Icon icon={ChevronRightIcon} directional />;
```

#### Related components

- Instead, see Spinner: For a loading indicator that moves: use `Spinner`.
- Used by: Accordion, AddCard, AgentCard, Alert, ApprovalCard, Banner, Breadcrumb, Checkbox, ColorOption, Combobox, CommandPalette, DataTable, DatePicker, IconButton, Link, MatrixGrid, Menu, MenuItem, MenuSection, MenuSeparator, MoreActionsMenu, NavItem, Rating, ResponseFeedback, SearchInput, Select, StatCard, StatusSteps, Stepper, SubMenu, SuggestionChip, Tag, TagGroup, Timeline, Toggle, ToolCallStep

### IconButton

> A square button with a single icon and a required accessible name.

The `label` becomes `aria-label`; there is no `title` (it would duplicate the name and is
not keyboard accessible). Set `tooltip` to show the label in a `Tooltip` on hover and focus.

A square button that holds one icon and has a required accessible name. Built on React Aria's `Button`.

- Handoff source: `components/forms/IconButton` (CMP-FRM-02).

- Import: `import { IconButton } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/IconButton/IconButton.tsx`
- Stories (Storybook title `Components/IconButton`): Default, Ghost, Variants, Sizes, Disabled, Toolbar, AccessibleName, KeyboardActivation, Focused, Hovered

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | yes |  | Accessible name, required. Say what the button does, as a verb plus object when there is one ("Add order", "Close dialog"), not what it looks like ("Plus"). |
| `icon` | `LucideIcon` | yes |  | The icon to draw: one of the curated set (for example `PlusIcon`). Decorative inside the button. |
| `variant` | `'secondary' \| 'ghost'` |  | `'secondary'` | Visual style: `secondary` (default, bordered) or `ghost` (no border at rest). |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Square size token: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `tooltip` | `boolean \| IconButtonTooltipOptions` |  |  | Shows `label` in a `Tooltip` on hover and keyboard focus. Pass `true`, or an object to add a shortcut or change the side. Off by default. The `label` stays the accessible name; the tooltip only repeats it visually for sighted mouse users. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLButtonElement>` |  |  | Ref to the underlying `<button>` element. |

##### Inherited props

- From `AriaBaseButtonProps` (react-aria): `aria-controls`, `aria-current`, `aria-disabled`, `aria-expanded`, `aria-haspopup`, `aria-pressed`, `form`, `formAction`, `formEncType`, `formMethod`, `formNoValidate`, `formTarget`, `name`, `preventFocusOnPress`, `type`, `value`
- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `ButtonProps` (react-aria): `isDisabled`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `HoverEvents` (@react-types/shared): `onHoverChange`, `onHoverEnd`, `onHoverStart`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `secondary`, `ghost`
- `size`: `sm`, `md`, `lg`

#### Design tokens used

`--ds-accent`, `--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-target-min`, `--ds-text`, `--ds-text-2`

#### When to use

- A compact action whose meaning is clear from context and icon: close, add, more actions, search.
- Toolbars and card headers where a text button would not fit.

#### When not to use

- When there is room for a text label: use `Button` with a `leading` icon. A visible word is clearer than any icon.
- For navigation: use `Link`.
- For an action whose icon is ambiguous: write the label out in a `Button`.

#### Anatomy

One native `<button>` containing a decorative `Icon`. No visible text, no `title`.

#### Accessibility

- `label` is required by the type (`label: string`), which enforces AGENTS.md section 8.
- The name is `aria-label` only. The handoff set `title` too, which duplicated the name and was not available to keyboard or touch users. Set `tooltip` to show the label (and an optional shortcut) in a `Tooltip` on hover **and** focus, dismissible with `Esc`.
- The icon is `aria-hidden` and `focusable="false"`; the button is never named by its glyph.
- Target size: 32 / 40 / 48 px, above the 24px minimum of WCAG 2.5.8 (`--ds-target-min` is also enforced as `min-inline-size` and `min-block-size`).
- Keys: `Tab` focuses, `Enter` and `Space` press.
- Focus: accent border plus 3px ring on keyboard focus; forced-colors mode repaints the transparent outline.
- Contrast: the icon uses `--ds-text` (secondary) or `--ds-text-2` (ghost) on the surface, both above 4.5:1 and well above the 3:1 needed for graphics.
- Reduced motion: only a 150ms background transition, neutralized by the global rule.

#### Content rules

- `label`: verb plus object in sentence case, without the word "button" or "icon": "Add order", "Close dialog", "More actions".
- Translate it like any other text; `IconButton` has no built-in strings.

#### Examples

```tsx
<IconButton label="Add order" icon={PlusIcon} onPress={addOrder} />

<IconButton variant="ghost" size="sm" label="More actions" icon={EllipsisIcon} />

<div role="toolbar" aria-label="Order actions">
  <IconButton variant="ghost" label="Search orders" icon={SearchIcon} />
  <IconButton variant="ghost" label="Close panel" icon={XIcon} />
</div>
```

#### Related components

- Instead, see Button: When there is room for a text label: use `Button` with a `leading` icon. A visible word is clearer than any icon.
- Instead, see Link: For navigation: use `Link`.
- Renders: Icon, Tooltip
- Used by: Alert, AppShell, AppShellNavToggle, Banner, Calendar, Drawer, FileUpload, LedgerList, Menu, MenuItem, MenuSection, MenuSeparator, MoreActionsMenu, NumberField, Pagination, Sheet, SubMenu, ToastRegion

### Inline

> Lays its children out in a horizontal row with a consistent gap. It wraps by default.
Direction follows the writing mode, so it mirrors in right-to-left languages.

A horizontal row of children with one consistent gap. It wraps by default, so a row never overflows a narrow screen.

- Import: `import { Inline } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Inline/Inline.tsx`
- Stories (Storybook title `Layout/Inline`): Default, LargeGap, JustifyBetween, JustifyEnd, AlignBaseline, Wrapping, NoWrap, AsList, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `gap` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 12 \| 16 \| '1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '8' \| '12' \| '16'` |  | `2` | Space between children, as a key of the space scale, a number or its string form (`2` = `--ds-space-2` = 8px). Default `2`. |
| `align` | `'center' \| 'start' \| 'end' \| 'baseline' \| 'stretch'` |  | `'center'` | Cross-axis (vertical) alignment. Default `center`. |
| `justify` | `'center' \| 'start' \| 'end' \| 'between'` |  | `'start'` | Main-axis (horizontal) distribution. `between` pushes the first and last child to the edges. Default `start`. |
| `wrap` | `boolean` |  | `true` | Whether children wrap onto the next line when they do not fit. Default `true`, so a row never overflows a narrow screen. |
| `as` | `'div' \| 'article' \| 'aside' \| 'footer' \| 'form' \| 'header' \| 'li' \| 'main' \| 'nav' \| 'ol' \| 'section' \| 'ul'` |  | `'div'` | Element to render, `div` by default. Use `ul` or `ol` for a list of `li` children: the list reset is applied and `role="list"` keeps the list semantics in Safari. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-inline-gap`, `--ds-space-2`

#### When to use

- Buttons in a footer, chips, a number and its caption, a toolbar of controls.
- Anything that should flow left to right (right to left in RTL) and wrap when out of room.

#### When not to use

- For a column: use `Stack`.
- For equal columns that must line up across rows: use `Grid`.
- For a form row where fields share the width: use `Grid` with `columns`.

#### Anatomy

```
div (flex row, wrap, gap)
  children
```

#### Accessibility

- No semantics of its own: choose `as` for meaning.
- Source order is visual order, so keyboard and reading order match. Do not reorder children with CSS.
- Wrapping keeps content reachable at 320px and 200% zoom (WCAG 1.4.10 reflow).
- Direction follows the writing mode, so the row mirrors in RTL.

#### Content rules

- Put the primary action last in a footer row (`justify="end"`), after the secondary action.

#### Examples

```tsx
<Inline justify="end">
  <Button>Cancel</Button>
  <Button variant="primary">Save changes</Button>
</Inline>

<Inline gap={3} align="baseline">
  <Text size="body" mono>1,240</Text>
  <Text tone="secondary">orders this month</Text>
</Inline>
```

#### Related components

- Instead, see Stack: For a column: use `Stack`.
- Instead, see Grid: For equal columns that must line up across rows: use `Grid`.

### InlineConfirm

> A two-step confirmation without a dialog: the trigger button turns into a question with
Cancel and a confirm button, in place. For a destructive action in a dense row or toolbar
where a `ConfirmDialog` would be heavy.

Focus moves to **Cancel** when the prompt opens (configurable), so Enter right after the
click cannot confirm. `Escape` cancels, but only while focus is inside the prompt (it is not a
window listener, so it does not close a surrounding `Dialog` first). When the prompt closes,
focus returns to the trigger.

A two-step confirmation in place: a button that turns into a question with Cancel and a confirm button. No dialog.

- Handoff source: `components/feedback/InlineConfirm` (CMP-FBK-07).

- Import: `import { InlineConfirm } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/InlineConfirm/InlineConfirm.tsx`
- Stories (Storybook title `Components/InlineConfirm`): Default, Asking, EscapeCancels, ConfirmByKeyboard, FocusOnConfirm, Neutral, Small, DefaultPrompt, Disabled

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | yes |  | Label of the trigger button: verb plus object ("Delete order"). |
| `onConfirm` | `() => void` | yes |  | Called when the user confirms. The prompt closes afterwards. |
| `prompt` | `string` |  |  | The question, ideally with the consequence ("Remove this line? This can't be undone."). Default from messages: "Are you sure?". |
| `confirmLabel` | `string` |  |  | Label of the confirming button. Defaults to `label`, which already names the action. |
| `tone` | `'danger' \| 'neutral'` |  | `'danger'` | `danger` (default): destructive styling. `neutral`: secondary trigger, primary confirm. |
| `initialFocus` | `'cancel' \| 'confirm'` |  | `'cancel'` | Which button gets the focus when the prompt opens. `cancel` (default) is the safe choice and the product principle for destructive actions. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Button size, `md` by default. |
| `isOpen` | `boolean` |  |  | Controlled state: whether the prompt is showing. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  | `false` | Initial state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the prompt opens or closes. |
| `isDisabled` | `boolean` |  |  | Disables the trigger. |
| `messages` | `Partial<{ cancel: string; prompt: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLSpanElement>` |  |  | Ref to the root element. |

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`
- `tone`: `danger`, `neutral`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ InlineConfirm: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `cancel` | `Cancel` | Label of the button that backs out of the confirmation. |
| `prompt` | `Are you sure?` | Default question shown next to the buttons. State the consequence when you can. |

#### Design tokens used

`--ds-font-sans`, `--ds-fs-small`, `--ds-lh-small`, `--ds-space-2`, `--ds-text-2`

#### When to use

- A destructive action in a dense row, toolbar or card where a `ConfirmDialog` would be heavy ("Delete line", "Remove member").

#### When not to use

- Deleting something important or large (a customer, an order): use `ConfirmDialog`, which can show the consequence in full.
- Reversible actions: do them and offer **Undo** in a `Toast`.
- Anything that needs more input: use `Dialog`.

#### Anatomy

```
span                       (inline-flex)
  Button                   trigger: variant danger | secondary          (idle)
─ or ─
span[role=group]           aria-labelledby = prompt                    (asking)
  span                     prompt (text-2)
  Button ghost             Cancel                                       <- initial focus
  Button danger-solid | primary   confirm
```

#### Accessibility

- **Initial focus is Cancel** by default, so Enter or Space pressed right after the click cannot confirm. The handoff auto-focused the confirm button.
- **Escape cancels, scoped.** The handler is on the prompt, not on `window`. It only fires while focus is inside the prompt, and it stops propagation, so an enclosing `Dialog` or `Sheet` stays open (tested); a second Escape closes the dialog. The handoff attached a window listener (ARCH-005).
- **Focus returns to the trigger** after Cancel, Escape or confirm.
- The prompt is a `group` named by the question; screen readers hear it when focus lands on Cancel. Button names are real text; color (red) is never the only signal.
- Cancel and confirm are normal buttons in the tab order: `Tab` from Cancel reaches confirm.
- With `defaultOpen`, focus moves to Cancel on mount; avoid it on page load.

#### Content rules

- Trigger and confirm: verb plus object, sentence case ("Delete line"). Not "Yes" or "OK".
- Prompt: a short question; add the consequence ("Remove this line? This can't be undone.").

#### Examples

```tsx
<InlineConfirm
  label="Delete line"
  prompt="Remove this line? This can't be undone."
  onConfirm={() => removeLine(line.id)}
/>
```

#### Related components

- Instead, see ConfirmDialog: Deleting something important or large (a customer, an order): use `ConfirmDialog`, which can show the consequence in full.
- Instead, see Dialog: Anything that needs more input: use `Dialog`.
- Renders: Button

### Input

> Single-line text field: label, control, description and error wired together
(`for`, `aria-describedby`, `aria-invalid`), built on React Aria `TextField`.

Consumer `onFocus`, `onBlur`, `onKeyDown` etc. are composed with the internal handlers, so
they never break the focus ring (a defect of the handoff).

Single-line text field with a label, helper text and error text wired together. Built on React Aria `TextField` + `Input`; see [Field](../Field/Field.md) for the shared states, spacing and validation timing.

- Import: `import { Input } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Input/Input.tsx`
- Stories (Storybook title `Components/Input`): Default, WithDescription, DescriptionTones, Required, Invalid, Disabled, ReadOnly, Mono, Sizes, WithAdornments, LongLabel, Focused, FocusKeepsRingWithConsumerHandlers, FullWidthInRow

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | `ReactNode` |  |  | Helper text under the control (handoff `hint`). Linked with `aria-describedby`. |
| `descriptionTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the description: `success`, `warning`, `danger` or `accent` for a live check such as "Matches" or "Over by $5". The text carries the meaning; colour only reinforces it. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text (handoff `error`). Shown while the field is invalid *and* the error is displayed: after a submit attempt with the default `validationBehavior="native"`, or at once when you control `isInvalid`. A function receives the validation result. |
| `placeholder` | `string` |  |  | Text shown while the field is empty. Never a substitute for the label. |
| `mono` | `boolean` |  | `false` | Geist Mono with tabular figures, for codes, identifiers and numbers. |
| `leading` | `ReactNode` |  |  | Decoration before the text, usually an `Icon`. Keep it decorative or give it its own name. |
| `trailing` | `ReactNode` |  |  | Content after the text: a unit, a shortcut hint (`Kbd`), or an `IconButton`. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Control height: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `fullWidth` | `boolean` |  | `false` | Take the free space of a flex row (an `Inline`): the field grows to fill it and can shrink below its content width. Off by default. In a block context the field already spans the width. |
| `className` | `string` |  |  | Class name for the field root (label, control and messages). |
| `inputClassName` | `string` |  |  | Class name for the `<input>` element. |
| `inputRef` | `Ref<HTMLInputElement>` |  |  | Ref to the `<input>` element. The `ref` prop points at the field root. |
| `messages` | `Partial<{ requiredMark: string; }>` |  |  | Message overrides for this instance (`requiredMark`). |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaTextFieldProps` (react-aria): `aria-activedescendant`, `aria-autocomplete`, `aria-controls`, `aria-haspopup`, `enterKeyHint`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `TextFieldProps` (react-aria-components): `isInvalid`
- From `TextInputDOMEvents` (@react-types/shared): `onBeforeInput`, `onCompositionEnd`, `onCompositionStart`, `onCompositionUpdate`, `onCopy`, `onCut`, `onInput`, `onPaste`, `onSelect`
- From `TextInputDOMProps` (@react-types/shared): `autoComplete`, `autoCorrect`, `inputMode`, `maxLength`, `minLength`, `pattern`, `spellCheck`, `type`
- From `Validation` (@react-types/shared): `isRequired`, `validate`
- From `ValueBase` (@react-types/shared): `defaultValue`, `onChange`, `value`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Design tokens used

`--ds-field-control-padding-inline`, `--ds-font-mono`, `--ds-space-2`, `--ds-text-3`

#### When to use

- Short free text, codes, emails, passwords, search terms, numbers typed as text. For a password with a show/hide toggle, see the `PasswordField` recipe.
- Use `mono` for codes and identifiers (`ORD-1048`).

#### When not to use

- Several lines of text: `Textarea`.
- A choice from a list: `Select`, `RadioGroup`, `Checkbox`.
- Currency or quantity entry that needs masking: a dedicated field (`CurrencyInput`, planned).

#### Anatomy

```
Label *                          required marker (aria-hidden)
[ leading  value / placeholder  trailing ]
Description
Error
```

#### Props (key ones)

| Prop                                                                | Notes                                                                                                                            |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `label`                                                             | Visible label. Without it you must pass `aria-label` or `aria-labelledby` (type error otherwise).                                |
| `description`                                                       | Helper text (handoff `hint`).                                                                                                    |
| `descriptionTone`                                                   | `neutral` (default), `accent`, `success`, `warning`, `danger`: tints the description for a live check ("Matches"). See Field.md. |
| `errorMessage`                                                      | Error text (handoff `error`), node or function of the validation result. Needs an invalid state.                                 |
| `isInvalid` / `isRequired` / `isReadOnly` / `isDisabled`            | Standard states. `isInvalid` shows the error at once.                                                                            |
| `size`                                                              | `sm` 32px, `md` 40px (default), `lg` 48px.                                                                                       |
| `fullWidth`                                                         | Take the free space of a flex row such as `Inline` (`flex: 1 1 auto`, can shrink). Off by default.                               |
| `mono`                                                              | Geist Mono with tabular figures.                                                                                                 |
| `leading` / `trailing`                                              | Adornments inside the box: an `Icon`, a unit, a `Kbd` hint, an `IconButton`.                                                     |
| `value` / `defaultValue` / `onChange(value)`                        | Controlled and uncontrolled, React Aria naming (`onChange` receives the string, not the event).                                  |
| `name`, `type`, `autoComplete`, `inputMode`, `maxLength`, `pattern` | Passed to the `<input>`; `name` and the value take part in form submission.                                                      |
| `validate`, `validationBehavior`                                    | See Field.md.                                                                                                                    |
| `inputRef` / `ref`                                                  | `inputRef` is the `<input>`, `ref` the field root.                                                                               |
| `messages`                                                          | `requiredMark` override.                                                                                                         |

All other props of React Aria `TextField` are accepted (`onFocus`, `onBlur`, `onKeyDown`, `autoFocus`, `form`, ...). They are composed with the internal handlers, never replacing them.

#### Accessibility

- Native `<input>` named by `<label for>`; description and error are in `aria-describedby`; `aria-invalid` when invalid; `required` when required.
- Keyboard: standard text editing. `Enter` submits the surrounding form. Focus is visible as the accent border plus ring; in forced-colors mode it is a system outline.
- The placeholder never replaces the label.
- Hotkeys: A consumer `onKeyDown` does not hide keys from `useHotkeys(..., { allowInEditable: true })` shortcuts: a key keeps bubbling unless your handler called `event.preventDefault()` on it. Recipe: `Enter` confirms and `Escape` cancels (both with `preventDefault()`), every other key stays a hotkey. See `docs/architecture/hotkeys.md`.
- Click anywhere in the box (including padding) focuses the input. Clicking a decorative adornment does not; make interactive adornments real buttons with their own names.

#### Content

- Label: sentence case noun ("Workspace name"). Error: how to fix it ("Enter a complete email address.").
- Description: one short sentence, no exclamation marks.

#### Example

```tsx
<Input label="Workspace name" placeholder="e.g. Northwind" description="Visible to everyone." isRequired />
<Input label="Email" type="email" name="email" errorMessage="Enter a complete email address." isRequired />
<Input aria-label="Search orders" leading={<Icon icon={SearchIcon} />} trailing={<Kbd>/</Kbd>} />
```

#### Related components

- Instead, see Textarea: Several lines of text: `Textarea`.
- Instead, see Select: A choice from a list: `Select`, `RadioGroup`, `Checkbox`.
- Instead, see RadioGroup: A choice from a list: `Select`, `RadioGroup`, `Checkbox`.
- Instead, see Checkbox: A choice from a list: `Select`, `RadioGroup`, `Checkbox`.
- Instead, see CurrencyInput: Currency or quantity entry that needs masking: a dedicated field (`CurrencyInput`, planned).
- Renders: FieldMessages, Label
- Used by: CurrencyInput

### Kbd

> A keyboard shortcut hint in mono type. With `keys` it renders `Mod` as the command symbol
on Apple platforms and as Ctrl elsewhere, and gives screen readers the spoken key names.

A keyboard shortcut hint in mono type. It renders a real `<kbd>` element.

- Import: `import { Kbd } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Kbd/Kbd.tsx`
- Stories (Storybook title `Components/Kbd`): Default, Apple, Windows, SingleKey, Arrows, WithChildren, InText, PortugueseLocale, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `keys` | `readonly string[]` |  |  | The keys of one shortcut, in order: `['Mod', 'K']`, `['Shift', 'Enter']`, `['Esc']`. Recognized names (case-insensitive): `Mod` (Command on Apple, Control elsewhere), `Cmd`, `Meta`, `Ctrl`, `Shift`, `Alt`, `Option`, `Enter`, `Esc`, `Tab`, `Backspace`, `Delete`, `Space`, arrows (`Up`, `ArrowUp`, ...), `Home`, `End`, `PageUp`, `PageDown`. Anything else is shown as typed (`K`, `/`, `1`). Symbols are hidden from assistive technology and replaced by the spoken name. |
| `children` | `ReactNode` |  |  | Free content shown as is (for example `⌘K`). Prefer `keys`, which is accessible and platform-aware. |
| `platform` | `'apple' \| 'other'` |  |  | Forces the platform used to render `Mod` and the modifier symbols. By default it is detected in the browser; during server rendering and the first client render it is `other` (Ctrl), then switches to `apple` (the command symbol) after hydration. |
| `messages` | `Partial<{ name: (key: KbdKeyId) => string; label: (key: KbdKeyId) => string; }>` |  |  | Per-instance overrides of the spoken key names and short key labels. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Kbd: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `name(key: KbdKeyId)` |  |  |
| `label(key: KbdKeyId)` |  |  |

#### Design tokens used

`--ds-font-mono`, `--ds-fs-caption`, `--ds-kbd-border`, `--ds-kbd-fg`, `--ds-kbd-height`, `--ds-kbd-padding-inline`, `--ds-lh-caption`, `--ds-radius-sm`, `--ds-space-1`, `--ds-weight-medium`

#### When to use

- Next to a command, menu item or button to show its shortcut: "Search `Ctrl K`".
- In help text and tooltips that name a key.

#### When not to use

- To register the shortcut: use `useHotkey`. `Kbd` only displays it.
- For code or file names: use `<code>`.

#### Anatomy

```
kbd.root (border, mono)
  kbd.key   symbol or text   (aria-hidden when a spoken name replaces it)
            VisuallyHidden   spoken name ("Command")
  kbd.key   K
```

#### Platform awareness

`Mod` is Command on Apple platforms and Control elsewhere. The server and the first client render use `other` (Ctrl) so hydration matches; the component then reads the real platform (`useSyncExternalStore`) and re-renders with the command symbol on Apple devices. Pass `platform` to pin it. The same detection backs `useHotkey`, so the hint always matches the key that works.

On Apple platforms modifiers use symbols (`⌘ ⌃ ⇧ ⌥ ↵ ⎋ ⇥ ⌫ ⌦`); elsewhere they are short text (`Ctrl`, `Shift`, `Alt`, `Esc`, `Del`). Command and the arrows use their symbol everywhere.

#### Accessibility

Inside a `Button` the `Kbd` is `aria-hidden` (the button's `shortcut` prop exposes the keys once through `aria-keyshortcuts`), so the shortcut never doubles the accessible name.

- Screen readers do not reliably read symbols such as `⌘`. Every symbol or abbreviation is `aria-hidden` and followed by a visually hidden spoken name from the message catalog: "Command K", "Control Shift Escape".
- When the visible text already is the name (`Enter`, `Tab`) nothing is duplicated.
- The element has no role and is not focusable: it is text. The shortcut itself must be announced where it works (for example `aria-keyshortcuts` on the control, which is the control's responsibility).
- Text is `--ds-text-2`, which keeps at least 4.5:1 on the surface (the handoff used `--ds-text-3`).

#### Content rules

- Write the logical key (`Mod`), not the platform one.
- One `Kbd` per shortcut. A sequence ("G then I") is two `Kbd`s with the word between them from your own copy; sequences are not a built-in prop.

#### Examples

```tsx
<Kbd keys={['Mod', 'K']} />
<Kbd keys={['Shift', 'Enter']} />
<Kbd keys={['Esc']} />
```

#### Related components

- Renders: VisuallyHidden
- Used by: Button, CommandPalette, SearchInput, ShortcutsHelp, Tab, TabList, TabPanel, Tabs

### Label

> The visible label of a field. Must be rendered inside a React Aria field (TextField, Select,
CheckboxGroup, RadioGroup, ...), which wires `for` / `aria-labelledby`.
With `isRequired` it appends a visible marker (text from messages) that is hidden from
assistive technology: screen readers get "required" from the control itself (`required` /
`aria-required`), so announcing the marker too would repeat it.

Shared building blocks that make every form control (`Input`, `Textarea`, `Select`, `Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`) look and behave the same: the same label, description and error styles, the same spacing, the same required marker, the same disabled treatment and the same validation timing. Tickets: ARCH-008, ARCH-009, part of GAP-003.

Most code never imports from `Field` directly: use the ready-made controls. Use the pieces when you compose a field that has no ready-made component yet (for example a custom picker built on a React Aria field).

- Import: `import { Label } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Field/Field.tsx`
- Stories (Storybook title `Components/Field`): Anatomy, ErrorsAfterSaveAttempt, RealtimeValidation, StandaloneErrorText

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` |  |  |  |
| `isRequired` | `boolean` |  | `false` | Adds the required marker after the text. The control itself must also be required. |
| `messages` | `Partial<{ requiredMark: string; }>` |  |  | Message overrides for this instance (`requiredMark`). |
| `ref` | `Ref<HTMLLabelElement>` |  |  |  |

##### Inherited props

- From `DOMRenderProps` (react-aria-components): `render`
- From `LabelProps` (react-aria-components): `elementType`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Field: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `requiredMark` | `*` | Visible marker after the label of a required field. Hidden from assistive technology. |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-1`, `--ds-success`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-weight-medium`

#### Exports

| Export                                 | What it is                                                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Label`                                | React Aria `Label` with the field label style (13/18, medium). `isRequired` appends the required marker.                                                                       |
| `Description`                          | React Aria `Text slot="description"`, 13/18 in `--ds-text-3`. Linked to the control with `aria-describedby`. `tone` tints it (see Toned description).                          |
| `FieldError`                           | React Aria `FieldError`: renders only while the field is invalid and the error is displayed. The message is in a `role="alert"` element. 13/18 in `--ds-danger`.               |
| `ErrorText`                            | Standalone error text for a group with no field around it. Same look as `FieldError`; `id` (generated by default), `announce` adds `role="alert"`. Renders nothing when empty. |
| `FieldMessages`                        | `Description` (with `descriptionTone`) followed by `FieldError`. Every control renders it under its box.                                                                       |
| `RequiredMark`                         | The marker alone, for fields whose label is not a `Label`.                                                                                                                     |
| `FieldMessageTone`                     | Type: `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'`, the tone of a description.                                                                                |
| `FieldLabelingProps`, `WithLabel`      | Types. `FieldLabelingProps` makes "label, `aria-label` or `aria-labelledby`" mandatory. `WithLabel<P>` helps type stories.                                                     |
| `FieldErrorMessage`, `FieldValidation` | Types for the `errorMessage` prop (a node or a function of the validation result).                                                                                             |

#### Anatomy and spacing

```
Label                       13/18 medium, --ds-text
  gap: --ds-field-gap (6px)
Control box                 border --ds-line-control, radius md, height 32/40/48
  gap: --ds-field-gap
Description                 13/18, --ds-text-3
Error                       13/18, --ds-danger
```

The description stays visible when an error shows (the handoff replaced the hint with the error). Constraints such as "8 characters or more" remain useful while the user fixes the value, and both texts are linked to the control.

#### Toned description (GAP-039)

A live check under a field ("Matches", "Over by $5", "Short by $5") is a description with a tone, not an error: the field stays valid and no `role="alert"` is added.

```tsx
<CurrencyInput
  label="Amount received"
  currency="USD"
  description="Short by $5.00"
  descriptionTone="danger"
/>
```

- `descriptionTone` (`neutral` default, `accent`, `success`, `warning`, `danger`) is supported by `Input`, `Textarea`, `Select`, `Combobox`, `NumberField`, `CurrencyInput` and `SegmentedControl`; `Description` and `FieldMessages` take `tone` / `descriptionTone`.
- The text carries the meaning; the tone only reinforces it. Write the words yourself ("Over by $5", not a bare "$5") and never rely on colour alone. The tone sets `data-tone` on the description element and nothing else changes: the description is announced exactly as before through `aria-describedby`.
- Colours are the signal tokens `--ds-accent`, `--ds-success`, `--ds-warning`, `--ds-danger`, which pass 4.5:1 on `--ds-bg`, `--ds-surface` and `--ds-surface-raised` (see `contrast-pairs.json`).
- Use `errorMessage` when the value must be fixed before submitting; use a toned description for information that can be left as it is.
- Other fields built on `FieldMessages` (`Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`, `ChoiceTiles`, `DatePicker`, `TagInput`) do not expose `descriptionTone` yet.

#### One state model (ARCH-009)

| State     | Look                                                                                                                       | Semantics                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Default   | `--ds-line-control` border, `--ds-bg` fill                                                                                 |                                                    |
| Hover     | Border brightens to `--ds-text-3`. The fill never changes, so the border stays at 3:1 or more.                             |                                                    |
| Focus     | Accent border and the 3px focus ring (`--ds-focus-ring`); forced-colors gets a system outline                              |                                                    |
| Invalid   | Danger border and danger focus ring                                                                                        | `aria-invalid`, error linked by `aria-describedby` |
| Read only | `--ds-surface` fill, same border                                                                                           | `readonly`; focusable, submitted with the form     |
| Disabled  | Label and control at `--ds-opacity-disabled`, dashed border, `--ds-surface` fill; description and error stay full strength | `disabled`; not focusable, not submitted           |
| Required  | Marker after the label                                                                                                     | `required` / `aria-required` on the control        |

Form-control borders use `--ds-line-control` and stay at 3:1 or better against the page in every state (WCAG 1.4.11). The suites assert this per state.

#### Required marker

`Label isRequired` appends the text of the `requiredMark` message (`*` by default) inside the label. The marker is `aria-hidden`: the control itself exposes "required", so announcing the marker too would repeat it. Override the text per instance (`messages={{ requiredMark: '(required)' }}`) or app-wide:

```tsx
<DSProvider locale="pt-BR" messages={{ Field: { requiredMark: '(obrigatório)' } }}>
```

#### Validation behavior: native (default), and why

React Aria fields validate in one of two modes:

- `validationBehavior="native"` (React Aria's default, kept here): the browser's constraint validation. Constraints such as `required`, `type`, `pattern` and `minLength` block submission. The error is **not displayed until the user tries to submit**; then focus moves to the first invalid field and the error appears. Custom `validate` rules report when the user commits the field (leaves it) and again on submit.
- `validationBehavior="aria"`: only ARIA attributes are set; nothing blocks submission, and the error follows every keystroke.

**Decision: `native` is the default for all fields.** It implements the product rule _errors appear only after a save attempt_ without extra code, it works without JavaScript hydration problems (the browser blocks the submit), it puts `required` on the real control and it moves focus to the first problem. `aria` suits fields that need live feedback (a username availability check, a counter): opt in per field with `validationBehavior="aria"`. A consumer that renders its own `Form` can set the mode for every field below it.

Rules for authors:

- Provide an `errorMessage` that says how to fix the problem ("Enter a complete email address."). Without one, React Aria shows the browser's own message, in the browser's language. A static `errorMessage` replaces only that browser text: a message the app supplied (a `validate` rule or `validationErrors` on a `Form`) is shown instead (GAP-009).
- To control `isInvalid` yourself (for example after a server response), pass `isInvalid` and `errorMessage`; the error shows at once.
- The error text is announced when it appears (`role="alert"`) and read again when focus lands on the field.
- Putting `<form>` in the page is enough; no wrapper component is required.

#### Errors outside a field: `ErrorText`

| Use                   | When                                                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `FieldError`          | Inside a React Aria field (`Input`, `Select`, `CheckboxGroup`, ...): validation is wired for you.                     |
| `ErrorText`           | A group of controls you built by hand (colour options, rows) with no field around it. Light, inline, under the group. |
| `Alert tone="danger"` | An error about the whole page, form or request ("Could not save the order"). Heavy, boxed.                            |

`ErrorText` renders whenever it has content, so you decide when it shows. It is not a live region by default: link it with `aria-describedby`, and move focus to the first invalid control on submit so the message is read. Set `announce` when the error appears with no focus move (it adds `role="alert"`). `aria-invalid` is not allowed on `role="group"`; if the group has a role that supports it (`radiogroup`, `listbox`), set it together with `aria-describedby`.

```tsx
const errorId = useId();
<div
  role="group"
  aria-labelledby={labelId}
  aria-describedby={error ? errorId : undefined}
>
  {options}
</div>
<ErrorText id={errorId}>{error}</ErrorText>
```

#### Accessibility

- Every control needs an accessible name: `label`, `aria-label` or `aria-labelledby`. The types enforce it; a development warning covers untyped callers.
- `Description` and `FieldError` are linked with `aria-describedby`; the order is description, then error.
- Disabled fields are exempt from contrast requirements; everything else meets 4.5:1 for text and 3:1 for borders.

#### Related components

- Used by: CheckboxGroup, ChoiceTiles, ColorField, ColorOptionGroup, Combobox, DatePicker, Input, NumberField, Radio, RadioGroup, Select, Slider, TagInput, Textarea

### LedgerList

> A list of signed ledger entries: date, title, optional sub line, a signed amount and an
optional running balance. The sign is text (`+` / `−`) as well as color. Built as a `ul`.

Amounts are integers in minor units (ADR-0006) formatted with `Intl`: pass `currency` for
money, `format` for anything else, or neither for plain quantities.

Import it from `loui-ds/patterns`.

A list of signed entries: date, title, optional sub line, a signed amount and an optional running balance, with optional edit and delete buttons per row. Rows can be fixed (no buttons) and the date is optional. The sign is shown as text and color. Import it from `loui-ds/patterns`.

- Handoff source: `components/erp/LedgerList.jsx` (TODO `CMP-PAT-12`).

- Import: `import { LedgerList } from 'loui-ds/patterns';`
- Status: stable
- Source: `src/patterns/LedgerList/LedgerList.tsx`
- Stories (Storybook title `Patterns/LedgerList`): Default, NegativeAsSuccess, NegativeNeutral, WithoutBalance, Quantities, CustomFormat, LongText, NarrowEditableAndDeletable, Empty, Deletable, KeyboardDelete, EditableAndDeletable, EditOnly, EditInSheet, EditInline, MixedDeletableAndFixed, WithoutDate, NoDatesAtAll, Portuguese, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `entries` | `readonly LedgerEntry[]` | yes |  | The entries, in display order (usually newest first). |
| `currency` | `string` |  |  | ISO 4217 currency code ("USD"). When set, amounts and balances are formatted as money with `formatCurrency` (minor units). Ignored when `format` is given. |
| `format` | `(value: number) => string` |  |  | Custom formatter for amounts and balances, receiving a number in the same unit as `delta`. The amount of an entry is passed as an absolute value (the sign is shown separately). Without `currency` or `format`, numbers are formatted for the locale. |
| `negativeTone` | `'neutral' \| 'success' \| 'warning' \| 'danger'` |  | `'danger'` | Color of negative amounts: `neutral`, `success`, `warning` or `danger` (default). The `-` sign is always shown too. Pick the tone by what the subtraction means (an expense is `danger`, a payment out of a balance owed may be `success`). |
| `dateStyle` | `'short' \| 'medium' \| 'long' \| 'full' \| 'monthDay' \| 'monthYear'` |  | `'monthDay'` | Format of each entry's date (`formatDate` styles). Default `monthDay`. |
| `onDelete` | `(entry: LedgerEntry) => void` |  |  | Adds a "Delete entry" button to each row (except entries with `isDeletable: false`) and calls this with the entry. The component only reports the request: the consumer must confirm it (dialog or inline confirmation) before data is removed, and offer Undo afterwards. |
| `onEdit` | `(entry: LedgerEntry) => void` |  |  | Adds an "Edit entry" button (pencil icon) before the delete button of each row (except entries with `isEditable: false`) and calls this with the entry. The component only reports the request: the consumer shows the editing UI, either a `Sheet` or an inline field in the row's place. When a sheet closes, focus returns to the edit button that opened it. |
| `messages` | `Partial<{ balance: (amount: string) => string; editEntry: (title: string) => string; deleteEntry: (title: string) => string; }>` |  |  | Message overrides for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ LedgerList: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `balance(amount: string)` | `Balance {amount}` | Label of the running balance after an entry. `amount` is already formatted. |
| `editEntry(title: string)` | `Edit entry {title}` | Accessible name of the edit button of an entry; `title` is the entry's title. |
| `deleteEntry(title: string)` | `Delete entry {title}` | Accessible name of the delete button of an entry; `title` is the entry's title. |

#### Design tokens used

`--ds-control-h-sm`, `--ds-danger`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-ledger-list-date-width`, `--ds-ledger-list-gap`, `--ds-ledger-list-padding-inline`, `--ds-ledger-list-text-gap`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-line-subtle`, `--ds-space-1`, `--ds-space-3`, `--ds-space-4`, `--ds-success`, `--ds-text`, `--ds-text-2`, `--ds-warning`, `--ds-weight-medium`

#### When to use

- A short history of changes to a balance or a quantity: account activity, wallet movements, stock adjustments.
- When the running balance after each entry matters.

#### When not to use

- Large, sortable or filterable data: use `DataTable`.
- A feed of events with no amounts: use a plain list.

#### Anatomy

```
ul aria-label
  li[data-direction=positive|negative|zero]
    time[datetime]                 formatDate(date, locale, dateStyle)   (only when the entry has a date)
    title · sub
    amount                         "+" | "−" text sign + number   (color by negativeTone)
    balance                        "Balance $125.00"              (optional)
    button "Edit entry …"          (only with onEdit and isEditable !== false)
    button "Delete entry …"        (only with onDelete and isDeletable !== false)
```

#### Accessibility

- A `ul` of `li`; the list should be named with `aria-label` or `aria-labelledby`.
- The sign is text (`+` or the minus sign U+2212), so meaning never depends on color. Positive amounts use ink, negative ones the chosen tone, zero uses secondary text.
- Dates are `<time datetime>`. The balance is labelled by text ("Balance $125.00"), not by position.
- Edit buttons are `IconButton`s named "Edit entry {title}" and come before the delete button in the tab order. Rows with `isEditable: false` have none.
- Delete buttons are `IconButton`s named "Delete entry {title}" (one per deletable row, distinguishable); they are 32px. Rows with `isDeletable: false` have no button, so they are skipped by `Tab`.
- The component only calls `onDelete(entry)`; it never removes anything or asks for confirmation (AGENTS.md section 5.5). The consumer opens a confirmation dialog (title "Delete X?", the consequence, a danger button naming the action, initial focus on Cancel) in `onDelete`, removes the entry on confirm and then shows a toast with Undo.
- Text truncates with an ellipsis; long titles do not push the amounts out.

#### Content rules

- Titles say what happened in sentence case ("Payment received"); the sub line holds the reference.
- Amounts are integers in minor units (ADR-0006); never pre-format them.

#### Examples

```tsx
import { LedgerList } from 'loui-ds/patterns';

<LedgerList
  aria-label="Account activity"
  currency="USD"
  entries={[
    { id: '2', date: '2026-03-12', title: 'Payment received', delta: 5000, balance: 15000 },
    { id: '1', date: '2026-03-01', title: 'Service fee', delta: -1000, balance: 10000 },
  ]}
  onDelete={askToDelete}
/>;
```

A drawer that mixes a fixed opening balance with deletable payments, where `askToDelete` opens the confirmation dialog:

```tsx
<LedgerList
  aria-label="Account activity"
  currency="USD"
  entries={[
    { id: '2', date: '2026-03-12', title: 'Payment received', delta: 5000, balance: 15000 },
    { id: '1', title: 'Opening balance', delta: 10000, balance: 10000, isDeletable: false },
  ]}
  onDelete={askToDelete}
/>
```

#### Narrow containers

The list is a size container. At 480 px or less the date moves under the title as a meta line, the padding shrinks and the amount, balance and actions columns stay fixed, so titles keep a readable width. The DOM and reading order do not change.

#### Related components

- Instead, see DataTable: Large, sortable or filterable data: use `DataTable`.
- Renders: IconButton

### Legend

> A list of the series of a chart: swatch, name and, optionally, a value. With `interactive`
each item is a toggle button that hides or shows its series, and the legend reports the
hidden ids so the chart can leave those series out (`StackedBar` does this itself; with
`Chart` keep `hiddenIds` in state and filter your data).

The swatch is never the only identification: every item has its text label, a hatch pattern
tells apart series beyond the fourth, and a hidden series shows a hollow swatch and a struck
label in addition to the pressed state read by screen readers.

A list of the series of a chart: swatch, name and, optionally, a value. With `interactive` each item is a toggle button that hides or shows its series, and the legend reports which ones are hidden so the chart can leave them out.

- Import: `import { Legend } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Legend/Legend.tsx`
- Stories (Storybook title `Components/Legend`): Default, Vertical, NamesOnly, EightSeries, ExplicitColors, Interactive, InteractiveWithHiddenSeries, LongLabels, WithChart, PortugueseBrazil, RightToLeft, WithShare, ShareOfTotal

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly LegendItem[]` | yes |  | The series, in the same order as in the chart (the order sets the swatch of items without `color`). |
| `orientation` | `'horizontal' \| 'vertical'` |  | `'horizontal'` | `horizontal` (default) wraps items in a row; `vertical` stacks them, one per line. |
| `interactive` | `boolean` |  | `false` | Turns each item into a toggle button (`aria-pressed`: pressed means the series is shown), so readers can hide series in the chart that consumes the legend. Off by default: a plain list. |
| `hiddenIds` | `readonly string[]` |  |  | Controlled list of hidden series ids (interactive legends). |
| `defaultHiddenIds` | `readonly string[]` |  | `[]` | Initial hidden series ids when uncontrolled. |
| `onHiddenIdsChange` | `(hiddenIds: string[]) => void` |  |  | Called with the new list of hidden ids whenever the user toggles an item. |
| `showShare` | `boolean` |  | `false` | Prints the share of each item (its `amount` over the denominator) in a column of its own, formatted with `Intl` for the active locale. When an item also has a `value`, both show, in two aligned columns (value, then share). Hidden series print no share and leave the denominator. Percentages are rounded one by one, so the printed shares may sum to 99% or 101%; raise `shareDigits` when that matters, the legend never adjusts them. |
| `shareOf` | `number` |  |  | Denominator of the shares, in the unit of `amount`. Default: the sum of the amounts of the visible (not hidden) items. Pass the real total when the items are only part of a whole. |
| `shareDigits` | `number` |  | `0` | Decimals of the printed shares. Default `0`. |
| `messages` | `Partial<{ label: string; toggleHint: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Legend: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `label` | `Legend` | Accessible name of the legend list, unless the consumer passes `aria-label` or `aria-labelledby`. |
| `toggleHint` | `Press a series to show or hide it.` | Accessible description of an interactive legend: what pressing an item does. Read after the name of the list. |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-chart-series-1`, `--ds-chart-series-2`, `--ds-chart-series-3`, `--ds-chart-series-4`, `--ds-chart-series-hatch-size`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-fs-label`, `--ds-fs-small`, `--ds-legend-color`, `--ds-legend-gap`, `--ds-legend-share-col-w`, `--ds-legend-swatch-size`, `--ds-lh-small`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-2`, `--ds-surface-hover`, `--ds-target-min`, `--ds-text`, `--ds-text-2`, `--ds-text-3`

#### When to use

- Naming the series of a multi-series chart (`StackedBar` renders one itself).
- Letting readers hide series to compare the rest.
- Next to a `Chart` when you plot one series at a time and let the reader pick which.

#### When not to use

- One series: name the chart instead.
- Choosing between views or filters unrelated to a chart: use `SegmentedControl`, `ToggleGroup` or `Tabs`.
- Showing the parts of a single bar with percentages: `ProportionBar` has its own legend.

#### Anatomy

```
ul[aria-label="Legend"]
  li  swatch (aria-hidden) · name · value (optional)
  li  button[aria-pressed] (interactive)  swatch · name · value
VisuallyHidden  hint, linked with aria-describedby (interactive only)
```

#### Props (key ones)

| Prop                | Type                                       | Default        | Notes                                                      |
| ------------------- | ------------------------------------------ | -------------- | ---------------------------------------------------------- |
| `items`             | `{ id, label, value?, amount?, color? }[]` | -              | Same order as the chart: the position sets the swatch      |
| `showShare`         | `boolean`                                  | `false`        | Prints each item's share of the `amount`s (needs `amount`) |
| `shareOf`           | `number`                                   | sum of visible | Denominator of the shares                                  |
| `shareDigits`       | `number`                                   | `0`            | Decimals of the printed shares                             |
| `orientation`       | `'horizontal' \| 'vertical'`               | `'horizontal'` | Row that wraps, or one item per line                       |
| `interactive`       | `boolean`                                  | `false`        | Items become toggle buttons                                |
| `hiddenIds`         | `readonly string[]`                        |                | Controlled hidden series                                   |
| `defaultHiddenIds`  | `readonly string[]`                        | `[]`           | Initial hidden series when uncontrolled                    |
| `onHiddenIdsChange` | `(ids: string[]) => void`                  |                | Called on every toggle                                     |
| `messages`          | `Partial<messages>`                        |                | `label` (list name), `toggleHint`                          |

#### Showing the share

Give each item a numeric `amount` and set `showShare`: the legend prints `amount / denominator` with `formatPercent` for the provider locale. The denominator is the sum of the visible items (hidden series leave it, and print no share) unless you pass `shareOf` because the items are only part of a whole. `value` still works as a free node; with both, a vertical legend lines value and share up in two columns (tabular mono). Percentages are rounded one by one, so three equal items show 33% each and the shares may sum to 99% or 101%. The legend never fudges them; raise `shareDigits` if that matters. `StackedBar` uses this through its `legendShare` prop.

#### Telling series apart without color

The swatch follows the same neutral ramp as `StackedBar` and `ProportionBar` (`--ds-chart-series-1` to `-4`, which are `text`, `text-2`, `text-3` and `line-control`). From the fifth series on the ramp repeats with a hatch pattern, so up to eight series look different. Beyond that, pass `color` or group the tail into "Other". The text label always identifies the series; the swatch only helps sighted users.

A hidden series is shown with a hollow swatch and a struck-through label, in addition to `aria-pressed="false"`.

#### Accessibility

- A real list named "Legend" (override with `aria-label` or `aria-labelledby`).
- Interactive items are native buttons (React Aria `ToggleButton`): `Tab` moves between them, `Space` and `Enter` toggle. `aria-pressed="true"` means the series is **shown**. The list is described by a hint ("Press a series to show or hide it.").
- Toggle buttons are at least 24 px tall (target size 2.5.8) and have a visible focus ring; forced colors use system colors for swatches and focus.
- The chart that consumes the legend must update visibly when a series is toggled. If it can end up with nothing to show, say so in text (`StackedBar` does).

#### Content rules

- Series names are short nouns in sentence case ("Online", "Store").
- Values are formatted text; use `Intl` helpers for the locale.

#### Example

```tsx
const [hidden, setHidden] = useState<string[]>([]);

<Legend
  interactive
  items={[
    { id: 'online', label: 'Online' },
    { id: 'store', label: 'Store' },
  ]}
  hiddenIds={hidden}
  onHiddenIdsChange={setHidden}
/>;
```

#### Related components

- Instead, see SegmentedControl: Choosing between views or filters unrelated to a chart: use `SegmentedControl`, `ToggleGroup` or `Tabs`.
- Instead, see ToggleGroup: Choosing between views or filters unrelated to a chart: use `SegmentedControl`, `ToggleGroup` or `Tabs`.
- Instead, see Tabs: Choosing between views or filters unrelated to a chart: use `SegmentedControl`, `ToggleGroup` or `Tabs`.
- Instead, see ProportionBar: Showing the parts of a single bar with percentages: `ProportionBar` has its own legend.
- Renders: VisuallyHidden
- Used by: StackedBar

### Link

> A link built on React Aria's `Link`. With `href` it renders a real `<a>` and uses the router
set on `DSProvider` for client-side navigation. Links that open a new tab (`target="_blank"`)
get `rel="noopener noreferrer"`, an external-link icon and a hidden note for screen readers.

A link to another page, section or site. Built on React Aria's `Link`: a real `<a href>` that uses the router set on `DSProvider` for client-side navigation.

- Handoff source: none (the handoff only had underlined `<a>` styles); part of GAP-002.

- Import: `import { Link } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Link/Link.tsx`
- Stories (Storybook title `Components/Link`): Default, InText, Standalone, External, Disabled, KeyboardActivation, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | `'inline' \| 'standalone'` |  | `'inline'` | - `inline` (default): underlined, for links inside running text. Color alone does not   identify a link (WCAG 1.4.1), so the underline is part of the design. - `standalone`: no underline at rest (underlined on hover and focus). Only where the context   makes it obvious that it is a link: a navigation list, a "View all" line under a heading. |
| `children` | `ReactNode` |  |  | Link text. Describe the destination or action ("Pricing details"), never "click here". |
| `messages` | `Partial<{ opensInNewTab: string; }>` |  |  | Override the built-in messages for this instance. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLAnchorElement>` |  |  | Ref to the underlying `<a>` element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `AriaLinkOptions` (react-aria): `isDisabled`
- From `AriaLinkProps` (react-aria): `aria-current`
- From `DOMProps` (@react-types/shared): `id`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `HoverEvents` (@react-types/shared): `onHoverChange`, `onHoverEnd`, `onHoverStart`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `LinkDOMProps` (@react-types/shared): `download`, `href`, `hrefLang`, `ping`, `referrerPolicy`, `rel`, `routerOptions`, `target`
- From `PossibleLinkDOMRenderProps` (react-aria-components): `render`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `inline`, `standalone`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Link: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `opensInNewTab` | `(opens in a new tab)` |  |

#### Design tokens used

`--ds-accent`, `--ds-focus-ring`, `--ds-opacity-disabled`, `--ds-radius-sm`, `--ds-space-1`

#### When to use

- To go somewhere: another route, a section (`#id`), a document or an external site.
- Inside running text (`inline`), or as a quiet navigation line such as "View all orders" (`standalone`).

#### When not to use

- To run an action in place (save, delete, open a dialog): use `Button`.
- For a styled call to action that happens to navigate: still a link semantically, but use a `Button` with `href` when it is the primary action of the screen (planned with the button-as-link variant).

#### Variants

| Variant      | At rest   | Hover and keyboard focus | Use                                                                      |
| ------------ | --------- | ------------------------ | ------------------------------------------------------------------------ |
| `inline`     | underline | thicker underline        | Links inside sentences. Default.                                         |
| `standalone` | none      | underline                | Navigation lists, "View all" lines. Only where context makes it obvious. |

Color alone never identifies a link (WCAG 1.4.1), so inline links are always underlined. The accent color (`--ds-accent`) is reserved for focus, selection and links.

#### Routing

Wrap the app once: `<DSProvider navigate={router.push} useHref={router.resolve}>`. Links with a relative `href` then navigate without a page reload; modified clicks (Ctrl/Cmd, middle button) and `target="_blank"` keep the browser behavior.

#### Accessibility

- Real `<a href>`: opens in a new tab with the context menu, can be copied, works without JavaScript.
- Keys: `Tab` focuses, `Enter` follows. (`Space` does not activate a link, by design.)
- Focus: 3px accent ring through `data-focus-visible`; forced-colors mode repaints the transparent outline and system link colors apply.
- Links that open a new tab: the name ends with "(opens in a new tab)" for screen readers (hidden text from the `Link` messages) and a decorative icon shows it visually. `rel="noopener noreferrer"` is added automatically.
- Contrast: accent `#8AB4FF` on the dark surfaces is well above 4.5:1.
- Target size: inline links in text are exempt from WCAG 2.5.8; standalone links should sit in a 24px-high row.
- Reduced motion: hover changes decoration thickness only, no animation.

#### Content rules

- Link text describes the destination or action and makes sense out of context: "Pricing details", "Download invoice". Never "click here" or "read more".
- Sentence case, no trailing punctuation inside the link, no emoji.
- Do not repeat the word "link". The role is announced.

#### Examples

```tsx
<p>
  Read the <Link href="/pricing">pricing details</Link> before you change a plan.
</p>

<Link variant="standalone" href="/orders">View all orders</Link>

<Link href="https://example.com/docs" target="_blank">Documentation</Link>
```

#### Related components

- Instead, see Button: To run an action in place (save, delete, open a dialog): use `Button`.
- Renders: Icon, VisuallyHidden
- Used by: Citation, SourceList

### MatrixGrid

> A matrix of toggle cells: rows by columns, each cell linking or unlinking one row with one
column. It is an ARIA `grid` with roving focus: the grid is one tab stop, the arrow keys move
between cells (`Home` / `End` within a row, `Ctrl+Home` / `Ctrl+End` to the first / last
cell), and `Space` or `Enter` toggles. Arrow keys follow the reading direction.

The row and the column of the focused cell get a subtle surface step (a visual aid; the focus
ring and the cell name carry the meaning). The column header row and the row header column stay
fixed while the region scrolls; give the root a height (`className`) to scroll vertically.
`onToggle` may return a promise for a per-cell pending state (see `onToggle`).

Each cell is a button named "{row} · {column}: linked" / "not linked" (messages). The grid
scrolls horizontally inside a labelled, focusable region.

Import it from `loui-ds/patterns`.

A rows-by-columns matrix of toggle cells, where each cell links or unlinks one row with one column (for example which colors a product comes in). It is an ARIA `grid` with roving focus and full arrow-key navigation. Import it from `loui-ds/patterns`.

- Handoff source: `components/erp/MatrixGrid.jsx` (TODO `CMP-PAT-11`).

- Import: `import { MatrixGrid } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/MatrixGrid/MatrixGrid.tsx`
- Stories (Storybook title `Patterns/MatrixGrid`): Default, WithCountAndHint, CheckContrast, WithoutColors, ManyColumns, LongLabels, Empty, KeyboardNavigation, AsyncToggle, StickyHeaders, Portuguese, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `aria-label` | `string` | yes |  | Accessible name of the grid ("Product colors"). The scroll region around it is named from it too. |
| `rows` | `readonly MatrixGridRow[]` | yes |  | The rows, in display order. Sort them yourself (alphabetically by default). |
| `columns` | `readonly MatrixGridColumn[]` | yes |  | The columns, in display order. |
| `isLinked` | `(rowId: string, columnId: string) => boolean` | yes |  | Whether a row and a column are linked. Called for every cell on each render; keep it cheap. |
| `onToggle` | `(rowId: string, columnId: string) => unknown` | yes |  | Called with the row and column ids when the user toggles a cell. Update your state in it.  It may return a promise (a request to save the link). While it is pending the cell shows a spinner, is `aria-busy` and ignores further toggles. The grid never flips a cell by itself: the cell shows what `isLinked` returns, so if you update optimistically, revert in `onToggleError`. A rejected promise calls `onToggleError`. |
| `onToggleError` | `(error: unknown, rowId: string, columnId: string) => void` |  |  | Called when the promise returned by `onToggle` rejects, with the error and the cell's ids. Revert an optimistic update here and tell the user (a toast). The grid also announces "Couldn't update {row} · {column}. Try again." in a visually hidden status. |
| `cornerLabel` | `string` |  |  | Caption of the first (row header) column. Without it a visually hidden "Row" is used. |
| `countLabel` | `string` |  |  | Adds a last column with the number of linked cells per row; this is its header ("Linked"). |
| `hint` | `ReactNode` |  |  | Help text under the grid, linked to it with `aria-describedby`. |
| `messages` | `Partial<{ cell: (row: string, column: string, linked: boolean) => string; cellPending: (row: string, column: string, linked: boolean) => string; toggleFailed: (row: string, column: string) => string; scrollRegion: (name: string) => string; rowHeader: string; }>` |  |  | Message overrides for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ MatrixGrid: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `cell(row: string, column: string, linked: boolean)` | `{row} · {column}: not linked` | Accessible name of a toggle cell: the row, the column and the state of the link. |
| `cellPending(row: string, column: string, linked: boolean)` | `{row} · {column}: not linked, saving` | Accessible name of a cell while its toggle request is running. |
| `toggleFailed(row: string, column: string)` | `Couldn't update {row} · {column}. Try again.` | Status announced when a toggle request fails; the cell keeps its previous state. |
| `scrollRegion(name: string)` | `{name}, scrollable` | Accessible name of the focusable scroll region around the grid. `name` is the grid's name. |
| `rowHeader` | `Row` | Hidden header text of the first column when no `cornerLabel` is given. |

#### Design tokens used

`--ds-accent`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-line`, `--ds-line-control`, `--ds-line-subtle`, `--ds-matrix-grid-cell-size`, `--ds-matrix-grid-color`, `--ds-matrix-grid-column-header-padding-inline`, `--ds-matrix-grid-column-width`, `--ds-matrix-grid-columns`, `--ds-matrix-grid-count-width`, `--ds-matrix-grid-label-width`, `--ds-matrix-grid-padding-inline`, `--ds-matrix-grid-row-header-gap`, `--ds-matrix-grid-row-min-height`, `--ds-matrix-grid-sticky-z-index`, `--ds-radius-lg`, `--ds-radius-md`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-surface`, `--ds-surface-row-hover`, `--ds-swatch-ring`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-text-inverse`, `--ds-tracking-caption`, `--ds-weight-medium`

#### When to use

- Editing many-to-many relations where seeing the whole matrix helps (items by options, users by roles, products by regions).
- When every cell is a quick on/off decision.

#### When not to use

- Reading or sorting data: use a table (`DataTable`).
- One list of independent switches: use `CheckboxGroup` or `Switch`.
- Very large matrices (hundreds of rows): this component renders every cell.

#### Anatomy

```
div.root
  div[role=region] aria-label="… scrollable" tabindex=0      (horizontal scroll)
    div[role=grid] aria-label aria-describedby=hint
      div[role=row]
        columnheader (corner caption) · columnheader (swatch + label) × N · columnheader (count)
      div[role=row] × rows
        rowheader (label + meta) · gridcell > button "{row} · {column}: linked" × N · gridcell (count)
  p.hint
```

#### Async toggle, sticky headers and focus guides

- **Async toggle.** `onToggle` may return a promise (saving the link on a server). While it is pending the cell is `aria-busy` (on the `gridcell`), shows a small spinner, is named "{row} · {column}: linked, saving" (message `cellPending`) and ignores further toggles; focus stays on it and other cells keep working. The grid never flips a cell by itself: it shows what `isLinked` says. If you update your state optimistically, revert it in `onToggleError`, which runs when the promise rejects (also when `onToggle` throws). Use it for a toast: `onToggleError={() => toast.error('Could not save the link')}`. The grid also announces "Couldn't update {row} · {column}. Try again." in a visually hidden `role="status"` (message `toggleFailed`).
- **Sticky headers.** The column header row and the row header column are `position: sticky`; the corner sits above both. For vertical scrolling give the root a height or `max-block-size` through `className` / `style` (the scroll region fills it). `scroll-padding` keeps a focused cell out from behind the sticky parts (WCAG 2.4.11).
- **Focus guides.** While a cell has focus, its row, its column and the column header get one surface step (`--ds-surface-row-hover`). It is a visual aid only: the focus ring and the cell name carry the meaning, nothing changes in the accessibility tree.

#### Accessibility

- Semantics: `region` (focusable scroll container) > `grid` > `row` > `columnheader` / `rowheader` / `gridcell`. Each cell holds a native button named "{row} · {column}: linked" or "not linked" (messages, `en` and `pt-BR`); the state is in the name, so there is no separate `aria-pressed`.
- Keyboard: the grid is one tab stop (roving tabindex; the scroll region is the stop before it). `←` `→` `↑` `↓` move one cell (horizontal arrows follow the reading direction and stop at the edges); `Home` / `End` go to the first / last cell of the row; `Ctrl+Home` / `Ctrl+End` to the first / last cell of the grid; `Space` and `Enter` toggle.
- Linked state is not color alone: linked cells are solid with a check, unlinked cells are dashed with a plus; the name says it too.
- The check color is chosen with `readableTextOn` (WCAG relative luminance) on the column color, and the choice is tested at 3:1 for a set of colors.
- Targets are 40x40px (the minimum is 24px). Unlinked cell borders use `--ds-line-control` (3:1).
- Motion: the hover scale (1.06) exists only inside `@media (hover: hover) and (prefers-reduced-motion: no-preference)`.
- Forced colors: borders use `ButtonText`, linked cells `Highlight`.

#### Content rules

- Row and column labels are short nouns in sentence case; they are read in every cell name, so keep them unique within their axis.
- `countLabel` names what is counted ("Linked", "Colors").

#### Examples

```tsx
import { MatrixGrid } from 'loui-ds/patterns';

<MatrixGrid
  aria-label="Product colors"
  cornerLabel="Product"
  countLabel="Linked"
  rows={products}
  columns={[{ id: 'navy', label: 'Navy', color: '#1f3a93' }]}
  isLinked={(productId, colorId) => links.has(`${productId}:${colorId}`)}
  onToggle={toggleLink}
  hint="Select a cell to link or unlink a color."
/>;
```

#### Related components

- Instead, see DataTable: Reading or sorting data: use a table (`DataTable`).
- Instead, see CheckboxGroup: One list of independent switches: use `CheckboxGroup` or `Switch`.
- Instead, see Switch: One list of independent switches: use `CheckboxGroup` or `Switch`.
- Renders: Icon, Spinner, Swatch, VisuallyHidden

### Menu

> A menu of commands that opens from a trigger, built on React Aria `MenuTrigger`, `Popover`
and `Menu`.

Keys: the trigger opens it with Enter, Space or Arrow Down (focus goes to the first item;
Arrow Up focuses the last); Arrow Up/Down, Home/End and typeahead move; Enter or Space
activates; Escape closes and focus returns to the trigger. Selection modes
(`selectionMode="single"` or `"multiple"`) turn items into radio or checkbox items.

A menu of commands that opens from a trigger. Built on React Aria `MenuTrigger`, `Popover` and `Menu`. Exports `Menu`, `MenuItem`, `MenuSection`, `MenuSeparator`, `SubMenu` and `MoreActionsMenu`.

- Handoff source: `components/navigation/Menu` (CMP-NAV-02).

- Import: `import { Menu } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Menu/Menu.tsx`
- Stories (Storybook title `Components/Menu`): Default, EscapeRestoresFocus, TypeaheadAndHomeEnd, Open, CheckboxItems, RadioItems, WithSections, WithSubmenu, LongLabels, MoreActions

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes |  | The element that opens the menu: a `Button` or `IconButton`. It receives `aria-haspopup`, `aria-expanded` and names the menu (`aria-labelledby`), so give it a clear name. |
| `children` | `ReactNode` | yes |  | `MenuItem`, `MenuSection`, `MenuSeparator` and `SubMenu` elements. |
| `placement` | `'bottom' \| 'bottom left' \| 'bottom right' \| 'bottom start' \| 'bottom end' \| 'top' \| 'top left' \| 'top right' \| 'top start' \| 'top end' \| 'left' \| 'left top' \| 'left bottom' \| 'start' \| 'start top' \| 'start bottom' \| 'right' \| 'right top' \| 'right bottom' \| 'end' \| 'end top' \| 'end bottom'` |  | `'bottom start'` | Side and alignment relative to the trigger. Default `bottom start`. Flips on collision. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  |  | Initial open state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the menu opens or closes. |
| `className` | `string` |  |  | Class name for the menu list. |
| `popoverClassName` | `string` |  |  | Class name for the popover that holds the menu. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the menu list element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `AriaMenuProps` (react-aria): `escapeKeyBehavior`
- From `CollectionBase` (@react-types/shared): `disabledKeys`, `items`
- From `CollectionProps` (react-aria-components): `dependencies`
- From `DOMProps` (@react-types/shared): `id`
- From `MenuProps` (react-aria): `autoFocus`, `onAction`, `onClose`, `shouldFocusWrap`
- From `MenuProps` (react-aria-components): `renderEmptyState`, `shouldCloseOnSelect`
- From `MultipleSelection` (@react-types/shared): `defaultSelectedKeys`, `disallowEmptySelection`, `onSelectionChange`, `selectedKeys`, `selectionMode`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Menu: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `moreActions` | `More actions` | Name of the overflow button of `MoreActionsMenu`. |

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-danger-soft-hover`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-menu-indicator-size`, `--ds-menu-max-width`, `--ds-menu-min-width`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-select-popover-max-height`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-4`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-tracking-caption`

#### When to use

- Row, card or toolbar actions that do not deserve their own button.
- View options with check or radio items (columns shown, sort order, density).

#### When not to use

- Choosing a value for a field: use `Select` or `Combobox`.
- Content the user types into or operates (filters, forms): use `Popover`.
- Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- The only way to reach an important action: keep primary actions visible.

#### Anatomy

```
MenuTrigger
  trigger            Button | IconButton    aria-haspopup=true, aria-expanded
  Popover            raised surface, radius lg, overlay shadow, z popover
    Menu             role=menu, named by the trigger (aria-labelledby)
      MenuItem       role=menuitem | menuitemcheckbox | menuitemradio, height --ds-item-h
        indicator    check / dot (selectable menus)
        label
        shortcut     mono hint, optional
        chevron      when it opens a SubMenu
      MenuSection    role=group, caption optional (mono uppercase)
      MenuSeparator  1px line
```

#### Accessibility

Keyboard contract (AGENTS.md section 8):

| Key                                     | Behavior                                                        |
| --------------------------------------- | --------------------------------------------------------------- |
| `Enter`, `Space`, `ArrowDown` (trigger) | Opens the menu and focuses the first item                       |
| `ArrowUp` (trigger)                     | Opens the menu and focuses the last item                        |
| `ArrowUp` / `ArrowDown`                 | Move between items; disabled items are skipped                  |
| `Home` / `End`                          | First / last item                                               |
| Typing                                  | Typeahead: focus moves to the item whose label starts with it   |
| `Enter` / `Space`                       | Activates the item (checkbox and radio items toggle) and closes |
| `ArrowRight` / `ArrowLeft`              | Open / close a submenu (mirrored in right-to-left)              |
| `Escape`                                | Closes one level; focus returns to the trigger                  |

- Items are real `menuitem`, `menuitemcheckbox` or `menuitemradio` elements with `aria-checked`; the handoff used `tabIndex=0` divs with no keyboard activation.
- Danger is red text plus the item's own label ("Delete order"); the colour is never the only signal. `tone="danger"` does not confirm: open a `ConfirmDialog` from `onAction`.
- The shortcut hint is visual; bind the key yourself. It uses `--ds-text-2` so the hint stays legible next to the label.
- Focus is shown with the accent ring; forced colors use a `Highlight` outline.
- Layer: `--ds-z-popover` (see Dialog doc, "Layers", for menus opened inside a Dialog or Sheet).
- The `MoreActionsMenu` trigger has a tooltip that repeats its name.

#### Content rules

- Items are a verb plus object in sentence case ("Duplicate order"). End with an ellipsis only when the item opens something that needs more input ("Move to…").
- Order: most common first, destructive last, separated by a `MenuSeparator`.

#### Examples

```tsx
<MoreActionsMenu onAction={(key) => run(String(key))}>
  <MenuItem id="edit" shortcut="Ctrl+E">Edit order</MenuItem>
  <MenuItem id="duplicate">Duplicate order</MenuItem>
  <MenuSeparator />
  <MenuItem id="delete" tone="danger">Delete order</MenuItem>
</MoreActionsMenu>

<Menu trigger={<Button>View</Button>} selectionMode="multiple" defaultSelectedKeys={['id']}>
  <MenuItem id="id">Show ID</MenuItem>
  <MenuItem id="status">Show status</MenuItem>
</Menu>
```

#### Related components

- Instead, see Select: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Combobox: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Popover: Content the user types into or operates (filters, forms): use `Popover`.
- Instead, see Tabs: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Sidebar: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Breadcrumb: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Renders: Icon, IconButton

### MenuItem

> One command. Inside a menu with `selectionMode` it becomes a checkbox or radio item and shows
its selected state with a check or a dot. Disabled items are dimmed and skipped by keyboard
navigation.

A menu of commands that opens from a trigger. Built on React Aria `MenuTrigger`, `Popover` and `Menu`. Exports `Menu`, `MenuItem`, `MenuSection`, `MenuSeparator`, `SubMenu` and `MoreActionsMenu`.

- Handoff source: `components/navigation/Menu` (CMP-NAV-02).

- Import: `import { MenuItem } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Menu/Menu.tsx`
- Stories (Storybook title `Components/Menu`): Default, EscapeRestoresFocus, TypeaheadAndHomeEnd, Open, CheckboxItems, RadioItems, WithSections, WithSubmenu, LongLabels, MoreActions

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | The label: a verb plus object in sentence case ("Duplicate order"). |
| `tone` | `'neutral' \| 'danger'` |  | `'neutral'` | `danger` marks a destructive command (red text and tint). It does not confirm anything: open a `ConfirmDialog` from `onAction`. |
| `shortcut` | `string` |  |  | Shortcut hint in mono type ("Ctrl+D"). Visual only; it does not bind the key. |
| `className` | `string` |  |  |  |

##### Inherited props

- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `HoverEvents` (@react-types/shared): `onHoverChange`, `onHoverEnd`, `onHoverStart`
- From `LinkDOMProps` (@react-types/shared): `download`, `href`, `hrefLang`, `ping`, `referrerPolicy`, `rel`, `routerOptions`, `target`
- From `MenuItemProps` (react-aria-components): `aria-label`, `id`, `isDisabled`, `onAction`, `textValue`, `value`
- From `MenuProps` (react-aria-components): `shouldCloseOnSelect`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `tone`: `neutral`, `danger`

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-danger-soft-hover`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-menu-indicator-size`, `--ds-menu-max-width`, `--ds-menu-min-width`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-select-popover-max-height`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-4`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-tracking-caption`

#### When to use

- Row, card or toolbar actions that do not deserve their own button.
- View options with check or radio items (columns shown, sort order, density).

#### When not to use

- Choosing a value for a field: use `Select` or `Combobox`.
- Content the user types into or operates (filters, forms): use `Popover`.
- Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- The only way to reach an important action: keep primary actions visible.

#### Anatomy

```
MenuTrigger
  trigger            Button | IconButton    aria-haspopup=true, aria-expanded
  Popover            raised surface, radius lg, overlay shadow, z popover
    Menu             role=menu, named by the trigger (aria-labelledby)
      MenuItem       role=menuitem | menuitemcheckbox | menuitemradio, height --ds-item-h
        indicator    check / dot (selectable menus)
        label
        shortcut     mono hint, optional
        chevron      when it opens a SubMenu
      MenuSection    role=group, caption optional (mono uppercase)
      MenuSeparator  1px line
```

#### Accessibility

Keyboard contract (AGENTS.md section 8):

| Key                                     | Behavior                                                        |
| --------------------------------------- | --------------------------------------------------------------- |
| `Enter`, `Space`, `ArrowDown` (trigger) | Opens the menu and focuses the first item                       |
| `ArrowUp` (trigger)                     | Opens the menu and focuses the last item                        |
| `ArrowUp` / `ArrowDown`                 | Move between items; disabled items are skipped                  |
| `Home` / `End`                          | First / last item                                               |
| Typing                                  | Typeahead: focus moves to the item whose label starts with it   |
| `Enter` / `Space`                       | Activates the item (checkbox and radio items toggle) and closes |
| `ArrowRight` / `ArrowLeft`              | Open / close a submenu (mirrored in right-to-left)              |
| `Escape`                                | Closes one level; focus returns to the trigger                  |

- Items are real `menuitem`, `menuitemcheckbox` or `menuitemradio` elements with `aria-checked`; the handoff used `tabIndex=0` divs with no keyboard activation.
- Danger is red text plus the item's own label ("Delete order"); the colour is never the only signal. `tone="danger"` does not confirm: open a `ConfirmDialog` from `onAction`.
- The shortcut hint is visual; bind the key yourself. It uses `--ds-text-2` so the hint stays legible next to the label.
- Focus is shown with the accent ring; forced colors use a `Highlight` outline.
- Layer: `--ds-z-popover` (see Dialog doc, "Layers", for menus opened inside a Dialog or Sheet).
- The `MoreActionsMenu` trigger has a tooltip that repeats its name.

#### Content rules

- Items are a verb plus object in sentence case ("Duplicate order"). End with an ellipsis only when the item opens something that needs more input ("Move to…").
- Order: most common first, destructive last, separated by a `MenuSeparator`.

#### Examples

```tsx
<MoreActionsMenu onAction={(key) => run(String(key))}>
  <MenuItem id="edit" shortcut="Ctrl+E">Edit order</MenuItem>
  <MenuItem id="duplicate">Duplicate order</MenuItem>
  <MenuSeparator />
  <MenuItem id="delete" tone="danger">Delete order</MenuItem>
</MoreActionsMenu>

<Menu trigger={<Button>View</Button>} selectionMode="multiple" defaultSelectedKeys={['id']}>
  <MenuItem id="id">Show ID</MenuItem>
  <MenuItem id="status">Show status</MenuItem>
</Menu>
```

#### Related components

- Instead, see Select: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Combobox: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Popover: Content the user types into or operates (filters, forms): use `Popover`.
- Instead, see Tabs: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Sidebar: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Breadcrumb: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Renders: Icon, IconButton

### MenuSection

> A group of items with an optional caption. Give a section its own `selectionMode` to make a
radio group or a set of checkbox items inside a menu that also holds plain commands.

A menu of commands that opens from a trigger. Built on React Aria `MenuTrigger`, `Popover` and `Menu`. Exports `Menu`, `MenuItem`, `MenuSection`, `MenuSeparator`, `SubMenu` and `MoreActionsMenu`.

- Handoff source: `components/navigation/Menu` (CMP-NAV-02).

- Import: `import { MenuSection } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Menu/Menu.tsx`
- Stories (Storybook title `Components/Menu`): Default, EscapeRestoresFocus, TypeaheadAndHomeEnd, Open, CheckboxItems, RadioItems, WithSections, WithSubmenu, LongLabels, MoreActions

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | `MenuItem` elements. |
| `title` | `string` |  |  | Caption of the group, announced as its name. Mono uppercase by CSS. Omit it for an unnamed group. |
| `className` | `string` |  |  |  |

##### Inherited props

- From `CollectionBase` (@react-types/shared): `items`
- From `CollectionProps` (react-aria-components): `dependencies`
- From `MenuProps` (react-aria-components): `shouldCloseOnSelect`
- From `MultipleSelection` (@react-types/shared): `defaultSelectedKeys`, `disallowEmptySelection`, `onSelectionChange`, `selectedKeys`, `selectionMode`
- From `SectionProps` (react-aria-components): `id`, `value`
- From `SectionProps` (@react-types/shared): `aria-label`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-danger-soft-hover`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-menu-indicator-size`, `--ds-menu-max-width`, `--ds-menu-min-width`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-select-popover-max-height`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-4`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-tracking-caption`

#### When to use

- Row, card or toolbar actions that do not deserve their own button.
- View options with check or radio items (columns shown, sort order, density).

#### When not to use

- Choosing a value for a field: use `Select` or `Combobox`.
- Content the user types into or operates (filters, forms): use `Popover`.
- Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- The only way to reach an important action: keep primary actions visible.

#### Anatomy

```
MenuTrigger
  trigger            Button | IconButton    aria-haspopup=true, aria-expanded
  Popover            raised surface, radius lg, overlay shadow, z popover
    Menu             role=menu, named by the trigger (aria-labelledby)
      MenuItem       role=menuitem | menuitemcheckbox | menuitemradio, height --ds-item-h
        indicator    check / dot (selectable menus)
        label
        shortcut     mono hint, optional
        chevron      when it opens a SubMenu
      MenuSection    role=group, caption optional (mono uppercase)
      MenuSeparator  1px line
```

#### Accessibility

Keyboard contract (AGENTS.md section 8):

| Key                                     | Behavior                                                        |
| --------------------------------------- | --------------------------------------------------------------- |
| `Enter`, `Space`, `ArrowDown` (trigger) | Opens the menu and focuses the first item                       |
| `ArrowUp` (trigger)                     | Opens the menu and focuses the last item                        |
| `ArrowUp` / `ArrowDown`                 | Move between items; disabled items are skipped                  |
| `Home` / `End`                          | First / last item                                               |
| Typing                                  | Typeahead: focus moves to the item whose label starts with it   |
| `Enter` / `Space`                       | Activates the item (checkbox and radio items toggle) and closes |
| `ArrowRight` / `ArrowLeft`              | Open / close a submenu (mirrored in right-to-left)              |
| `Escape`                                | Closes one level; focus returns to the trigger                  |

- Items are real `menuitem`, `menuitemcheckbox` or `menuitemradio` elements with `aria-checked`; the handoff used `tabIndex=0` divs with no keyboard activation.
- Danger is red text plus the item's own label ("Delete order"); the colour is never the only signal. `tone="danger"` does not confirm: open a `ConfirmDialog` from `onAction`.
- The shortcut hint is visual; bind the key yourself. It uses `--ds-text-2` so the hint stays legible next to the label.
- Focus is shown with the accent ring; forced colors use a `Highlight` outline.
- Layer: `--ds-z-popover` (see Dialog doc, "Layers", for menus opened inside a Dialog or Sheet).
- The `MoreActionsMenu` trigger has a tooltip that repeats its name.

#### Content rules

- Items are a verb plus object in sentence case ("Duplicate order"). End with an ellipsis only when the item opens something that needs more input ("Move to…").
- Order: most common first, destructive last, separated by a `MenuSeparator`.

#### Examples

```tsx
<MoreActionsMenu onAction={(key) => run(String(key))}>
  <MenuItem id="edit" shortcut="Ctrl+E">Edit order</MenuItem>
  <MenuItem id="duplicate">Duplicate order</MenuItem>
  <MenuSeparator />
  <MenuItem id="delete" tone="danger">Delete order</MenuItem>
</MoreActionsMenu>

<Menu trigger={<Button>View</Button>} selectionMode="multiple" defaultSelectedKeys={['id']}>
  <MenuItem id="id">Show ID</MenuItem>
  <MenuItem id="status">Show status</MenuItem>
</Menu>
```

#### Related components

- Instead, see Select: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Combobox: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Popover: Content the user types into or operates (filters, forms): use `Popover`.
- Instead, see Tabs: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Sidebar: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Breadcrumb: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Renders: Icon, IconButton

### MenuSeparator

> A 1px line between groups of items.

A menu of commands that opens from a trigger. Built on React Aria `MenuTrigger`, `Popover` and `Menu`. Exports `Menu`, `MenuItem`, `MenuSection`, `MenuSeparator`, `SubMenu` and `MoreActionsMenu`.

- Handoff source: `components/navigation/Menu` (CMP-NAV-02).

- Import: `import { MenuSeparator } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Menu/Menu.tsx`
- Stories (Storybook title `Components/Menu`): Default, EscapeRestoresFocus, TypeaheadAndHomeEnd, Open, CheckboxItems, RadioItems, WithSections, WithSubmenu, LongLabels, MoreActions

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` |  |  |  |

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-danger-soft-hover`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-menu-indicator-size`, `--ds-menu-max-width`, `--ds-menu-min-width`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-select-popover-max-height`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-4`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-tracking-caption`

#### When to use

- Row, card or toolbar actions that do not deserve their own button.
- View options with check or radio items (columns shown, sort order, density).

#### When not to use

- Choosing a value for a field: use `Select` or `Combobox`.
- Content the user types into or operates (filters, forms): use `Popover`.
- Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- The only way to reach an important action: keep primary actions visible.

#### Anatomy

```
MenuTrigger
  trigger            Button | IconButton    aria-haspopup=true, aria-expanded
  Popover            raised surface, radius lg, overlay shadow, z popover
    Menu             role=menu, named by the trigger (aria-labelledby)
      MenuItem       role=menuitem | menuitemcheckbox | menuitemradio, height --ds-item-h
        indicator    check / dot (selectable menus)
        label
        shortcut     mono hint, optional
        chevron      when it opens a SubMenu
      MenuSection    role=group, caption optional (mono uppercase)
      MenuSeparator  1px line
```

#### Accessibility

Keyboard contract (AGENTS.md section 8):

| Key                                     | Behavior                                                        |
| --------------------------------------- | --------------------------------------------------------------- |
| `Enter`, `Space`, `ArrowDown` (trigger) | Opens the menu and focuses the first item                       |
| `ArrowUp` (trigger)                     | Opens the menu and focuses the last item                        |
| `ArrowUp` / `ArrowDown`                 | Move between items; disabled items are skipped                  |
| `Home` / `End`                          | First / last item                                               |
| Typing                                  | Typeahead: focus moves to the item whose label starts with it   |
| `Enter` / `Space`                       | Activates the item (checkbox and radio items toggle) and closes |
| `ArrowRight` / `ArrowLeft`              | Open / close a submenu (mirrored in right-to-left)              |
| `Escape`                                | Closes one level; focus returns to the trigger                  |

- Items are real `menuitem`, `menuitemcheckbox` or `menuitemradio` elements with `aria-checked`; the handoff used `tabIndex=0` divs with no keyboard activation.
- Danger is red text plus the item's own label ("Delete order"); the colour is never the only signal. `tone="danger"` does not confirm: open a `ConfirmDialog` from `onAction`.
- The shortcut hint is visual; bind the key yourself. It uses `--ds-text-2` so the hint stays legible next to the label.
- Focus is shown with the accent ring; forced colors use a `Highlight` outline.
- Layer: `--ds-z-popover` (see Dialog doc, "Layers", for menus opened inside a Dialog or Sheet).
- The `MoreActionsMenu` trigger has a tooltip that repeats its name.

#### Content rules

- Items are a verb plus object in sentence case ("Duplicate order"). End with an ellipsis only when the item opens something that needs more input ("Move to…").
- Order: most common first, destructive last, separated by a `MenuSeparator`.

#### Examples

```tsx
<MoreActionsMenu onAction={(key) => run(String(key))}>
  <MenuItem id="edit" shortcut="Ctrl+E">Edit order</MenuItem>
  <MenuItem id="duplicate">Duplicate order</MenuItem>
  <MenuSeparator />
  <MenuItem id="delete" tone="danger">Delete order</MenuItem>
</MoreActionsMenu>

<Menu trigger={<Button>View</Button>} selectionMode="multiple" defaultSelectedKeys={['id']}>
  <MenuItem id="id">Show ID</MenuItem>
  <MenuItem id="status">Show status</MenuItem>
</Menu>
```

#### Related components

- Instead, see Select: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Combobox: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Popover: Content the user types into or operates (filters, forms): use `Popover`.
- Instead, see Tabs: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Sidebar: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Breadcrumb: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Renders: Icon, IconButton

### Meter

> A bar that shows a quantity within a known range (disk used, quota, score), as opposed to
progress of a task. Built on React Aria `Meter` (`role="meter"`).

A thin bar (4 px) with a label and a value in mono type. `Progress` shows the progress of a task, determinate or indeterminate (React Aria `ProgressBar`, `role="progressbar"`). `Meter` shows a quantity within a range (React Aria `Meter`, `role="meter"`) and shares the same look.

- Import: `import { Meter } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Progress/Progress.tsx`
- Stories (Storybook title `Components/Progress`): Default, WithoutLabel, ShowValue, Empty, Complete, Warning, Danger, Indeterminate, AllTones, AsMeter, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | `ReactNode` |  |  | Visible label, wired to the bar with `aria-labelledby`. Required unless you set `aria-label` or `aria-labelledby`: a bar without a name is an accessibility bug (React Aria warns in development). |
| `meta` | `ReactNode` |  |  | Text on the right of the label, in mono type: "6.2 / 10 GB". It is visual only. If it says more than the percentage, also pass `valueLabel` so screen readers hear the same thing. |
| `showValue` | `boolean` |  |  | Shows the formatted percentage (`62%`, from `Intl` with the active locale) as `meta` when `meta` is not given. |
| `tone` | `'accent' \| 'success' \| 'warning' \| 'danger'` |  | `'accent'` | Color of the fill. Color is never the only signal: pair it with a label or `meta`. Default `accent`. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLDivElement>` |  |  |  |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `DOMProps` (@react-types/shared): `id`
- From `ProgressBarBaseProps` (react-aria): `formatOptions`, `maxValue`, `minValue`, `value`, `valueLabel`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `tone`: `accent`, `success`, `warning`, `danger`

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-duration-progress`, `--ds-ease`, `--ds-font-mono`, `--ds-fs-label`, `--ds-lh-label`, `--ds-progress-height`, `--ds-progress-indeterminate-duration`, `--ds-progress-indeterminate-width`, `--ds-radius-pill`, `--ds-space-2`, `--ds-space-3`, `--ds-success`, `--ds-surface-hover`, `--ds-text-2`, `--ds-warning`

#### When to use

- `Progress`: an upload, an import, a multi-step job. Use indeterminate when the amount is unknown.
- `Meter`: disk used, quota consumed, a score. The value is a measurement, not a task that will finish.

#### When not to use

- Waiting with no known structure and no label: use `Spinner`.
- Content that is loading: use `Skeleton`.

#### Anatomy

```
div[role=progressbar|meter]
  div.header      Label (left) · meta (right, mono)
  div.track       4px, pill
    div.fill      width = percentage (or a sweeping segment when indeterminate)
```

#### Accessibility

- The bar is named by the visible label (`aria-labelledby`) or `aria-label`; React Aria warns in development when a bar has neither.
- `aria-valuenow`, `aria-valuemin` and `aria-valuemax` are set, and `aria-valuetext` is the percentage formatted with `Intl` for the active locale ("62%", "62,5%" in pt-BR). If you show "6.2 / 10 GB", set `valueLabel="6.2 of 10 GB"` so screen readers hear the same thing.
- An indeterminate bar has no `aria-valuenow`, so assistive technology reports it as busy without a number.
- Progress does not announce changes by itself. For long tasks, announce milestones and completion in a live region (for example with a `Toast`).
- Color is not the only signal: the label and the value text carry the meaning. The fill is 4 px high but the track and fill are a graphic that keeps at least 3:1 against the surface; the track is a neutral surface step.
- **Reduced motion:** the width change has no transition and the indeterminate sweep becomes a static segment centered in the track. **Forced colors:** the track gets a border and the fill uses the text color.

#### Content rules

- Labels are nouns or short phrases in sentence case ("Storage", "Importing orders").
- Put units and ratios in `meta`, in the formatted form of the active locale.

#### Examples

```tsx
<Progress value={62} label="Storage" meta="6.2 / 10 GB" valueLabel="6.2 of 10 GB" />
<Progress isIndeterminate label="Importing orders" />
<Meter value={82} tone="warning" label="Quota" showValue />
```

#### Related components

- Instead, see Spinner: Waiting with no known structure and no label: use `Spinner`.
- Instead, see Skeleton: Content that is loading: use `Skeleton`.

### MoreActionsMenu

> The common "more actions" menu: an icon button with three dots whose name comes from the
message catalog ("More actions"), opening a `Menu`. Use it for the row or card actions that
do not deserve their own button.

A menu of commands that opens from a trigger. Built on React Aria `MenuTrigger`, `Popover` and `Menu`. Exports `Menu`, `MenuItem`, `MenuSection`, `MenuSeparator`, `SubMenu` and `MoreActionsMenu`.

- Handoff source: `components/navigation/Menu` (CMP-NAV-02).

- Import: `import { MoreActionsMenu } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Menu/Menu.tsx`
- Stories (Storybook title `Components/Menu`): Default, EscapeRestoresFocus, TypeaheadAndHomeEnd, Open, CheckboxItems, RadioItems, WithSections, WithSubmenu, LongLabels, MoreActions

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | `MenuItem`, `MenuSection`, `MenuSeparator` and `SubMenu` elements. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Size of the trigger button. Default `md`. |
| `messages` | `Partial<{ moreActions: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `className` | `string` |  |  | Class name for the menu list. |
| `placement` | `'bottom' \| 'bottom left' \| 'bottom right' \| 'bottom start' \| 'bottom end' \| 'top' \| 'top left' \| 'top right' \| 'top start' \| 'top end' \| 'left' \| 'left top' \| 'left bottom' \| 'start' \| 'start top' \| 'start bottom' \| 'right' \| 'right top' \| 'right bottom' \| 'end' \| 'end top' \| 'end bottom'` |  | `'bottom end'` | Side and alignment relative to the trigger. Default `bottom start`. Flips on collision. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  |  | Initial open state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the menu opens or closes. |
| `popoverClassName` | `string` |  |  | Class name for the popover that holds the menu. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the menu list element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `AriaMenuProps` (react-aria): `escapeKeyBehavior`
- From `CollectionBase` (@react-types/shared): `disabledKeys`, `items`
- From `CollectionProps` (react-aria-components): `dependencies`
- From `DOMProps` (@react-types/shared): `id`
- From `MenuProps` (react-aria): `autoFocus`, `onAction`, `onClose`, `shouldFocusWrap`
- From `MenuProps` (react-aria-components): `renderEmptyState`, `shouldCloseOnSelect`
- From `MultipleSelection` (@react-types/shared): `defaultSelectedKeys`, `disallowEmptySelection`, `onSelectionChange`, `selectedKeys`, `selectionMode`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Menu: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `moreActions` | `More actions` | Name of the overflow button of `MoreActionsMenu`. |

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-danger-soft-hover`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-menu-indicator-size`, `--ds-menu-max-width`, `--ds-menu-min-width`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-select-popover-max-height`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-4`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-tracking-caption`

#### When to use

- Row, card or toolbar actions that do not deserve their own button.
- View options with check or radio items (columns shown, sort order, density).

#### When not to use

- Choosing a value for a field: use `Select` or `Combobox`.
- Content the user types into or operates (filters, forms): use `Popover`.
- Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- The only way to reach an important action: keep primary actions visible.

#### Anatomy

```
MenuTrigger
  trigger            Button | IconButton    aria-haspopup=true, aria-expanded
  Popover            raised surface, radius lg, overlay shadow, z popover
    Menu             role=menu, named by the trigger (aria-labelledby)
      MenuItem       role=menuitem | menuitemcheckbox | menuitemradio, height --ds-item-h
        indicator    check / dot (selectable menus)
        label
        shortcut     mono hint, optional
        chevron      when it opens a SubMenu
      MenuSection    role=group, caption optional (mono uppercase)
      MenuSeparator  1px line
```

#### Accessibility

Keyboard contract (AGENTS.md section 8):

| Key                                     | Behavior                                                        |
| --------------------------------------- | --------------------------------------------------------------- |
| `Enter`, `Space`, `ArrowDown` (trigger) | Opens the menu and focuses the first item                       |
| `ArrowUp` (trigger)                     | Opens the menu and focuses the last item                        |
| `ArrowUp` / `ArrowDown`                 | Move between items; disabled items are skipped                  |
| `Home` / `End`                          | First / last item                                               |
| Typing                                  | Typeahead: focus moves to the item whose label starts with it   |
| `Enter` / `Space`                       | Activates the item (checkbox and radio items toggle) and closes |
| `ArrowRight` / `ArrowLeft`              | Open / close a submenu (mirrored in right-to-left)              |
| `Escape`                                | Closes one level; focus returns to the trigger                  |

- Items are real `menuitem`, `menuitemcheckbox` or `menuitemradio` elements with `aria-checked`; the handoff used `tabIndex=0` divs with no keyboard activation.
- Danger is red text plus the item's own label ("Delete order"); the colour is never the only signal. `tone="danger"` does not confirm: open a `ConfirmDialog` from `onAction`.
- The shortcut hint is visual; bind the key yourself. It uses `--ds-text-2` so the hint stays legible next to the label.
- Focus is shown with the accent ring; forced colors use a `Highlight` outline.
- Layer: `--ds-z-popover` (see Dialog doc, "Layers", for menus opened inside a Dialog or Sheet).
- The `MoreActionsMenu` trigger has a tooltip that repeats its name.

#### Content rules

- Items are a verb plus object in sentence case ("Duplicate order"). End with an ellipsis only when the item opens something that needs more input ("Move to…").
- Order: most common first, destructive last, separated by a `MenuSeparator`.

#### Examples

```tsx
<MoreActionsMenu onAction={(key) => run(String(key))}>
  <MenuItem id="edit" shortcut="Ctrl+E">Edit order</MenuItem>
  <MenuItem id="duplicate">Duplicate order</MenuItem>
  <MenuSeparator />
  <MenuItem id="delete" tone="danger">Delete order</MenuItem>
</MoreActionsMenu>

<Menu trigger={<Button>View</Button>} selectionMode="multiple" defaultSelectedKeys={['id']}>
  <MenuItem id="id">Show ID</MenuItem>
  <MenuItem id="status">Show status</MenuItem>
</Menu>
```

#### Related components

- Instead, see Select: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Combobox: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Popover: Content the user types into or operates (filters, forms): use `Popover`.
- Instead, see Tabs: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Sidebar: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Breadcrumb: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Renders: Icon, IconButton
- Used by: ActionList

### NavItem

> One entry of a navigation list. A real link when it has an `href`, a button when it only has
`onPress`. The active item is marked with `aria-current="page"`, a raised background and a
2px ink bar at the start edge.

One entry of a navigation list: a real link (or a button) with an optional icon and count. Built on React Aria `Link` and `Button`.

- Handoff source: `components/navigation/NavItem.jsx` (TODO `CMP-NAV-03`).

- Import: `import { NavItem } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/NavItem/NavItem.tsx`
- Stories (Storybook title `Components/NavItem`): Default, Active, AsButton, WithoutIcon, WithCount, CountTones, ZeroCountHidden, Disabled, LongLabel, RouterNavigation, PortugueseCount, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | Label: a noun in sentence case ("Orders"). Truncated with an ellipsis when it does not fit. |
| `href` | `string` |  |  | Destination. With `href` the item is a real link (`<a>`) and navigates through the router set on `DSProvider`. Without it the item is a `<button>` that runs `onPress`. |
| `icon` | `LucideIcon` |  |  | Icon from the curated set, drawn at 18px before the label. Decorative. |
| `isActive` | `boolean` |  | `false` | Marks the item for the page or view being shown: sets `aria-current="page"`, the raised background and the 2px ink bar. Exactly one item of a navigation should be active. |
| `count` | `string \| number` |  |  | A count shown in a pill at the end of the item. `0` shows no pill. Numbers are formatted for the active locale. |
| `countLabel` | `string` |  |  | The text a screen reader hears instead of the bare number, with what is being counted ("3 pending", "12 unread"). Always set it together with `count`; without it a generic "Count: 3" from the message catalog is used. |
| `countTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  | `'neutral'` | Tone of the count pill. Color never carries the meaning alone: `countLabel` does. Default `neutral`. |
| `messages` | `Partial<{ count: (value: string) => string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLElement>` |  |  | Ref to the underlying `<a>` (with `href`) or `<button>` element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `AriaLinkOptions` (react-aria): `isDisabled`
- From `DOMProps` (@react-types/shared): `id`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `HoverEvents` (@react-types/shared): `onHoverChange`, `onHoverEnd`, `onHoverStart`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `LinkDOMProps` (@react-types/shared): `download`, `hrefLang`, `ping`, `referrerPolicy`, `rel`, `routerOptions`, `target`
- From `PossibleLinkDOMRenderProps` (react-aria-components): `render`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ NavItem: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `count(value: string)` | `Count: {value}` | Spoken text for a count when the consumer gives no `countLabel`. |

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-danger`, `--ds-danger-soft`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-small`, `--ds-nav-item-count-padding-inline`, `--ds-nav-item-count-size`, `--ds-nav-item-icon-opacity`, `--ds-nav-item-indicator-width`, `--ds-nav-item-padding-inline`, `--ds-opacity-disabled`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-space-3`, `--ds-success`, `--ds-success-soft`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-warning`, `--ds-warning-soft`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- Inside the `Sidebar`, or any vertical navigation list.
- To go to a page or view (with `href`), or to run a navigation-like command such as "Log out" (with `onPress`).

#### When not to use

- For actions inside a page: use `Button`.
- For switching panels on a page: use `Tabs`.
- For a link inside text: use `Link`.

#### Anatomy

```
a | button .root           (36px high, --ds-item-h)
  Icon                     (18px, optional, 0.7 opacity when inactive)
  label                    (truncates with an ellipsis)
  count                    (optional pill with tone)
    "3"                    (aria-hidden)
    "3 pending"            (visually hidden text alternative)
```

#### States

| State    | Look                                                                          | Semantics             |
| -------- | ----------------------------------------------------------------------------- | --------------------- |
| Rest     | transparent, `--ds-text-2`                                                    | link or button        |
| Hover    | raised background (`--ds-surface-raised`), ink text                           | none                  |
| Active   | raised background, ink text, 2px ink bar at the start edge, full-opacity icon | `aria-current="page"` |
| Focus    | accent ring                                                                   |                       |
| Disabled | `--ds-opacity-disabled`                                                       | `aria-disabled`       |

#### Accessibility

- Real `<a href>` (or `<button>`), so opening in a new tab, copying the URL and screen reader link lists work. The handoff used `div role="link"` with no `href`.
- `aria-current="page"` on the active item, on links and on buttons.
- The count pill is not enough on its own: a screen reader hears the label then the text alternative ("Orders 3 pending"). Color (tone) is only reinforcement.
- Keys: `Tab` to focus; `Enter` follows a link; `Enter` and `Space` press a button.
- Contrast: label `--ds-text-2` on `--ds-bg`, ink on the raised surface. The pill text meets 4.5:1 on its soft background.
- Forced colors: the active bar and the pill border use system colors.

#### Content rules

- Labels are nouns in sentence case: "Orders", "Customers". Long labels are truncated.
- `countLabel` states what is counted and its state: "3 pending", "12 unread".

#### Examples

```tsx
<nav aria-label="Main">
  <NavItem
    href="/orders"
    icon={StarIcon}
    isActive
    count={3}
    countLabel="3 pending"
    countTone="warning"
  >
    Orders
  </NavItem>
  <NavItem href="/customers" icon={SearchIcon}>
    Customers
  </NavItem>
  <NavItem onPress={signOut}>Log out</NavItem>
</nav>
```

#### Related components

- Instead, see Button: For actions inside a page: use `Button`.
- Instead, see Tabs: For switching panels on a page: use `Tabs`.
- Instead, see Link: For a link inside text: use `Link`.
- Renders: Icon, VisuallyHidden
- Used by: Sidebar

### NumberField

> A number field with minus and plus steppers (the handoff `Stepper`), built on React Aria
`NumberField`: a text `<input>` with `aria-roledescription="Number field"` (React Aria
deliberately drops `role="spinbutton"`: VoiceOver cannot focus a spin button with typed
text). You can type a value or step it: `ArrowUp` / `ArrowDown` by `step`,
`PageUp` / `PageDown` like the arrows (React Aria has no larger step), `Home` / `End` to the
limits (when `minValue` / `maxValue` are set), the mouse wheel while focused, and press and hold on a button repeats.
The typed text is parsed with the locale of `DSProvider` (`1.234,5` in pt-BR) and committed on
blur or `Enter`; values are clamped to the limits and snapped to `step`.

`onChange` receives a number, `NaN` while the field is empty. For money use `CurrencyInput`.

A number input with minus and plus steppers; the successor of the handoff `Stepper`. Built on React Aria `NumberField` (`Group`, `Input`, two `Button`s in the `decrement` / `increment` slots), styled like [Input](../Input/Input.md). Task: CMP-PAT-06.

- Import: `import { NumberField } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/NumberField/NumberField.tsx`
- Stories (Storybook title `Components/NumberField`): Default, KeyboardContract, TypingClampsToLimits, WithSuffix, FormattedUnit, WithDescription, Required, Invalid, Disabled, ReadOnly, AtLimit, Sizes, Controlled, FullWidthInRow

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | `ReactNode` |  |  | Helper text under the control, linked with `aria-describedby`. |
| `descriptionTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the description: `success`, `warning`, `danger` or `accent` for a live check such as "Matches" or "Over by $5". The text carries the meaning; colour only reinforces it. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while the field is invalid and the error is displayed. See `Input`. |
| `placeholder` | `string` |  |  | Text shown while the field is empty. Never a substitute for the label. |
| `suffix` | `ReactNode` |  |  | A unit shown after the number inside the box ("m", "kg", "pcs"). Visual only: for a spoken unit use `formatOptions={{ style: 'unit', unit: 'meter' }}`, which also formats the number. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Height of the box and of both stepper buttons: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `fullWidth` | `boolean` |  | `false` | Take the free space of a flex row (an `Inline`): the field grows to fill it and can shrink below its content width. Off by default. In a block context the field already spans the width. |
| `className` | `string` |  |  | Class name for the field root. |
| `inputClassName` | `string` |  |  | Class name for the `<input>` element. |
| `inputRef` | `Ref<HTMLInputElement>` |  |  | Ref to the `<input>` element. The `ref` prop points at the field root. |
| `messages` | `Partial<{ decrease: string; increase: string; } & { requiredMark: string; }>` |  |  | Message overrides for this instance: `decrease`, `increase`, `requiredMark`. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaNumberFieldProps` (react-aria): `decrementAriaLabel`, `incrementAriaLabel`, `isWheelDisabled`
- From `DOMProps` (@react-types/shared): `id`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `NumberFieldProps` (react-stately): `commitBehavior`, `formatOptions`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `RangeInputBase` (@react-types/shared): `maxValue`, `minValue`, `step`
- From `SlotProps` (react-aria-components): `slot`
- From `TextInputDOMEvents` (@react-types/shared): `onBeforeInput`, `onCompositionEnd`, `onCompositionStart`, `onCompositionUpdate`, `onCopy`, `onCut`, `onInput`, `onPaste`, `onSelect`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- From `ValueBase` (@react-types/shared): `defaultValue`, `onChange`, `value`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ NumberField: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `decrease` | `Decrease` | Accessible name of the "minus" stepper button. |
| `increase` | `Increase` | Accessible name of the "plus" stepper button. |

#### Design tokens used

`--ds-field-control-padding-inline`, `--ds-font-mono`, `--ds-fs-label`, `--ds-number-field-value-min-width`, `--ds-space-1`, `--ds-text-3`

#### When to use

- A bounded or unbounded count or measure that users type or nudge: quantity, length, number of copies.

#### When not to use

- Money: `CurrencyInput` (integer minor units, currency formatting).
- An approximate value on a range: `Slider`.
- Digits that are an identifier (postal code, phone): `Input` with `mono`.

#### Anatomy

`[ - ] [ value + suffix ] [ + ]`: three boxes of the same height (`sm` 32 / `md` 40 / `lg` 48). The middle box is the `Input` look (`--ds-line-control` border, focus ring, mono, centered); the steppers are `IconButton`s.

#### Props (key ones)

| Prop                                                          | Notes                                                                                                |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `label` / `aria-label` / `aria-labelledby`                    | One is required.                                                                                     |
| `value` / `defaultValue` / `onChange(value)`                  | RAC naming. `onChange` receives a `number`, `NaN` while the field is empty.                          |
| `minValue`, `maxValue`, `step`                                | Typed and stepped values are clamped and snapped to `step`.                                          |
| `formatOptions`                                               | `Intl.NumberFormat` options (`{ style: 'unit', unit: 'kilogram' }`, `{ maximumFractionDigits: 2 }`). |
| `suffix`                                                      | A visual unit after the number ("m", "pcs"). For a spoken unit use `formatOptions`.                  |
| `size`                                                        | `sm` / `md` (default) / `lg`; the steppers follow.                                                   |
| `fullWidth`                                                   | Take the free space of a flex row such as `Inline` (`flex: 1 1 auto`, can shrink). Off by default.   |
| `description`, `descriptionTone`, `errorMessage`              | As in `Input`.                                                                                       |
| `name`, `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly` | Standard. `name` submits the raw number (`1234.5`), not the formatted text.                          |
| `messages`                                                    | `decrease`, `increase`, `requiredMark`.                                                              |

#### Accessibility and keyboard

| Key                       | Behavior                                                                  |
| ------------------------- | ------------------------------------------------------------------------- |
| `ArrowUp` / `ArrowDown`   | Step up / down                                                            |
| `PageUp` / `PageDown`     | Same as the arrows (React Aria has no larger step)                        |
| `Home` / `End`            | `minValue` / `maxValue` (only when set)                                   |
| Typing                    | Parsed with the locale (`1.234,5` in pt-BR), committed on `Enter` or blur |
| Press and hold a stepper  | Repeats (React Aria)                                                      |
| Mouse wheel while focused | Steps                                                                     |

The input is a text input with `aria-roledescription="Number field"`: React Aria deliberately does not use `role="spinbutton"` because VoiceOver cannot focus a spin button that accepts typed text. The stepper buttons are named "Decrease" / "Increase" from messages and, through `aria-labelledby`, followed by the field label ("Increase Quantity"); they are out of the tab order (the input handles the keys) and disabled at the limits. The value is not a live region (RAC announces changes).

#### Content rules

Label with the noun ("Quantity"). Put the unit in `suffix` or `formatOptions`, not in the label. Error text says how to fix: "Enter a quantity between 0 and 10."

#### Example

```tsx
<NumberField label="Quantity" name="quantity" defaultValue={1} minValue={1} maxValue={99} />
```

#### Related components

- Instead, see CurrencyInput: Money: `CurrencyInput` (integer minor units, currency formatting).
- Instead, see Slider: An approximate value on a range: `Slider`.
- Instead, see Input: Digits that are an identifier (postal code, phone): `Input` with `mono`.
- Renders: FieldMessages, IconButton, Label

### Pagination

> Previous and next buttons, numbered page buttons with ellipses, and a text that says where
you are ("11–20 of 42", or "Page 2 of 5" when only the page count is known).

The text is a polite live region, so a screen reader announces the new range when the page
changes. The current page button has `aria-current="page"`. The buttons that cannot be used
(previous on page 1) are disabled; when pressing a button disables it, focus moves to the
current page button so it is never lost.

Previous and next buttons, numbered page buttons with ellipses and a text that says where you are ("11–20 of 42"). The list logic is a tested pure function, `getPageItems`.

- Handoff source: `components/data/Pagination.jsx` (TODO `CMP-DAT-02`).

- Import: `import { Pagination } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Pagination/Pagination.tsx`
- Stories (Storybook title `Components/Pagination`): Default, WithRange, MiddlePage, LastPage, FewPages, SinglePage, NoResults, KeyboardNavigation, FocusStaysAfterLastPage, Controlled, Portuguese, NarrowContainer, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `page` | `number` |  |  | Current page, 1-based (controlled). |
| `defaultPage` | `number` |  | `1` | Page shown first (uncontrolled). Default `1`. |
| `onChange` | `(page: number) => void` |  |  | Called with the new page when the user picks one. |
| `pageCount` | `number` |  |  | Number of pages. Optional when `total` and `pageSize` are given (then it is derived from them). Default `1`. |
| `total` | `number` |  |  | Total number of items. With `pageSize` it enables the "1–10 of 42" range text. |
| `pageSize` | `number` |  |  | Items per page. |
| `messages` | `Partial<{ navLabel: string; previous: string; next: string; page: (page: string) => string; range: (from: string, to: string, total: string) => string; empty: string; pageOf: (page: string, count: string) => string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Pagination: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `navLabel` | `Pagination` | Accessible name of the pagination navigation landmark. |
| `previous` | `Previous page` |  |
| `next` | `Next page` |  |
| `page(page: string)` | `Page {page}` | Accessible name of a page button; the button shows only the number. |
| `range(from: string, to: string, total: string)` | `{from}–{to} of {total}` | Visible and announced range of items. All arguments are already formatted for the locale. |
| `empty` | `No results` | Visible and announced text when `total` is 0. |
| `pageOf(page: string, count: string)` | `Page {page} of {count}` | Visible and announced text when only the page count is known. |

#### Design tokens used

`--ds-accent`, `--ds-control-h-sm`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-label`, `--ds-lh-label`, `--ds-line-strong`, `--ds-radius-md`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-5`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`

#### When to use

- Below a table or list that is split into pages on the server or the client.

#### When not to use

- For endless feeds: use a "Load more" `Button`.
- For a handful of items that fit on one screen.
- For moving through steps: use a stepper.

#### Anatomy

```
div.root
  span[role=status, aria-live=polite]   "11–20 of 42"  or  "Page 2 of 5"
  nav[aria-label="Pagination"]
    ul
      li  IconButton  Previous page
      li  button      1    (aria-label "Page 1", aria-current="page" on the current one)
      li  …                (aria-hidden)
      li  IconButton  Next page
```

#### Page list algorithm

Up to 7 pages every page is shown. Beyond that: the first page, the last page, the current page and its two neighbours; each gap becomes an ellipsis. A gap that would hide exactly one page shows that page instead (the handoff showed an ellipsis for it, which is wider than the page it hides). The page list never exceeds 7 slots.

#### Accessibility

- `nav` named "Pagination" (from the catalog). Page buttons have `aria-label="Page 3"` and show only the number; the current one has `aria-current="page"`.
- The summary is a polite live region: when the page changes, a screen reader announces the new range ("11–20 of 42"). It is not announced on first render.
- Previous and next are disabled at the ends. When pressing one disables it, focus moves to the current page button, so focus is never lost to the page body.
- Ellipses are `aria-hidden` list items. In right-to-left locales the previous and next chevrons swap direction.
- Targets are 32px; page numbers are mono with tabular figures. Numbers are formatted for the locale ("1.248" in pt-BR).
- Keys: `Tab` to move; `Enter` and `Space` press.

#### Content rules

- Do not repeat the total elsewhere. Keep the labels from the catalog unless your product uses another word for the items ("rows", "orders").

#### Examples

```tsx
<Pagination total={42} pageSize={10} page={page} onChange={setPage} />

<Pagination pageCount={8} defaultPage={3} />
```

#### Related components

- Instead, see Button: For endless feeds: use a "Load more" `Button`.
- Renders: IconButton
- Used by: DataTable

### Popover

> A floating surface for interactive content (filters, a small form, a color picker), built on
React Aria `DialogTrigger`, `Popover` and `Dialog`.

It is not for lists of commands (use `Menu`), for choosing one option (use `Select`) or for
plain hints (use `Tooltip`). `Escape` and an outside press close it and focus returns to the
trigger; when the content has focusable elements, `Tab` stays inside until it is closed.

A floating surface that opens from a trigger and holds interactive content. Built on React Aria `DialogTrigger`, `Popover` and `Dialog`.

- Handoff source: `components/navigation/Popover` (CMP-NAV-04).

- Import: `import { Popover } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Popover/Popover.tsx`
- Stories (Storybook title `Components/Popover`): Default, Open, WithArrow, AboveTrigger, AlignedToEnd, KeyboardOpenAndRestoreFocus, CloseFromInside

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes |  | The element that opens the popover: a `Button`, `IconButton` or any React Aria pressable. It receives `aria-expanded` and `aria-haspopup="dialog"`. |
| `label` | `string` | yes |  | Accessible name of the popover (for example "Filters"). The popover is a `dialog`, so it needs a name; a visible heading inside it can be linked with `aria-labelledby` instead. |
| `children` | `ReactNode \| ((options: { close: () => void; }) => ReactNode)` | yes |  | Interactive content. A function receives `close` to dismiss the popover from inside. |
| `placement` | `'bottom' \| 'bottom left' \| 'bottom right' \| 'bottom start' \| 'bottom end' \| 'top' \| 'top left' \| 'top right' \| 'top start' \| 'top end' \| 'left' \| 'left top' \| 'left bottom' \| 'start' \| 'start top' \| 'start bottom' \| 'right' \| 'right top' \| 'right bottom' \| 'end' \| 'end top' \| 'end bottom'` |  | `'bottom start'` | Side and alignment relative to the trigger. Default `bottom start`. Flips on collision. |
| `showArrow` | `boolean` |  | `false` | Draws an arrow that points at the trigger. |
| `isNonModal` | `boolean` |  | `false` | Keeps the page outside the popover available to assistive technology and does not hide it. Leave it off unless the popover is a long-lived tool the user returns to; React Aria's guidance is that most popovers should stay modal for screen readers. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  |  | Initial open state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the popover opens or closes. |
| `className` | `string` |  |  | Class name for the popover surface. |
| `ref` | `Ref<HTMLElement>` |  |  | Ref to the popover surface. |

#### Design tokens used

`--ds-duration`, `--ds-ease`, `--ds-font-sans`, `--ds-fs-small`, `--ds-lh-small`, `--ds-line-strong`, `--ds-popover-arrow-size`, `--ds-popover-min-width`, `--ds-popover-padding`, `--ds-radius-lg`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-surface-raised`, `--ds-text`

#### When to use

- Filters, a small form, a date range, a color picker: content the user operates and then dismisses.

#### When not to use

- A list of commands: use `Menu`.
- Choosing one option from a list: use `Select` or `Combobox`.
- A hint on hover or focus: use `Tooltip`.
- A decision that blocks the task: use `Dialog`.

#### Anatomy

```
DialogTrigger
  trigger            Button | IconButton            aria-haspopup=dialog, aria-expanded, aria-controls
  Popover            raised surface, strong line, radius lg, overlay shadow, z popover
    OverlayArrow     optional
    Dialog           role=dialog, aria-label = label
      children
```

#### Accessibility

- The trigger gets `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`. The handoff used a `span` with a click handler and no ARIA.
- The surface is a `dialog` named by `label`. A menu is **not** a dialog: use `Menu` for commands.
- Keys: `Enter`/`Space` on the trigger opens it and moves focus inside; `Tab` moves through the content; `Esc` closes it and focus returns to the trigger.
- Outside press closes it. React Aria hides the rest of the page from assistive technology while it is open (`isNonModal` turns that off; React Aria recommends it only for long-lived tool popovers).
- Focus is restored to the trigger on close.
- Placement is collision-aware. Forced colors: the arrow uses `CanvasText`/`Canvas`.
- Layer: `--ds-z-popover`. A popover opened from inside a `Dialog` or `Sheet` sits **below** them in the current z-index scale (see the Dialog doc, "Layers").

#### Content rules

- `label` is a noun phrase: "Filters", "Date range".
- Put the confirming action inside the content ("Apply filters"); verb plus object.

#### Examples

```tsx
<Popover trigger={<Button>Filters</Button>} label="Filters" placement="bottom end">
  {({ close }) => (
    <>
      <Input label="Customer" />
      <Button variant="primary" onPress={close}>
        Apply filters
      </Button>
    </>
  )}
</Popover>
```

#### Related components

- Instead, see Menu: A list of commands: use `Menu`.
- Instead, see Select: Choosing one option from a list: use `Select` or `Combobox`.
- Instead, see Combobox: Choosing one option from a list: use `Select` or `Combobox`.
- Instead, see Tooltip: A hint on hover or focus: use `Tooltip`.
- Instead, see Dialog: A decision that blocks the task: use `Dialog`.

### Progress

> A thin bar for a task that makes progress: determinate with a `value`, or indeterminate
when the amount is unknown. Built on React Aria `ProgressBar` (`role="progressbar"`).
For a measured quantity that is not a task (disk used, quota) use `Meter`.

A thin bar (4 px) with a label and a value in mono type. `Progress` shows the progress of a task, determinate or indeterminate (React Aria `ProgressBar`, `role="progressbar"`). `Meter` shows a quantity within a range (React Aria `Meter`, `role="meter"`) and shares the same look.

- Import: `import { Progress } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Progress/Progress.tsx`
- Stories (Storybook title `Components/Progress`): Default, WithoutLabel, ShowValue, Empty, Complete, Warning, Danger, Indeterminate, AllTones, AsMeter, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | `ReactNode` |  |  | Visible label, wired to the bar with `aria-labelledby`. Required unless you set `aria-label` or `aria-labelledby`: a bar without a name is an accessibility bug (React Aria warns in development). |
| `meta` | `ReactNode` |  |  | Text on the right of the label, in mono type: "6.2 / 10 GB". It is visual only. If it says more than the percentage, also pass `valueLabel` so screen readers hear the same thing. |
| `showValue` | `boolean` |  |  | Shows the formatted percentage (`62%`, from `Intl` with the active locale) as `meta` when `meta` is not given. |
| `tone` | `'accent' \| 'success' \| 'warning' \| 'danger'` |  | `'accent'` | Color of the fill. Color is never the only signal: pair it with a label or `meta`. Default `accent`. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLDivElement>` |  |  |  |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `DOMProps` (@react-types/shared): `id`
- From `ProgressBarBaseProps` (react-aria): `formatOptions`, `maxValue`, `minValue`, `value`, `valueLabel`
- From `ProgressBarProps` (react-aria): `isIndeterminate`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `tone`: `accent`, `success`, `warning`, `danger`

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-duration-progress`, `--ds-ease`, `--ds-font-mono`, `--ds-fs-label`, `--ds-lh-label`, `--ds-progress-height`, `--ds-progress-indeterminate-duration`, `--ds-progress-indeterminate-width`, `--ds-radius-pill`, `--ds-space-2`, `--ds-space-3`, `--ds-success`, `--ds-surface-hover`, `--ds-text-2`, `--ds-warning`

#### When to use

- `Progress`: an upload, an import, a multi-step job. Use indeterminate when the amount is unknown.
- `Meter`: disk used, quota consumed, a score. The value is a measurement, not a task that will finish.

#### When not to use

- Waiting with no known structure and no label: use `Spinner`.
- Content that is loading: use `Skeleton`.

#### Anatomy

```
div[role=progressbar|meter]
  div.header      Label (left) · meta (right, mono)
  div.track       4px, pill
    div.fill      width = percentage (or a sweeping segment when indeterminate)
```

#### Accessibility

- The bar is named by the visible label (`aria-labelledby`) or `aria-label`; React Aria warns in development when a bar has neither.
- `aria-valuenow`, `aria-valuemin` and `aria-valuemax` are set, and `aria-valuetext` is the percentage formatted with `Intl` for the active locale ("62%", "62,5%" in pt-BR). If you show "6.2 / 10 GB", set `valueLabel="6.2 of 10 GB"` so screen readers hear the same thing.
- An indeterminate bar has no `aria-valuenow`, so assistive technology reports it as busy without a number.
- Progress does not announce changes by itself. For long tasks, announce milestones and completion in a live region (for example with a `Toast`).
- Color is not the only signal: the label and the value text carry the meaning. The fill is 4 px high but the track and fill are a graphic that keeps at least 3:1 against the surface; the track is a neutral surface step.
- **Reduced motion:** the width change has no transition and the indeterminate sweep becomes a static segment centered in the track. **Forced colors:** the track gets a border and the fill uses the text color.

#### Content rules

- Labels are nouns or short phrases in sentence case ("Storage", "Importing orders").
- Put units and ratios in `meta`, in the formatted form of the active locale.

#### Examples

```tsx
<Progress value={62} label="Storage" meta="6.2 / 10 GB" valueLabel="6.2 of 10 GB" />
<Progress isIndeterminate label="Importing orders" />
<Meter value={82} tone="warning" label="Quota" showValue />
```

#### Related components

- Instead, see Spinner: Waiting with no known structure and no label: use `Spinner`.
- Instead, see Skeleton: Content that is loading: use `Skeleton`.
- Used by: FileUpload

### ProportionBar

> A single bar split into the parts of a whole (payment methods, composition). It is an image
with a text summary ("Payment methods: Pix 47%, Cash 16%…"), and an optional legend with the
percentage and the value of each part.

Neutral by default: signal colors are not used for categories. Parts are separated by a
gap, and beyond four parts the ramp repeats with a hatch so they never look alike.

One bar split into the parts of a whole (payment methods, composition), with a text summary for assistive technology and an optional legend with the percentage and value of each part.

- Import: `import { ProportionBar } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/ProportionBar/ProportionBar.tsx`
- Stories (Storybook title `Components/ProportionBar`): Default, WithLegend, EightParts, ExplicitColors, ZeroPart, AllZero, OneDecimalPercent, LongLabels, PortugueseBrazil, LegendColumns, PartOfWhole

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `segments` | `readonly ProportionSegment[]` | yes |  | The parts of the whole, in display order. Without `color` they use a neutral ramp of four steps (`text`, `text-2`, `text-3`, `line-control`); from the fifth part on, the ramp repeats with a hatch pattern so no two parts look the same (up to eight; group the tail into "Other" or give explicit colors beyond that). The bar never sorts. |
| `label` | `string` |  |  | Name of the whole ("Payment methods"). It starts the summary read for the bar. |
| `legend` | `boolean` |  | `false` | Shows a list under the bar with swatch, label, percentage and formatted value for each part. |
| `total` | `number` |  |  | The size of the whole, in the unit of the segment values. When it is larger than the sum of the segments, the difference is the remaining part: an unlabelled track after the segments, named "Remaining" in the summary and in the legend. This is how a single segment becomes a "part of the whole" indicator ("Paid 1,240 of 2,000"). When smaller than the sum it is ignored. |
| `legendColumns` | `readonly ProportionLegendColumn[]` |  | `['share', 'value']` | Columns of the legend, in order: `share` (percentage), `value` (formatted with `format`) and `count` (the segment `count`). Default `['share', 'value']`. Percentages are rounded one by one and may not add up to exactly 100%. |
| `format` | `(value: number) => ReactNode` |  |  | Formats each value in the legend. Default: `formatNumber` with the active locale. Use `formatCurrency` for money. |
| `percentDigits` | `number` |  | `0` | Decimals of the percentages in the summary and the legend. Default `0`. |
| `messages` | `Partial<{ segment: (label: string, percent: string) => string; summary: (items: string, label?: string) => string; remaining: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ ProportionBar: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `segment(label: string, percent: string)` | `{label} {percent}` | One segment in the summary read for the bar: "Cash 16%". Both arguments are already formatted. |
| `summary(items: string, label?: string)` | `{label?}: {items}` | The whole summary. `items` is the list of segments joined for the locale ("Cash 16%, Card 11% and Pix 73%"); `label` names the bar, if given. |
| `remaining` | `Remaining` | Name of the unfilled part when `total` is larger than the sum of the segments: read in the summary and printed in the legend. |

#### Design tokens used

`--ds-bg`, `--ds-font-mono`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-small`, `--ds-line`, `--ds-line-control`, `--ds-line-subtle`, `--ds-proportion-bar-color`, `--ds-proportion-bar-columns`, `--ds-proportion-bar-hatch-size`, `--ds-proportion-bar-height`, `--ds-proportion-bar-percent-col-w`, `--ds-proportion-bar-segment-gap`, `--ds-proportion-bar-share`, `--ds-proportion-bar-swatch-size`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-space-3`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`

#### When to use

- Showing how a total divides into a few parts (2 to 8) at a glance.
- Next to or inside a `StatCard`.

#### When not to use

- Progress of a task: use `Progress`. A quantity within a range: use `Meter`.
- Comparing separate values or many categories: use `Chart` or `RankList`.
- Exact figures the user must read: show the legend (or a table).

#### Anatomy

```
div.root
  div[role=img][aria-label="Payment methods: Pix 53%, Cash 18%…"]   the track, 10px, pill radius
    div  one segment per non-zero part (flex share = its share of the whole, 2px gap)
  ul (legend, optional)
    li  swatch (aria-hidden) · label · percentage · value
```

#### Props (key ones)

| Prop            | Type                                      | Default | Notes                                                                                                                                               |
| --------------- | ----------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `segments`      | `{ id?, label, value, count?, color? }[]` | -       | Display order; never sorted. Negative and non-finite values count as 0. `id` links the segment to its legend item, `count` feeds the `count` column |
| `total`         | `number`                                  |         | Size of the whole. When larger than the sum, the rest is an unlabelled track named "Remaining"                                                      |
| `legendColumns` | `('share'                                 | 'value' | 'count')[]`                                                                                                                                         | `['share', 'value']` | Columns of the legend, in order |
| `label`         | `string`                                  |         | Name of the whole; starts the summary                                                                                                               |
| `legend`        | `boolean`                                 | `false` | List with swatch, label, percentage and formatted value                                                                                             |
| `format`        | `(value) => ReactNode`                    | `Intl`  | Formats legend values. Use `formatCurrency` for money                                                                                               |
| `percentDigits` | `number`                                  | `0`     | Decimals of the percentages                                                                                                                         |
| `messages`      | `Partial<messages>`                       |         | `segment(label, percent)`, `summary(items, label?)`, `remaining`                                                                                    |

#### Part of the whole

A single segment plus `total` is the "Paid 1,240 of 2,000" indicator; there is no separate component:

```tsx
<ProportionBar
  label="Invoice"
  total={2000}
  legend
  format={(value) => formatCurrency(value * 100, 'USD', locale)}
  segments={[{ id: 'paid', label: 'Paid', value: 1240 }]}
/>
```

The summary reads "Invoice: Paid 62% and Remaining 38%" (the word comes from the `remaining` message, `Restante` in pt-BR). The remaining part is drawn as the empty track, so it carries no color; in the legend it has a hollow, dashed swatch. A `total` smaller than the sum of the segments is ignored. Use `DonutMeter` instead when the share is the only message and a ring fits better.

#### Linking segments and legend items

Each segment can carry a stable `id`. The bar segment gets `data-segment="<id>"` and its legend item gets the same attribute and the DOM id `<bar id>-<id>`, so tests and consumer code can find the pair. For people the link is the order, the label and the matching swatch (color is never the only link). The bar itself is one `role="img"` whose children are presentational, so the accessible link is the summary: it names every part in the same order as the legend, and the legend repeats the same labels.

#### Legend columns

`legendColumns` picks and orders the columns after the label: `share` (percentage), `value` (formatted with `format`) and `count` (the segment `count`, formatted with `Intl`). All rows share one grid, so the columns line up (tabular mono figures). Shares are rounded one by one and may not add up to 100%.

#### Distinguishing the parts

Neutral by default: signal colors are not used for categories.

- The ramp has four solid steps: `text`, `text-2`, `text-3`, `line-control`. All reach 3:1 against the track background.
- Neighbours are always separated by a 2px gap.
- From the fifth part on, the ramp **repeats with a diagonal hatch**, so up to eight parts look different. This is the only place a gradient is used, as a pattern, not as decoration.
- Beyond eight parts, group the smallest into "Other" or pass explicit `color`s. In development a warning appears when more than eight parts have no color.
- Even so, the legend and the summary carry the identity of every part; the fill only helps sighted users.

#### Accessibility

- The bar is `role="img"` with an `aria-label` that lists every part with its percentage: "Payment methods: Pix 53%, Cash 18%, Debit 17%, and Credit 11%". The list is joined with `Intl.ListFormat` for the locale; the per-part text comes from messages.
- The legend is a real list. It repeats the summary on purpose: it is the content sighted users read, and it stays available when you need more than the bar.
- Zero parts are listed in the legend (with 0%) but not drawn.
- Forced colors: segments use system colors (`CanvasText`, `GrayText`, `LinkText`, `Highlight`) and the track gets a border.

#### Content rules

- Part labels are short nouns ("Cash", "Pix"); the whole gets a label when the bar is not obvious from context.
- Percentages are rounded; they may not add up to exactly 100%. Use `percentDigits` if that matters.

#### Example

```tsx
<ProportionBar
  label="Payment methods"
  legend
  format={(value) => formatCurrency(value, 'USD', locale)}
  segments={[
    { label: 'Pix', value: 1693000 },
    { label: 'Cash', value: 573400 },
    { label: 'Debit', value: 538800 },
    { label: 'Credit', value: 359600 },
  ]}
/>
```

#### Related components

- Instead, see Progress: Progress of a task: use `Progress`. A quantity within a range: use `Meter`.
- Instead, see Meter: Progress of a task: use `Progress`. A quantity within a range: use `Meter`.
- Instead, see Chart: Comparing separate values or many categories: use `Chart` or `RankList`.
- Instead, see RankList: Comparing separate values or many categories: use `Chart` or `RankList`.

### Radio

> One option of a `RadioGroup`. `value` is required and identifies the option.

A labelled set of mutually exclusive options with native radio inputs. Built on React Aria `RadioGroup` + `RadioField` + `RadioButton` (the non-deprecated pair that supports a description per option). Shared field behavior is in [Field](../Field/Field.md).

- Import: `import { Radio } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/RadioGroup/RadioGroup.tsx`
- Stories (Storybook title `Components/RadioGroup`): Default, WithSelection, Horizontal, WithDescriptions, Required, Invalid, Disabled, DisabledOption, ReadOnly, LongLabels

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | `ReactNode` |  |  | Secondary text under the label. Linked with `aria-describedby`, not part of the name. |
| `className` | `string` |  |  | Class name for the option root. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the option root `<div>`. Use `inputRef` for the `<input>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `RadioFieldProps` (react-aria-components): `inputRef`
- From `RadioProps` (react-aria): `isDisabled`, `value`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-choice-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-fs-small`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radio-dot-size`, `--ds-radio-size`, `--ds-radius-pill`, `--ds-space-1`, `--ds-space-3`, `--ds-space-5`, `--ds-target-min`, `--ds-text`, `--ds-text-3`

#### When to use

- Choose exactly one of 2 to 5 options that users want to compare.

#### When not to use

- Many options: `Select`.
- Independent choices: `Checkbox`.
- Immediate on/off: `Switch`.

#### Props (key ones)

`RadioGroup`:

| Prop                                                  | Notes                                                                                                                  |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `label`                                               | Group name. Required: pass `label`, `aria-label` or `aria-labelledby` (type error otherwise; development warning too). |
| `description`, `errorMessage`                         | Linked to the group by `aria-describedby`.                                                                             |
| `orientation`                                         | `vertical` (default) or `horizontal`.                                                                                  |
| `value` / `defaultValue` / `onChange(value)`          | React Aria naming; `value` is a string.                                                                                |
| `name`                                                | Shared by every radio; the selected value is submitted.                                                                |
| `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly` | Standard states.                                                                                                       |

`Radio`: `value` (required), `label`, `description`, `isDisabled`, `className`, `inputRef`.

#### Look

- 18px circle (`--ds-radio-size`), `--ds-line-control` border at 3:1 or better in every state, accent border and a 9px accent dot when selected. Hover brightens the border.
- The option row is at least 24px tall and the whole row is clickable.
- A disabled group dims once; a single disabled option uses `--ds-opacity-disabled`.

#### Accessibility and keyboard

| Key                        | Behavior                                                                                        |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| `Tab`                      | One tab stop: lands on the selected radio, or the first one when nothing is selected            |
| `ArrowDown` / `ArrowRight` | Next radio, selects it, wraps from the last to the first (directions follow the text direction) |
| `ArrowUp` / `ArrowLeft`    | Previous radio, selects it, wraps                                                               |
| `Space`                    | Selects the focused radio                                                                       |

Roving focus is handled by React Aria, so only one radio is in the tab order (the handoff made every radio tabbable). `role="radiogroup"` is named by the label; the description and error belong to the group; `aria-required` and `aria-invalid` are set.

#### Example

```tsx
<RadioGroup
  label="Region"
  name="region"
  defaultValue="eu"
  description="You cannot change this later."
>
  <Radio value="eu" label="EU: Frankfurt" />
  <Radio value="us" label="US: Virginia" description="Default for new workspaces." />
</RadioGroup>
```

#### Related components

- Instead, see Select: Many options: `Select`.
- Instead, see Checkbox: Independent choices: `Checkbox`.
- Instead, see Switch: Immediate on/off: `Switch`.
- Renders: Description, FieldMessages, Label

### RadioGroup

> A labelled `role="radiogroup"` of mutually exclusive options with native radio inputs.
The group is one tab stop; arrow keys move and select (roving focus is handled by React Aria).
`value`, `defaultValue` and `onChange(value)` follow React Aria; `name` is shared by every radio.
A group needs a name: pass `label`, `aria-label` or `aria-labelledby`.

A labelled set of mutually exclusive options with native radio inputs. Built on React Aria `RadioGroup` + `RadioField` + `RadioButton` (the non-deprecated pair that supports a description per option). Shared field behavior is in [Field](../Field/Field.md).

- Import: `import { RadioGroup } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/RadioGroup/RadioGroup.tsx`
- Stories (Storybook title `Components/RadioGroup`): Default, WithSelection, Horizontal, WithDescriptions, Required, Invalid, Disabled, DisabledOption, ReadOnly, LongLabels

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | The `Radio` elements of the group. |
| `description` | `ReactNode` |  |  | Helper text under the label. Linked with `aria-describedby`. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text for the group, shown while it is invalid and the error is displayed (after a submit attempt with the default native validation, or at once with `isInvalid`). |
| `orientation` | `'vertical' \| 'horizontal'` |  | `'vertical'` | Layout of the options. Default `vertical`; arrow keys follow the reading direction either way. |
| `className` | `string` |  |  | Class name for the group root. |
| `messages` | `Partial<{ requiredMark: string; }>` |  |  | Message overrides for this instance (`requiredMark`). |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the group root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- From `ValueBase` (@react-types/shared): `defaultValue`, `onChange`, `value`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-choice-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-fs-small`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radio-dot-size`, `--ds-radio-size`, `--ds-radius-pill`, `--ds-space-1`, `--ds-space-3`, `--ds-space-5`, `--ds-target-min`, `--ds-text`, `--ds-text-3`

#### When to use

- Choose exactly one of 2 to 5 options that users want to compare.

#### When not to use

- Many options: `Select`.
- Independent choices: `Checkbox`.
- Immediate on/off: `Switch`.

#### Props (key ones)

`RadioGroup`:

| Prop                                                  | Notes                                                                                                                  |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `label`                                               | Group name. Required: pass `label`, `aria-label` or `aria-labelledby` (type error otherwise; development warning too). |
| `description`, `errorMessage`                         | Linked to the group by `aria-describedby`.                                                                             |
| `orientation`                                         | `vertical` (default) or `horizontal`.                                                                                  |
| `value` / `defaultValue` / `onChange(value)`          | React Aria naming; `value` is a string.                                                                                |
| `name`                                                | Shared by every radio; the selected value is submitted.                                                                |
| `isRequired`, `isInvalid`, `isDisabled`, `isReadOnly` | Standard states.                                                                                                       |

`Radio`: `value` (required), `label`, `description`, `isDisabled`, `className`, `inputRef`.

#### Look

- 18px circle (`--ds-radio-size`), `--ds-line-control` border at 3:1 or better in every state, accent border and a 9px accent dot when selected. Hover brightens the border.
- The option row is at least 24px tall and the whole row is clickable.
- A disabled group dims once; a single disabled option uses `--ds-opacity-disabled`.

#### Accessibility and keyboard

| Key                        | Behavior                                                                                        |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| `Tab`                      | One tab stop: lands on the selected radio, or the first one when nothing is selected            |
| `ArrowDown` / `ArrowRight` | Next radio, selects it, wraps from the last to the first (directions follow the text direction) |
| `ArrowUp` / `ArrowLeft`    | Previous radio, selects it, wraps                                                               |
| `Space`                    | Selects the focused radio                                                                       |

Roving focus is handled by React Aria, so only one radio is in the tab order (the handoff made every radio tabbable). `role="radiogroup"` is named by the label; the description and error belong to the group; `aria-required` and `aria-invalid` are set.

#### Example

```tsx
<RadioGroup
  label="Region"
  name="region"
  defaultValue="eu"
  description="You cannot change this later."
>
  <Radio value="eu" label="EU: Frankfurt" />
  <Radio value="us" label="US: Virginia" description="Default for new workspaces." />
</RadioGroup>
```

#### Related components

- Instead, see Select: Many options: `Select`.
- Instead, see Checkbox: Independent choices: `Checkbox`.
- Instead, see Switch: Immediate on/off: `Switch`.
- Renders: Description, FieldMessages, Label

### RankList

> An ordered list of items with a value, a bar relative to the largest value and an optional
detail. Rows can be plain or buttons.

The list renders the items as given; pass `sort` and `limit` for a "top N". Put it in a
`Card` with `padding="none"`.

An ordered list of items with a value, a bar relative to the largest value and an optional detail. Rows can be plain or buttons. Meant to sit inside a `Card` without body padding.

- Import: `import { RankList } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/RankList/RankList.tsx`
- Stories (Storybook title `Components/RankList`): Default, GivenOrder, SortedAndLimited, WithoutPositions, WithoutSwatchOrMeta, Actionable, Empty, LongLabels, BarsAlign, PortugueseBrazil

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly RankItem[]` | yes |  | The rows, rendered **in the order given** unless `sort` is set. This differs from the handoff, which always sorted descending and kept only six rows: sorting and truncating silently changes the data, so both are opt-in. |
| `aria-label` | `string` |  |  | Accessible name of the list ("Top products"). Optional: a list inside a titled `Card` is already named by it. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the list. |
| `sort` | `'desc' \| 'asc'` |  |  | Sorts by `value` (`desc` largest first, `asc` smallest first) before `limit` is applied. Ties keep their input order. |
| `limit` | `number` |  |  | Shows only the first `limit` rows (after `sort`). Default: all rows. |
| `format` | `(value: number) => ReactNode` |  |  | Formats each value. Default: `formatNumber` with the active locale; use `formatCurrency` for money. |
| `showPosition` | `boolean` |  | `true` | Shows the position (1, 2, 3...) before each row. The list is ordered either way. Default `true`. |
| `emptyState` | `ReactNode` |  |  | Content when there are no rows. Default: the "No data for this period" message. |
| `messages` | `Partial<{ empty: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ RankList: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `empty` | `No data for this period` | Text shown when there are no items. |

#### Design tokens used

`--ds-accent`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-meta`, `--ds-lh-small`, `--ds-line`, `--ds-radius-pill`, `--ds-rank-list-bar-h`, `--ds-rank-list-padding-block`, `--ds-rank-list-padding-inline`, `--ds-rank-list-position-w`, `--ds-rank-list-share`, `--ds-space-2`, `--ds-space-3`, `--ds-space-6`, `--ds-surface-row-hover`, `--ds-text`, `--ds-text-2`, `--ds-weight-medium`

#### When to use

- "Top products", "best customers", "colors by sales": a short ranking with comparable values.

#### When not to use

- Several columns, sorting by the user, selection: use `DataTable`.
- Parts of a whole: use `ProportionBar`.
- A trend over time: use `Chart`.

#### Anatomy

```
div.root
  ol (role=list)
    li > div | button     grid, shared columns for all rows (subgrid)
      position            decorative number (aria-hidden); the ol already numbers the items
      label               optional swatch (aria-hidden) + text, truncated
      value               mono, formatted
      bar                 4px track + fill, relative to the largest value (aria-hidden)
      meta                mono detail, optional
```

#### Props (key ones)

| Prop           | Type                   | Default | Notes                                                                       |
| -------------- | ---------------------- | ------- | --------------------------------------------------------------------------- |
| `items`        | `RankItem[]`           | -       | `id`, `label`, `value`, `meta`, `swatch`, `onAction`. Rendered **as given** |
| `sort`         | `asc \| desc`          |         | Opt-in sort by value (stable ties)                                          |
| `limit`        | `number`               |         | Opt-in truncation, applied after `sort`                                     |
| `format`       | `(value) => ReactNode` | `Intl`  | Use `formatCurrency` for money                                              |
| `showPosition` | `boolean`              | `true`  | Numbers 1, 2, 3 of the rows shown                                           |
| `emptyState`   | `ReactNode`            |         | Default: "No data for this period" (messages)                               |
| `aria-label`   | `string`               |         | Optional name of the list                                                   |
| `messages`     | `Partial<messages>`    |         | `empty`                                                                     |

#### Accessibility

- A real ordered list (`ol`, explicit `role="list"` so Safari keeps the semantics with `list-style: none`).
- Rows with `onAction` are `<button>`s (React Aria `Button`): Tab, Enter, Space. Their name is the label followed by the value; position, bar and swatch are hidden from assistive technology.
- The bar and swatch are decorative: the value (and `meta`) carry the information as text.
- Bars of all rows share one grid, so their lengths are comparable.
- Text colors: label `text`, meta `text-2` (stays above 4.5:1 on hover); focus is an inset accent outline (system color in forced colors).

#### Content rules

- Labels are names, not sentences. Meta is short and mono: `12 units · 18%`.
- Use this for things (products, colors, customers). Give customers an `onAction` that opens the profile.

#### Example

```tsx
<Card padding="none" title="Top products">
  <RankList
    sort="desc"
    limit={6}
    format={(v) => formatCurrency(v, 'USD', locale)}
    items={products.map((f) => ({
      id: f.id,
      label: f.name,
      value: f.totalMinor,
      swatch: f.hex,
      meta: `${f.units} units · ${f.pct}`,
    }))}
  />
</Card>
```

#### Related components

- Instead, see DataTable: Several columns, sorting by the user, selection: use `DataTable`.
- Instead, see ProportionBar: Parts of a whole: use `ProportionBar`.
- Instead, see Chart: A trend over time: use `Chart`.
- Renders: Swatch

### Rating

> A read-only star rating. It is a single image (`role="img"`) with a text alternative such
as "3.5 out of 5 stars"; the stars themselves are decorative. Half stars are supported.

It does not accept input. An interactive rating needs radio-group semantics and is not part
of the design system yet.

A read-only star rating, such as a review score. One image with a text alternative ("3.5 out of 5 stars"); half stars are supported.

- Handoff source: `components/display/Rating` (TODO `CMP-DSP-06`).

- Import: `import { Rating } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Rating/Rating.tsx`
- Stories (Storybook title `Components/Rating`): Default, HalfStar, Empty, Full, WithValue, Sizes, CustomScale, OutOfRange, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | `number` | yes |  | The rating to show, from 0 to `max`. Values are clamped and rounded to the nearest half star ("3.7" shows three and a half stars, and says "3.5 out of 5 stars"). |
| `max` | `number` |  | `5` | Number of stars. A whole number from 1. Default `5`. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Star size token: `sm` 12px, `md` 14px (default), `lg` 18px. |
| `showValue` | `boolean` |  | `false` | Also shows the value as text ("3.5/5") after the stars. Hidden from assistive technology: the name already says it. |
| `messages` | `Partial<{ label: (value: string, max: string, maxCount: number) => string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Rating: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `label(value: string, max: string, maxCount: number)` | `{value} out of {max} stars` | Accessible name of the rating. Arguments are already formatted for the locale. |

#### Design tokens used

`--ds-font-mono`, `--ds-fs-label`, `--ds-lh-label`, `--ds-line-control`, `--ds-rating-fill`, `--ds-rating-gap`, `--ds-rating-star-gap`, `--ds-text-2`, `--ds-warning`, `--ds-weight-medium`

#### When to use

- Show a score someone else gave (a review, a quality grade).
- Next to the review text in lists and cards, optionally with the numeric value.

#### When not to use

- To collect a rating: it takes no input. An interactive rating needs radio-group semantics (one tab stop, arrows, `Space`) and is out of scope for now; use `SegmentedControl` or `RadioGroup` with labelled options meanwhile.
- For an average with a distribution or a trend: use `Chart` or `ProportionBar`.

#### Anatomy

```
span[role=img][aria-label="3.5 out of 5 stars"]
  stars (aria-hidden)
    star x max      empty glyph + clipped filled glyph (0, 50 or 100 %)
  value             optional "3.5/5" (aria-hidden)
```

#### Accessibility

- `role="img"` with an `aria-label` from messages; the glyphs and the visible value are `aria-hidden`, so the rating is announced once.
- The label is pluralized by the scale (`1 out of 1 star`, `3.5 out of 5 stars`) and numbers follow the locale (`3,5 de 5 estrelas` in pt-BR).
- The value is not carried by color alone: the label and the optional value text state the number. The empty star uses `--ds-line-control` (3:1 against the surfaces); filled uses `--ds-warning`.
- Forced colors: filled stars use `CanvasText`, empty ones `GrayText`.

#### Content rules

- Show the number next to the stars when the exact value matters; stars alone are fine in dense lists.
- Pair a rating with the review it belongs to; do not leave it alone in a row of badges.

#### Examples

```tsx
<Rating value={4} />
<Rating value={3.5} showValue size="lg" />
<Rating value={7} max={10} />
```

#### Related components

- Instead, see SegmentedControl: To collect a rating: it takes no input. An interactive rating needs radio-group semantics (one tab stop, arrows, `Space`) and is out of scope for now; use `SegmentedControl` or `RadioGroup` with labelled options meanwhile.
- Instead, see RadioGroup: To collect a rating: it takes no input. An interactive rating needs radio-group semantics (one tab stop, arrows, `Space`) and is out of scope for now; use `SegmentedControl` or `RadioGroup` with labelled options meanwhile.
- Instead, see Chart: For an average with a distribution or a trend: use `Chart` or `ProportionBar`.
- Instead, see ProportionBar: For an average with a distribution or a trend: use `Chart` or `ProportionBar`.
- Renders: Icon
- Used by: ApprovalCard

### RequiredMark

> The visible marker of a required field, text from messages. Hidden from assistive technology:
the control announces "required" itself. Use it when a field cannot use `Label`
(for example inside a `Checkbox` label).

Shared building blocks that make every form control (`Input`, `Textarea`, `Select`, `Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`) look and behave the same: the same label, description and error styles, the same spacing, the same required marker, the same disabled treatment and the same validation timing. Tickets: ARCH-008, ARCH-009, part of GAP-003.

Most code never imports from `Field` directly: use the ready-made controls. Use the pieces when you compose a field that has no ready-made component yet (for example a custom picker built on a React Aria field).

- Import: `import { RequiredMark } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Field/Field.tsx`
- Stories (Storybook title `Components/Field`): Anatomy, ErrorsAfterSaveAttempt, RealtimeValidation, StandaloneErrorText

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `messages` | `Partial<{ requiredMark: string; }>` |  |  | Message overrides for this instance (`requiredMark`). |

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Field: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `requiredMark` | `*` | Visible marker after the label of a required field. Hidden from assistive technology. |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-field-gap`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-1`, `--ds-success`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-weight-medium`

#### Exports

| Export                                 | What it is                                                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Label`                                | React Aria `Label` with the field label style (13/18, medium). `isRequired` appends the required marker.                                                                       |
| `Description`                          | React Aria `Text slot="description"`, 13/18 in `--ds-text-3`. Linked to the control with `aria-describedby`. `tone` tints it (see Toned description).                          |
| `FieldError`                           | React Aria `FieldError`: renders only while the field is invalid and the error is displayed. The message is in a `role="alert"` element. 13/18 in `--ds-danger`.               |
| `ErrorText`                            | Standalone error text for a group with no field around it. Same look as `FieldError`; `id` (generated by default), `announce` adds `role="alert"`. Renders nothing when empty. |
| `FieldMessages`                        | `Description` (with `descriptionTone`) followed by `FieldError`. Every control renders it under its box.                                                                       |
| `RequiredMark`                         | The marker alone, for fields whose label is not a `Label`.                                                                                                                     |
| `FieldMessageTone`                     | Type: `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'`, the tone of a description.                                                                                |
| `FieldLabelingProps`, `WithLabel`      | Types. `FieldLabelingProps` makes "label, `aria-label` or `aria-labelledby`" mandatory. `WithLabel<P>` helps type stories.                                                     |
| `FieldErrorMessage`, `FieldValidation` | Types for the `errorMessage` prop (a node or a function of the validation result).                                                                                             |

#### Anatomy and spacing

```
Label                       13/18 medium, --ds-text
  gap: --ds-field-gap (6px)
Control box                 border --ds-line-control, radius md, height 32/40/48
  gap: --ds-field-gap
Description                 13/18, --ds-text-3
Error                       13/18, --ds-danger
```

The description stays visible when an error shows (the handoff replaced the hint with the error). Constraints such as "8 characters or more" remain useful while the user fixes the value, and both texts are linked to the control.

#### Toned description (GAP-039)

A live check under a field ("Matches", "Over by $5", "Short by $5") is a description with a tone, not an error: the field stays valid and no `role="alert"` is added.

```tsx
<CurrencyInput
  label="Amount received"
  currency="USD"
  description="Short by $5.00"
  descriptionTone="danger"
/>
```

- `descriptionTone` (`neutral` default, `accent`, `success`, `warning`, `danger`) is supported by `Input`, `Textarea`, `Select`, `Combobox`, `NumberField`, `CurrencyInput` and `SegmentedControl`; `Description` and `FieldMessages` take `tone` / `descriptionTone`.
- The text carries the meaning; the tone only reinforces it. Write the words yourself ("Over by $5", not a bare "$5") and never rely on colour alone. The tone sets `data-tone` on the description element and nothing else changes: the description is announced exactly as before through `aria-describedby`.
- Colours are the signal tokens `--ds-accent`, `--ds-success`, `--ds-warning`, `--ds-danger`, which pass 4.5:1 on `--ds-bg`, `--ds-surface` and `--ds-surface-raised` (see `contrast-pairs.json`).
- Use `errorMessage` when the value must be fixed before submitting; use a toned description for information that can be left as it is.
- Other fields built on `FieldMessages` (`Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`, `ChoiceTiles`, `DatePicker`, `TagInput`) do not expose `descriptionTone` yet.

#### One state model (ARCH-009)

| State     | Look                                                                                                                       | Semantics                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Default   | `--ds-line-control` border, `--ds-bg` fill                                                                                 |                                                    |
| Hover     | Border brightens to `--ds-text-3`. The fill never changes, so the border stays at 3:1 or more.                             |                                                    |
| Focus     | Accent border and the 3px focus ring (`--ds-focus-ring`); forced-colors gets a system outline                              |                                                    |
| Invalid   | Danger border and danger focus ring                                                                                        | `aria-invalid`, error linked by `aria-describedby` |
| Read only | `--ds-surface` fill, same border                                                                                           | `readonly`; focusable, submitted with the form     |
| Disabled  | Label and control at `--ds-opacity-disabled`, dashed border, `--ds-surface` fill; description and error stay full strength | `disabled`; not focusable, not submitted           |
| Required  | Marker after the label                                                                                                     | `required` / `aria-required` on the control        |

Form-control borders use `--ds-line-control` and stay at 3:1 or better against the page in every state (WCAG 1.4.11). The suites assert this per state.

#### Required marker

`Label isRequired` appends the text of the `requiredMark` message (`*` by default) inside the label. The marker is `aria-hidden`: the control itself exposes "required", so announcing the marker too would repeat it. Override the text per instance (`messages={{ requiredMark: '(required)' }}`) or app-wide:

```tsx
<DSProvider locale="pt-BR" messages={{ Field: { requiredMark: '(obrigatório)' } }}>
```

#### Validation behavior: native (default), and why

React Aria fields validate in one of two modes:

- `validationBehavior="native"` (React Aria's default, kept here): the browser's constraint validation. Constraints such as `required`, `type`, `pattern` and `minLength` block submission. The error is **not displayed until the user tries to submit**; then focus moves to the first invalid field and the error appears. Custom `validate` rules report when the user commits the field (leaves it) and again on submit.
- `validationBehavior="aria"`: only ARIA attributes are set; nothing blocks submission, and the error follows every keystroke.

**Decision: `native` is the default for all fields.** It implements the product rule _errors appear only after a save attempt_ without extra code, it works without JavaScript hydration problems (the browser blocks the submit), it puts `required` on the real control and it moves focus to the first problem. `aria` suits fields that need live feedback (a username availability check, a counter): opt in per field with `validationBehavior="aria"`. A consumer that renders its own `Form` can set the mode for every field below it.

Rules for authors:

- Provide an `errorMessage` that says how to fix the problem ("Enter a complete email address."). Without one, React Aria shows the browser's own message, in the browser's language. A static `errorMessage` replaces only that browser text: a message the app supplied (a `validate` rule or `validationErrors` on a `Form`) is shown instead (GAP-009).
- To control `isInvalid` yourself (for example after a server response), pass `isInvalid` and `errorMessage`; the error shows at once.
- The error text is announced when it appears (`role="alert"`) and read again when focus lands on the field.
- Putting `<form>` in the page is enough; no wrapper component is required.

#### Errors outside a field: `ErrorText`

| Use                   | When                                                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `FieldError`          | Inside a React Aria field (`Input`, `Select`, `CheckboxGroup`, ...): validation is wired for you.                     |
| `ErrorText`           | A group of controls you built by hand (colour options, rows) with no field around it. Light, inline, under the group. |
| `Alert tone="danger"` | An error about the whole page, form or request ("Could not save the order"). Heavy, boxed.                            |

`ErrorText` renders whenever it has content, so you decide when it shows. It is not a live region by default: link it with `aria-describedby`, and move focus to the first invalid control on submit so the message is read. Set `announce` when the error appears with no focus move (it adds `role="alert"`). `aria-invalid` is not allowed on `role="group"`; if the group has a role that supports it (`radiogroup`, `listbox`), set it together with `aria-describedby`.

```tsx
const errorId = useId();
<div
  role="group"
  aria-labelledby={labelId}
  aria-describedby={error ? errorId : undefined}
>
  {options}
</div>
<ErrorText id={errorId}>{error}</ErrorText>
```

#### Accessibility

- Every control needs an accessible name: `label`, `aria-label` or `aria-labelledby`. The types enforce it; a development warning covers untyped callers.
- `Description` and `FieldError` are linked with `aria-describedby`; the order is description, then error.
- Disabled fields are exempt from contrast requirements; everything else meets 4.5:1 for text and 3:1 for borders.

#### Related components

- Used by: Checkbox, Switch

### ResponseFeedback

> Feedback and follow-up actions under an assistant response: two toggle buttons (good and bad
response, `aria-pressed`), then optional Copy and Regenerate.

Choosing a rating is reversible, so nothing asks to confirm: pressing the active rating again
removes it. A polite live region says "Feedback sent" or "Feedback removed" after the change.
The first render never announces anything. The buttons show text only for now: thumbs, copy
and refresh icons are not part of the curated icon set yet.

Feedback and follow-up actions under an assistant response: good and bad response toggles, then optional Copy and Regenerate. Import it from `loui-ds/patterns`.

- Import: `import { ResponseFeedback } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/ResponseFeedback/ResponseFeedback.tsx`
- Stories (Storybook title `Patterns/ResponseFeedback`): Default, RatedBad, RatingOnly, Regenerating, Disabled, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | `ResponseRating \| null` |  |  | Controlled rating. `null` means no rating. |
| `defaultValue` | `ResponseRating \| null` |  | `null` | Initial rating when uncontrolled. |
| `onChange` | `(value: ResponseRating \| null) => void` |  |  | Called with the new rating, or `null` when the person takes their rating back. |
| `onCopy` | `() => void` |  |  | Called when Copy is pressed. Without it there is no Copy button. Confirm with a toast ("Copied"). |
| `onRegenerate` | `() => void` |  |  | Called when Regenerate is pressed. Without it there is no Regenerate button. |
| `isRegenerating` | `boolean` |  | `false` | Disables Regenerate while a new response is being generated. |
| `isDisabled` | `boolean` |  | `false` | Disables every button. |
| `messages` | `Partial<{ groupLabel: string; positive: string; negative: string; copy: string; regenerate: string; sent: string; removed: string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ ResponseFeedback: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `groupLabel` | `Rate this response` | Accessible name of the group of rating buttons. |
| `positive` | `Good response` | Toggle buttons; pressed means the rating is set. |
| `negative` | `Bad response` |  |
| `copy` | `Copy response` | Action buttons (verb plus object). |
| `regenerate` | `Regenerate response` |  |
| `sent` | `Feedback sent` | Polite announcements after a rating changes. |
| `removed` | `Feedback removed` |  |

#### Design tokens used

`--ds-font-sans`, `--ds-line-subtle`, `--ds-response-feedback-divider-gap`, `--ds-response-feedback-gap`

#### When to use

- Under each assistant response in a `ChatPanel`, to learn which answers help.

#### When not to use

- Collecting a written review or a star rating: use `Rating` in a form.
- Anything that sends the rating somewhere the owner cannot see: say where it goes in your product.

#### Anatomy

```
div
  group "Rate this response"   toggle "Good response" · toggle "Bad response"   (aria-pressed)
  button "Copy response"       only with onCopy
  button "Regenerate response" only with onRegenerate
  status                       visually hidden live region
```

#### Accessibility

- The rating buttons are toggle buttons (`aria-pressed`) in a labelled group. Each is a tab stop; `Space` and `Enter` press.
- Rating is reversible, so nothing asks to confirm: pressing the active button again removes the rating.
- A polite live region says "Feedback sent" or "Feedback removed" after a change. It is silent on first render.
- Each control shows a decorative icon (`ThumbsUpIcon`, `ThumbsDownIcon`, `CopyIcon`, `RefreshIcon`) next to its visible text label; the text is the accessible name.

#### Content rules

- Buttons are verb plus object ("Copy response", "Regenerate response").
- Confirm Copy with a short past-tense toast ("Copied"), outside this pattern.
- Regenerate replaces content: offer Undo, as for any reversible action.

#### Example

```tsx
<ResponseFeedback
  onChange={(rating) => saveRating(message.id, rating)}
  onCopy={() => copyToClipboard(message.content)}
  onRegenerate={() => regenerate(message.id)}
  isRegenerating={busy}
/>
```

#### Related components

- Instead, see Rating: Collecting a written review or a star rating: use `Rating` in a form.
- Renders: Button, Icon, Toggle, VisuallyHidden

### ScrollArea

> A scrolling container with thin, themed scrollbars. It scrolls inside the space its parent
gives it: give it a height (or put it in a flex column and let it shrink).

While its content overflows it becomes a keyboard stop (`tabindex="0"`) and a labelled
`region`, so keyboard users can scroll it with the arrow keys (WCAG 2.1.1). When nothing
overflows it is a plain container, with no tab stop and no landmark. A name is therefore
always required.

A scrolling container with thin, themed scrollbars that stays keyboard accessible.

- Import: `import { ScrollArea } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/ScrollArea/ScrollArea.tsx`
- Stories (Storybook title `Layout/ScrollArea`): Default, MaxHeight, NotScrollable, Horizontal, Both, LabelledBy, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `orientation` | `'both' \| 'horizontal' \| 'vertical'` |  | `'vertical'` | Which axes scroll. Default `vertical`. |
| `maxBlockSize` | `string \| number` |  |  | Maximum height of the region: a CSS length (`"20rem"`, `"40vh"`) or a number of pixels. The region grows with its content up to this height and then scrolls, which suits a list that should show a fixed number of rows (a searchable picker). Set as the `--ds-scroll-area-max-h` custom property; without it the region is limited by its parent (`100%`). While it scrolls it stays a focusable, labelled region. |
| `aria-label` | `string` |  |  | Accessible name of the region ("Order history"). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the region. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-line-control`, `--ds-scroll-area-max-h`, `--ds-space-1`, `--ds-text-3`

#### When to use

- A bounded list, log or panel inside a page: a notification list, a long form step, a code output.
- A region that must scroll on its own while the page around it does not.

#### When not to use

- For the page itself: let the document scroll, or use `AppShell`'s `main`.
- For a table: `DataTable` has its own horizontal scroll and sticky parts.
- Inside a Dialog or Sheet body: those already scroll their body.

#### Anatomy

```
div (overflow auto, scrollbar-width: thin)
  div (content wrapper, observed for size changes)
    children
```

#### Accessibility

- A scroll container must be reachable by keyboard (WCAG 2.1.1). While the content overflows, the area gets `tabindex="0"` and `role="region"` with your label; with nothing to scroll it is a plain container (no tab stop, no landmark). A `ResizeObserver` keeps this in sync as content or size changes.
- Because focusability is dynamic, the type always requires a name, so a scrollable area is never unlabelled.
- Arrow keys, `PageUp`/`PageDown`, `Home`/`End` scroll it natively.
- The focus ring is drawn inside the box, so a clipping parent cannot hide it.
- Scrollbars are the browser's thin scrollbars colored with `--ds-line-control` (3:1 on the background); on hover they brighten to `--ds-text-3`.

#### Content rules

- Name it for what it holds: "Order history", "Activity", not "Scrollable area".

#### Examples

```tsx
<div style={{ blockSize: 240 }}>
  <ScrollArea aria-label="Activity">{events.map(renderEvent)}</ScrollArea>
</div>
```

#### Related components

- Instead, see AppShell: For the page itself: let the document scroll, or use `AppShell`'s `main`.
- Instead, see DataTable: For a table: `DataTable` has its own horizontal scroll and sticky parts.

### SearchInput

> A search box: leading search icon, clear button (and `Escape` clears), optional decorative
shortcut hint, optional suggestions with accent-insensitive match highlighting. Built on React
Aria `SearchField` (plain) or `ComboBox` (with `suggestions`).

`onSubmit(text)` fires on `Enter` when no suggestion is highlighted.

A search box: leading search icon, clear button, optional decorative shortcut hint and optional suggestions with accent-insensitive match highlighting. Built on React Aria `SearchField` (plain) or `ComboBox` (with `suggestions`). Task: CMP-INP-06.

- Import: `import { SearchInput } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/SearchInput/SearchInput.tsx`
- Stories (Storybook title `Components/SearchInput`): Default, ClearButton, WithShortcutHint, Landmark, WithSuggestions, AccentInsensitiveHighlight, NoSuggestions, Disabled, VisibleLabel, Sizes, FullWidthInRow

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | `string` |  |  | The text. Pair with `onChange`. |
| `defaultValue` | `string` |  |  | The initial text when uncontrolled. |
| `onChange` | `((value: string) => void)` |  |  | Called with the new text on every keystroke and when it is cleared. |
| `suggestions` | `readonly (string \| SearchSuggestion)[]` |  |  | Suggestions shown under the box while typing, matched accent- and case-insensitively against `label` with the matching part highlighted. Strings are shorthand for `{ label }`. Without this prop the component is a plain search field (`role="searchbox"`); with it the input is a combobox (`role="combobox"`). Keep the array order: it is the order shown. |
| `onSelect` | `((suggestion: SearchSuggestion) => void)` |  |  | Called when a suggestion is chosen (click or `Enter` on the highlighted one). |
| `maxResults` | `number` |  |  | Most suggestions shown. Default `6`. |
| `shortcut` | `readonly string[]` |  |  | A decorative hint of the global shortcut that focuses the search (`['Mod', 'K']`, `['/']`), drawn with `Kbd` while the box is empty. It does not register the shortcut: use `useHotkey` and focus `inputRef` yourself. Hidden from assistive technology, since the hint is only useful when the shortcut exists; announce it with `aria-keyshortcuts` if it does. |
| `placeholder` | `string` |  |  | Text shown while the box is empty. Default from messages: "Search". |
| `landmark` | `boolean` |  |  | Wraps the field in a `role="search"` landmark named by the label. Use it once per page for the main search of a page or site; not for filters inside a table. |
| `size` | `'sm' \| 'md' \| 'lg'` |  |  | Control height: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `fullWidth` | `boolean` |  |  | Take the free space of a flex row (an `Inline`): the field grows to fill it and can shrink below its content width. Off by default. In a block context the field already spans the width. |
| `className` | `string` |  |  | Class name for the field root. |
| `popoverClassName` | `string` |  |  | Class name for the popover that holds the suggestions. |
| `inputRef` | `Ref<HTMLInputElement>` |  |  | Ref to the `<input>` element. The `ref` prop points at the field root. |
| `messages` | `Partial<{ clear: string; placeholder: string; noResults: string; } & { requiredMark: string; }>` |  |  | Message overrides for this instance: `clear`, `placeholder`, `noResults`. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaSearchFieldProps` (react-aria): `enterKeyHint`, `type`
- From `AriaTextFieldProps` (react-aria): `aria-activedescendant`, `aria-autocomplete`, `aria-controls`, `aria-haspopup`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `DOMProps` (@react-types/shared): `id`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `SearchFieldProps` (react-stately): `onClear`, `onSubmit`
- From `SlotProps` (react-aria-components): `slot`
- From `TextInputDOMEvents` (@react-types/shared): `onBeforeInput`, `onCompositionEnd`, `onCompositionStart`, `onCompositionUpdate`, `onCopy`, `onCut`, `onInput`, `onPaste`
- From `TextInputDOMProps` (@react-types/shared): `autoComplete`, `autoCorrect`, `inputMode`, `maxLength`, `minLength`, `pattern`, `spellCheck`
- From `Validation` (@react-types/shared): `isInvalid`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ SearchInput: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `clear` | `Clear search` | Accessible name of the clear button. |
| `placeholder` | `Search` | Placeholder when none is given. |
| `noResults` | `No results` | Shown in the suggestions list when nothing matches the text. |

#### Design tokens used

`--ds-combobox-popover-max-height`, `--ds-field-control-padding-inline`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-strong`, `--ds-radius-lg`, `--ds-radius-sm`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-6`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-target-min`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`, `--ds-z-dropdown`

#### When to use

- Searching a list, a table or the app, with or without suggestions.

#### When not to use

- Choosing a value from a list: `Combobox` (it keeps a selected value; SearchInput keeps free text).
- Filters with several fields: compose `Input`, `Select`.

#### Modes

| Mode               | Element                                  | Notes                                                                                                                                                      |
| ------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plain (default)    | `input[type=search]`, `role="searchbox"` | Clear button; `Escape` clears; `onSubmit(text)` on `Enter`.                                                                                                |
| With `suggestions` | `role="combobox"`                        | List under the box while there is text. `Escape` closes the list, then clears. `Enter` on a highlighted suggestion calls `onSelect`; otherwise `onSubmit`. |

#### Props (key ones)

| Prop                                                                                                  | Notes                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `aria-label` / `label` / `aria-labelledby`                                                            | One is required. Most searches use `aria-label` ("Search products") and no visible label.                                                                                      |
| `value` / `defaultValue` / `onChange(text)`                                                           | Controlled / uncontrolled text.                                                                                                                                                |
| `onSubmit(text)`, `onClear()`                                                                         | `Enter` and the clear action.                                                                                                                                                  |
| `suggestions`, `onSelect`, `maxResults`                                                               | Strings or `{ label, meta, data }`. Matched on `label` with `matchesSearch`, highlighted with `highlightMatch`, at most `maxResults` (default 6), in the order given.          |
| `shortcut`                                                                                            | Decorative hint such as `['Mod', 'K']`, drawn with `Kbd` while the box is empty. It registers nothing: use `useHotkey` and focus `inputRef`. Hidden from assistive technology. |
| `landmark`                                                                                            | Wraps the field in `role="search"` named by the label. Once per page.                                                                                                          |
| `size`, `placeholder`, `name`, `isDisabled`, `isReadOnly`, `autoFocus`, `inputRef`, `ref`, `messages` | `messages`: `clear`, `placeholder`, `noResults`.                                                                                                                               |
| `fullWidth`                                                                                           | Take the free space of a flex row such as `Inline` (`flex: 1 1 auto`, can shrink). Off by default.                                                                             |

#### Accessibility and keyboard

| Key                     | Behavior                                                                    |
| ----------------------- | --------------------------------------------------------------------------- |
| Typing                  | Plain: updates the text. Suggestions: opens the list when there are matches |
| `ArrowDown` / `ArrowUp` | (Suggestions) move through the list; focus stays in the input               |
| `Enter`                 | Select the highlighted suggestion, else `onSubmit(text)`                    |
| `Escape`                | Plain: clear. Suggestions: close the list, then clear                       |

The clear button is "Clear search" (from messages), out of the tab order in suggestions mode, hidden while the box is empty. Highlighted parts are `<mark>` without a background: only weight and brightness change, so contrast holds.

#### Content rules

`aria-label` names the scope ("Search products"), not the control. Placeholder "Search" is a hint, never the name.

#### Example

```tsx
<SearchInput
  aria-label="Search products"
  value={query}
  onChange={setQuery}
  suggestions={products}
  onSelect={(product) => open(product.data)}
  shortcut={['/']}
/>
```

#### Related components

- Instead, see Combobox: Choosing a value from a list: `Combobox` (it keeps a selected value; SearchInput keeps free text).
- Instead, see Input: Filters with several fields: compose `Input`, `Select`.
- Instead, see Select: Filters with several fields: compose `Input`, `Select`.
- Renders: Icon, Kbd

### SegmentedControl

> A segmented control picks one value from a few options, like a radio group drawn as a
bar. It is a value control: it does not own panels (use `Tabs` for that). Exactly one
option is always selected.

Built on React Aria `ToggleButtonGroup` with single selection and no empty selection:
it is exposed as a radio group, with one tab stop and arrow-key navigation.

With `label` and/or `description` the bar is wrapped in a field-like column: the label names
the group, the description is linked with `aria-describedby`. Long labels never truncate:
when the options are wider than the container the bar scrolls sideways.

A bar of two to five options where exactly one is selected, like a radio group drawn as buttons. It is a value control: it changes how something is shown or filtered, it does not own panels. Built on React Aria `ToggleButtonGroup` with single selection and no empty selection.

- Handoff source: `components/forms/SegmentedControl.jsx` (TODO `CMP-FRM-09`).

- Import: `import { SegmentedControl } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/SegmentedControl/SegmentedControl.tsx`
- Stories (Storybook title `Components/SegmentedControl`): Default, Small, FullWidth, WithCounts, DisabledOption, DisabledGroup, KeyboardSelection, Controlled, LongLabels, WithLabel, WithDescription, ToneDescription, FourOptions, InsideStack, ShortcutHint, PortugueseCounts, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `options` | `readonly SegmentedControlOption[]` | yes |  | The options, in display order. Two to five fit comfortably. |
| `value` | `string` |  |  | Selected option (controlled). |
| `defaultValue` | `string` |  |  | Initially selected option (uncontrolled). Defaults to the first enabled option. |
| `onChange` | `(value: string) => void` |  |  | Called with the new value when the user selects another option. |
| `description` | `ReactNode` |  |  | Helper text under the bar, linked to the group with `aria-describedby`. It can hold a `Kbd` to show the shortcuts of the options (see SegmentedControl.md). |
| `descriptionTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the description, same as on `Input`: the text carries the meaning. |
| `size` | `'sm' \| 'md'` |  | `'md'` | Height of the segments: `sm` 24px, `md` 32px (default). |
| `fullWidth` | `boolean` |  | `false` | Stretch to the container; the segments share the width equally. Without it the bar is as wide as its options, also inside a `Stack` (which stretches its children by default). |
| `className` | `string` |  |  | Class name for the bar (the group element), also when a `label` or `description` wraps it. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the group element. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `DOMRenderProps` (react-aria-components): `render`
- From `SlotProps` (react-aria-components): `slot`
- From `ToggleGroupProps` (react-stately): `isDisabled`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-line-control`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-radius-sm`, `--ds-segmented-control-height-md`, `--ds-segmented-control-height-sm`, `--ds-segmented-control-padding`, `--ds-space-2`, `--ds-space-3`, `--ds-surface`, `--ds-surface-hover`, `--ds-text`, `--ds-text-2`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- A view mode (List, Board, Calendar), a period (Day, Week, Month) or a small filter (All, Open, Closed).
- When the options are always visible and the change applies immediately.

#### When not to use

- To switch between panels of content: use `Tabs`.
- For more than five options, or labels that are whole sentences: use `Select` or `RadioGroup`. Long labels do not truncate (the bar scrolls sideways), but a scrolling bar hides options.
- For on/off settings: use `Switch`.

#### Anatomy

```
div.field                              (only with label or description)
  span  label                          (names the group, aria-labelledby)
  div[role=radiogroup]                 (bordered track)
    button[role=radio] aria-checked    (one per option)
      label
      count                            (optional, mono)
  span  description                    (aria-describedby, optional tone)
```

Without `label` and `description` the track is rendered alone, named by `aria-label` or `aria-labelledby`.

#### Width and overflow

- The bar is as wide as its options. It does not stretch in a `Stack` (which stretches its children) unless `fullWidth` is set.
- Labels never truncate or wrap. When the options are wider than the container, the bar is capped at the container width and scrolls sideways; a focused option scrolls into view, and the keyboard contract does not change. With `fullWidth` the segments share the width equally but never get narrower than their label.
- Keep labels short anyway: a scrolling bar hides options. Four short options fit in 440 px.

#### Shortcut hints

`count` is text or a number and cannot show a shortcut, and an option has no slot for a `Kbd`: a hint inside an option would become part of its accessible name ("List Control 1"). Show the shortcuts once, in the `description`, where they are read as a description of the group, and register them with `useHotkey`:

```tsx
<SegmentedControl
  label="View"
  options={views}
  value={view}
  onChange={setView}
  description={
    <>
      Switch with <Kbd keys={['Alt', '1']} /> <Kbd keys={['Alt', '2']} />
    </>
  }
/>
```

#### Accessibility

- Semantics: `radiogroup` with `radio` buttons and `aria-checked`. It is deliberately not a `tablist`.
- Keyboard: one tab stop; `←` / `→` move focus between options, `Space` selects the focused option. React Aria does not wrap at the ends. Disabled options are skipped. The selection can never be empty.
- The visible `label` is a `span` referenced by `aria-labelledby` (a `label` element would not name a group); the description is referenced by `aria-describedby`. A consumer `aria-describedby` is kept, in front of the description.
- A disabled control dims its label like the other fields.
- Selected state is shown by a raised background, a line and ink text, not by color alone. The track border uses `--ds-line-control` (3:1).
- The count uses `--ds-text-2`: `--ds-text-3` would fail 4.5:1 on the selected surface.
- Focus: accent border and ring. Forced colors: the selected segment border uses `Highlight`.

#### Content rules

- Labels are one word or a short phrase in sentence case ("Open", "This week").
- Same-length labels look best; avoid mixing a count on some options only.
- With a `label`, name the setting, not the control ("Transaction type", not "Segmented control"); do not repeat it in the options.

#### Examples

```tsx
<SegmentedControl
  label="Transaction type"
  description="Changes the fields below."
  options={types}
  value={type}
  onChange={setType}
/>

<SegmentedControl
  aria-label="View"
  options={[
    { value: 'list', label: 'List' },
    { value: 'board', label: 'Board' },
  ]}
  value={view}
  onChange={setView}
/>

<SegmentedControl
  aria-label="Order status"
  size="sm"
  options={[
    { value: 'all', label: 'All', count: 1248 },
    { value: 'open', label: 'Open', count: 12, countLabel: '12 open' },
  ]}
/>
```

#### Related components

- Instead, see Tabs: To switch between panels of content: use `Tabs`.
- Instead, see Select: For more than five options, or labels that are whole sentences: use `Select` or `RadioGroup`. Long labels do not truncate (the bar scrolls sideways), but a scrolling bar hides options.
- Instead, see RadioGroup: For more than five options, or labels that are whole sentences: use `Select` or `RadioGroup`. Long labels do not truncate (the bar scrolls sideways), but a scrolling bar hides options.
- Instead, see Switch: For on/off settings: use `Switch`.
- Renders: VisuallyHidden

### Select

> A single-choice dropdown built on React Aria `Select`: a button that opens a listbox in a
popover. Keyboard: Enter, Space or the arrow keys open it; typing selects by prefix (typeahead);
Escape closes it and returns focus to the trigger. A hidden native `<select>` carries `name` and
the value into form submission and browser autofill.

Use it for 4 or more options; for 2 to 4 prefer `RadioGroup`.

Single-choice dropdown: a button that opens a listbox in a popover. Built on React Aria `Select` (`Button`, `SelectValue`, `Popover`, `ListBox`). A hidden native `<select>` carries `name` and the value into form submission and autofill. Shared field behavior is in [Field](../Field/Field.md).

- Import: `import { Select } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Select/Select.tsx`
- Stories (Storybook title `Components/Select`): Default, KeyboardAndTypeahead, EscapeClosesAndRestoresFocus, Open, WithSelection, WithDescription, Required, Invalid, Disabled, Sizes, DisabledOptions, Sections, LongLabels, FullWidthInRow

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `options` | `readonly (SelectOption \| SelectGroup)[]` | yes |  | The options, or groups of options. Keep the order you want users to see (see Select.md). |
| `value` | `string \| null` |  |  | The selected `value`; `null` means nothing is selected. Pair with `onChange`. |
| `defaultValue` | `string \| null` |  |  | The initially selected `value` when uncontrolled. |
| `onChange` | `((value: string \| null) => void)` |  |  | Called with the new `value`. |
| `description` | `ReactNode` |  |  | Helper text under the control. Linked with `aria-describedby`. |
| `descriptionTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the description: `success`, `warning`, `danger` or `accent` for a live check such as "Matches" or "Over by $5". The text carries the meaning; colour only reinforces it. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while the field is invalid and the error is displayed. See `Input`. |
| `placeholder` | `string` |  |  | Trigger text while nothing is selected. Default from messages: "Select an option". |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Control height: `sm` 32px, `md` 40px (default), `lg` 48px. |
| `fullWidth` | `boolean` |  | `false` | Take the free space of a flex row (an `Inline`): the field grows to fill it and can shrink below its content width. Off by default. In a block context the field already spans the width. |
| `className` | `string` |  |  | Class name for the field root. |
| `popoverClassName` | `string` |  |  | Class name for the popover that holds the options. |
| `messages` | `Partial<{ placeholder: string; } & { requiredMark: string; }>` |  |  | Message overrides for this instance: `placeholder`, `requiredMark`. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaSelectProps` (react-aria): `autoComplete`, `form`, `name`
- From `CollectionBase` (@react-types/shared): `disabledKeys`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SelectProps` (react-stately): `allowsEmptyCollection`, `defaultOpen`, `isOpen`, `onOpenChange`, `shouldCloseOnSelect`
- From `SlotProps` (react-aria-components): `slot`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Select: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `placeholder` | `Select an option` | Shown in the trigger while nothing is selected. |

#### Design tokens used

`--ds-accent`, `--ds-field-control-padding-inline`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-sm`, `--ds-select-popover-max-height`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tracking-caption`, `--ds-z-dropdown`

#### When to use

- A choice from 4 or more options.

#### When not to use

- 2 to 4 options that users compare: `RadioGroup` (or a segmented control).
- Typing to filter a long list: `ComboBox` (planned).
- Several selections: `CheckboxGroup`.

#### Props (key ones)

| Prop                                                      | Notes                                                                                               |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `label`, `description`, `descriptionTone`, `errorMessage` | As in `Input`.                                                                                      |
| `options`                                                 | `SelectOption[]` (`value`, `label`, `isDisabled`) or groups `{ id, label, options }`, mixed freely. |
| `value` / `defaultValue` / `onChange(value)`              | The selected option `value`; `null` means nothing selected. `onChange` receives `string \| null`.   |
| `placeholder`                                             | Trigger text while empty. Default from messages: "Select an option" (pt-BR "Selecione uma opção").  |
| `size`                                                    | `sm` 32px, `md` 40px (default), `lg` 48px.                                                          |
| `fullWidth`                                               | Take the free space of a flex row such as `Inline` (`flex: 1 1 auto`, can shrink). Off by default.  |
| `name`, `isRequired`, `isInvalid`, `isDisabled`           | Standard. `name` is submitted through the hidden `<select>`.                                        |
| `popoverClassName`, `className`, `ref`                    | Styling hooks; `ref` is the field root.                                                             |
| `messages`                                                | `placeholder`, `requiredMark`.                                                                      |

Option order is yours: the component never reorders. The product rule that lists are alphabetical by default applies to what you pass in: use `sortByText(options, (o) => o.label, locale)` from `loui-ds` (locale- and accent-aware) unless the order carries meaning (sizes, steps).

#### Anatomy and styling

- Trigger: the same box as `Input` (`--ds-line-control` border, focus ring, no hover fill), with a chevron.
- Popover: raised surface, `--ds-shadow-overlay`, radius `lg`, layer `--ds-z-dropdown`, at least as wide as the trigger, scrolls above `--ds-select-popover-max-height`.
- Option: `--ds-item-h` (36px) tall, hover and keyboard focus use `--ds-surface-hover`, the selected option shows a check (`Icon`), disabled options use the shared opacity.
- Section captions are mono, uppercase by CSS, in `--ds-text-2` (`--ds-text-3` fails contrast on the raised surface).

#### Accessibility and keyboard

| Key                                      | Behavior                                                       |
| ---------------------------------------- | -------------------------------------------------------------- |
| `Enter`, `Space`, `ArrowDown`, `ArrowUp` | Open the list and focus the selected (or first/last) option    |
| `ArrowDown` / `ArrowUp`                  | Next / previous enabled option                                 |
| `Home` / `End`                           | First / last option                                            |
| Letters                                  | Typeahead: focus the option starting with what you type        |
| `Enter` / `Space`                        | Select the focused option, close, focus returns to the trigger |
| `Escape`                                 | Close without changing; focus returns to the trigger           |
| Typing on the closed trigger             | Selects by prefix without opening                              |

The trigger is a `button` with `aria-haspopup="listbox"`, named by the label and described by the description and error. Options are `role="option"` with `aria-selected`; sections are `role="group"` named by their caption; disabled options have `aria-disabled`.

#### Example

```tsx
<Select
  label="Region"
  name="region"
  options={[
    { value: 'eu', label: 'EU: Frankfurt' },
    { value: 'us', label: 'US: Virginia' },
  ]}
  isRequired
  errorMessage="Choose a region."
/>
```

#### Related components

- Instead, see RadioGroup: 2 to 4 options that users compare: `RadioGroup` (or a segmented control).
- Instead, see CheckboxGroup: Several selections: `CheckboxGroup`.
- Renders: FieldMessages, Icon, Label

### Sheet

> A side panel that slides in from the inline-end edge, for viewing or editing one record
without leaving the list. Built on React Aria `Modal` and `Dialog`: focus is trapped and
restored, the page is inert and does not scroll, and `Escape` closes only the top-most layer
(a `Dialog` opened from a sheet closes first).

The header (title, mono meta, extra content, close button) is `--ds-topbar-h` tall; the body
scrolls; the footer stays at the bottom.

A side panel that slides in from the inline-end edge to view or edit one record without leaving the list. Built on React Aria `Modal` and `Dialog`. Generic: it lives in the core entry point.

- Handoff source: `components/erp/Sheet` (CMP-PAT-01).

- Import: `import { Sheet } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Sheet/Sheet.tsx`
- Stories (Storybook title `Components/Sheet`): Default, Open, Medium, Large, CloseButton, LongContent, NotPadded, LongTitle, WithDescription, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | yes |  | Heading of the sheet and its accessible name. One line; it is truncated with an ellipsis. |
| `meta` | `ReactNode` |  |  | Short mono text after the title, such as a record code ("ORD-1048"). |
| `headerExtra` | `ReactNode` |  |  | Extra header content after the meta, usually a `Badge` with the status. |
| `description` | `ReactNode` |  |  | Optional description linked to the sheet with `aria-describedby`. |
| `children` | `ReactNode \| ((options: SheetRenderOptions) => ReactNode)` |  |  | Body of the sheet; it scrolls when it is taller than the viewport. A function receives `close`. |
| `footer` | `ReactNode \| ((options: SheetRenderOptions) => ReactNode)` |  |  | Footer actions, aligned to the end: Cancel (secondary) then the primary action. A function receives `close`. The footer stays at the bottom while the body scrolls. |
| `footerStart` | `ReactNode \| ((options: SheetRenderOptions) => ReactNode)` |  |  | Footer content aligned to the start, for the destructive action ("Delete order"). |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'sm'` | Width: `sm` 440px (default), `md` 460px, `lg` 480px. Full width on small screens. |
| `padded` | `boolean` |  | `true` | Pads the body (24px, 18px between children). Turn off for a table or a full-bleed list. Default `true`. |
| `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | The element that opens the sheet. Optional: omit it and control the sheet with `isOpen`. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  |  | Initial open state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the sheet opens or closes. |
| `isDismissable` | `boolean` |  | `true` | Whether pressing the scrim closes the sheet. Default `true`. |
| `isKeyboardDismissDisabled` | `boolean` |  |  | Disables closing with `Escape`. Use it only while a request is running. |
| `messages` | `Partial<{ close: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `className` | `string` |  |  | Class name for the sheet panel. |
| `ref` | `Ref<HTMLElement>` |  |  | Ref to the sheet panel. |

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Sheet: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `close` | `Close panel` | Name of the close button in the Sheet header. |

#### Design tokens used

`--ds-duration`, `--ds-ease`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-heading`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-heading`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-strong`, `--ds-line-subtle`, `--ds-scrim`, `--ds-shadow-dialog`, `--ds-sheet-from`, `--ds-sheet-padding`, `--ds-sheet-width`, `--ds-sheet-width-lg`, `--ds-sheet-width-md`, `--ds-sheet-width-sm`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-topbar-h`, `--ds-weight-semibold`

#### When to use

- A record's details or edit form next to the list it came from.
- Filters or settings with a footer of actions.

#### When not to use

- A short confirmation or a small form: use `Dialog`.
- A hint or a few controls on a trigger: use `Popover`.
- Page-level navigation: use `Sidebar`.

#### Anatomy

```
DialogTrigger
  trigger
  ModalOverlay       --ds-scrim, z sheet
    Modal            surface, strong line at the start edge, dialog shadow, width sm | md | lg
      Dialog         role=dialog, aria-labelledby = title
        header       --ds-topbar-h tall: title (ellipsis) · meta (mono) · headerExtra · close IconButton
        body         scrolls; padded (24px) or not
        footer       sticky: footerStart (destructive) ... footer (Cancel + primary)
```

#### Initial focus

React Aria moves focus into the sheet on open: to the first element with `autoFocus` if there is one, otherwise to the dialog itself. This holds for every way of opening it (keyboard or pointer on the trigger, `element.click()` from code, and a controlled sheet without a trigger whose `isOpen` is set from an effect or a timer); regression tests cover each one (GAP-031). If `autoFocus` seems lost in your own tests, the cause is the test environment, not `Sheet`: wait for the dialog to be visible before asserting focus (the field is focused after the overlay mounts).

#### Accessibility

- Same overlay contract as `Dialog`: focus trapped and restored, `inert` page, scroll lock, `Escape` closes only the top layer (a `Dialog` opened inside the sheet closes first; tested in `Dialog.test.tsx`).
- Named by the title through `aria-labelledby`, so a non-string title works (the handoff only labeled string titles).
- The close button is an `IconButton` named from messages. The handoff set `title="Close (Esc)"`.
- Slide-in is a 150 ms transform and the scrim fades; both are removed under `prefers-reduced-motion`. The slide direction follows the writing direction (`:dir(rtl)`).
- The panel is `Modal` content inside the overlay, so it stacks above the scrim without a second z-index.
- See the Dialog doc ("Layers") for popovers opened from inside the sheet.
- **Exit animation.** The sheet stays mounted for the 150 ms slide-out. It keeps rendering the props of its last open render during that time, so you can clear the state that feeds it (`setRecord(null)`) in the same update that closes it and the panel will not animate out empty (no blank fields or title). Reopening shows the new content at once. Under `prefers-reduced-motion` there is no animation, so it leaves the DOM immediately (tested). If the tab is hidden the browser does not run animations and React Aria unmounts the sheet only once the tab is visible again.

Controlled use without a `trigger` renders the overlay directly, without a `DialogTrigger`, so opening the sheet logs nothing to the console (GAP-022). Focus still returns to the element focused before it opened.

#### Content rules

- Title: the record type or name, sentence case. Meta: its code, as data.
- Footer: destructive action at the start ("Delete order"); Cancel then the primary action at the end ("Save order"). Deleting still goes through a `ConfirmDialog`.

#### Examples

```tsx
<Sheet
  trigger={<Button>View order</Button>}
  title="Order"
  meta="ORD-1048"
  headerExtra={<Badge tone="success">Shipped</Badge>}
  footerStart={<Button variant="danger">Delete order</Button>}
  footer={({ close }) => (
    <>
      <Button onPress={close}>Cancel</Button>
      <Button variant="primary" onPress={save}>
        Save order
      </Button>
    </>
  )}
>
  <Input label="Customer" />
</Sheet>
```

#### Related components

- Instead, see Dialog: A short confirmation or a small form: use `Dialog`.
- Instead, see Popover: A hint or a few controls on a trigger: use `Popover`.
- Instead, see Sidebar: Page-level navigation: use `Sidebar`.
- Renders: IconButton

### ShortcutsHelp

> A dialog that lists the registered keyboard shortcuts (`useHotkeys` with a `description`),
grouped by their `group`, one table per group with the keys drawn by `Kbd`. Opens with `?` by
default. Place it once, anywhere under the app, and it stays in sync with what is mounted.

A dialog that lists the keyboard shortcuts registered on the page, one table per group, with the keys drawn by `Kbd`. It opens with `?` by default.

- Import: `import { ShortcutsHelp } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/ShortcutsHelp/ShortcutsHelp.tsx`
- Stories (Storybook title `Components/ShortcutsHelp`): Default, Open, Empty, PortugueseBrazil

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `((isOpen: boolean) => void)` |  |  | Called when the dialog opens (from the hotkey) or closes. |
| `hotkey` | `string \| false` |  | `?` | The shortcut that opens the dialog, registered in the hotkey registry. Default `'?'`. It does not fire while an input has focus, so typing a question mark still works. Pass `false` to open the dialog only through `isOpen`. |
| `includeInactive` | `boolean` |  | `false` | Also list shortcuts whose scope is not active right now. Default `false`. |
| `messages` | `Partial<{ title: string; description: string; ungrouped: string; empty: string; close: string; action: string; keys: string; openDescription: string; openGroup: string; }>` |  |  | Message overrides for this instance. |
| `className` | `string` |  |  | Class name for the dialog panel. |

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ ShortcutsHelp: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `title` | `Keyboard shortcuts` | Title of the dialog. |
| `description` | `Shortcuts that work on this page.` | Description under the title. |
| `ungrouped` | `Other` | Heading for shortcuts that have no `group`. |
| `empty` | `No keyboard shortcuts on this page.` | Shown when no shortcut is registered. |
| `close` | `Close` | Label of the button that closes the dialog. |
| `action` | `Action` | Column header: what the shortcut does. |
| `keys` | `Shortcut` | Column header: the keys. |
| `openDescription` | `Show keyboard shortcuts` | Description of the shortcut that opens the dialog. |
| `openGroup` | `General` | Group of the shortcut that opens the dialog. |

#### Design tokens used

`--ds-font-mono`, `--ds-fs-caption`, `--ds-lh-caption`, `--ds-line-subtle`, `--ds-space-1`, `--ds-space-2`, `--ds-space-4`, `--ds-text`, `--ds-text-2`, `--ds-tracking-caption`, `--ds-weight-regular`

#### When to use

- Once per app (or per module), next to the `CommandPalette`, so users can learn the shortcuts without leaving the page.

#### When not to use

- To register shortcuts: use `useHotkeys`. This only lists what is registered.
- As the only way to find a command: the `CommandPalette` also searches by name.

#### Anatomy

```
Dialog "Keyboard shortcuts"  (size md, Close button)
  table  caption = group
    tr   th[scope=row] description · td Kbd keys
```

#### Behavior

- Lists shortcuts that have a `description` (`useHotkeys`). Groups are sorted with the locale; shortcuts without a `group` go under "Other", last. Rows are sorted by description.
- Updates while it is open: shortcuts that mount or unmount appear or disappear.
- It lists itself ("Show keyboard shortcuts") and the `CommandPalette` shortcut.
- While it is open, page shortcuts do not fire.

#### Accessibility

- A modal `dialog` named "Keyboard shortcuts" with a description; focus is trapped and returns on close.
- Each group is a real `<table>` named by its `<caption>`; the description is the row header, the keys are the cell. The column headers exist for screen readers and are visually hidden.
- Keys use `Kbd`, with spoken names for symbols.
- `Escape` and the Close button close it.

#### Content rules

- Descriptions are verb plus object in sentence case ("Create order"), as in the command palette.
- Messages: `title`, `description`, `ungrouped`, `empty`, `close`, `action`, `keys`, `openDescription`, `openGroup`. English and pt-BR ship.

#### Examples

```tsx
<HotkeyProvider>
  <App />
  <ShortcutsHelp />
</HotkeyProvider>
```

#### Related components

- Instead, see CommandPalette: As the only way to find a command: the `CommandPalette` also searches by name.
- Renders: Button, Dialog, Kbd, VisuallyHidden

### Sidebar

> The app sidebar: a workspace block, navigation sections, an optional status card, a footer
slot and the signed-in user. It is an `aside` landmark; each section is a separate `nav`
landmark named by its caption. It is `--ds-sidebar-w` wide and scrolls on its own when it is
taller than its container, so give the parent a fixed height.

Reading order and focus order follow the visual order: sections top to bottom, then the
footer. Collapsing or an off-canvas mobile variant is not part of this component.

The app sidebar: workspace block, navigation sections, optional status card, footer slot and the signed-in user. It is an `aside` landmark and each section is its own `nav`.

- Handoff source: `components/layout/Sidebar.jsx` (TODO `CMP-LAY-01`).

- Import: `import { Sidebar } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Sidebar/Sidebar.tsx`
- Stories (Storybook title `Components/Sidebar`): Default, Complete, StatusTones, StatusNeutral, WithoutCaptions, FocusOrder, Controlled, ManyItems, LongText, Portuguese, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `workspace` | `SidebarWorkspace` | yes |  | The workspace block at the top. |
| `sections` | `readonly SidebarSection[]` | yes |  | Navigation groups. Each one is its own labelled `nav` landmark. |
| `value` | `string` |  |  | `value` of the active item (gets `aria-current="page"`). |
| `onChange` | `(value: string) => void` |  |  | Called with the `value` of the item the user pressed. |
| `status` | `SidebarStatus` |  |  | Optional status card above the footer. |
| `footer` | `ReactNode` |  |  | Free slot above the user block, for example a help link or an upgrade note. |
| `user` | `SidebarUser` |  |  | The signed-in user, at the bottom. |
| `aria-label` | `string` |  |  | Overrides the accessible name of the landmark (default "Sidebar" from the catalog). |
| `messages` | `Partial<{ label: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Sidebar: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `label` | `Sidebar` | Accessible name of the sidebar landmark. |

#### Design tokens used

`--ds-bg`, `--ds-danger`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-line`, `--ds-line-subtle`, `--ds-nav-item-padding-inline`, `--ds-primary-bg`, `--ds-primary-fg`, `--ds-radius-lg`, `--ds-radius-md`, `--ds-radius-pill`, `--ds-sidebar-gap`, `--ds-sidebar-padding-block`, `--ds-sidebar-padding-inline`, `--ds-sidebar-status-dot-size`, `--ds-sidebar-w`, `--ds-sidebar-workspace-mark-size`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-success`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tracking-caption`, `--ds-warning`, `--ds-weight-medium`, `--ds-weight-semibold`

#### When to use

- The persistent primary navigation of an app shell, next to the content and below a `SkipLink`.

#### When not to use

- For in-page navigation or a table of contents.
- For mobile off-canvas navigation: collapsing and responsive behavior are not part of this component yet.

#### Anatomy

```
aside[aria-label="Sidebar"]         (--ds-sidebar-w wide, scrolls on its own)
  workspace                         (initial tile, name, subtitle)
  nav[aria-labelledby=caption]      (one per section)
    caption                         (mono, uppercase by CSS)
    ul > li > NavItem
  bottom
    status                          (role=status: dot + title + meta/value)
    footer                          (slot)
    user                            (Avatar + name + role)
```

#### Layout

- Width is `--ds-sidebar-w` (240px). The handoff's `width` prop and 248px default are dropped; there is one width in the system.
- The sidebar uses `max-block-size: 100%` and `overflow-y: auto`: give its parent a definite height (for example a full-height flex row) and it scrolls on its own while the content scrolls separately. The status, footer and user stay at the bottom when there is room.

#### Behavior change

The status dot is now grey (`neutral`) when `tone` is omitted; it used to default to green. Pass `tone: 'success'` to keep the green dot.

#### Accessibility

- Landmarks: `aside` (complementary) named "Sidebar", and one `nav` per section named by its visible caption (or by `label` when there is no caption). Names are unique, so landmark lists are meaningful.
- Items are in a `ul`, so screen readers announce "list, 5 items".
- Focus order follows the visual order: sections top to bottom, then the footer, then nothing in the status or user blocks (they are text).
- The status block is `role="status"` (polite live region): a change from "Synced" to "Sync failed" is announced. The dot is `aria-hidden`; the title says the status in words.
- The workspace tile and the user avatar are decorative because the names are shown next to them.
- The active item has `aria-current="page"` (see `NavItem`).

#### Content rules

- Section captions are written in sentence case ("Work"); the CSS makes them uppercase mono.
- Status titles say the state: "All systems operational", not "OK".

#### Examples

```tsx
<Sidebar
  workspace={{ name: 'Northwind', subtitle: 'Production' }}
  value="orders"
  onChange={setView}
  sections={[
    {
      id: 'work',
      title: 'Work',
      items: [
        {
          value: 'orders',
          label: 'Orders',
          href: '/orders',
          icon: StarIcon,
          count: 3,
          countLabel: '3 pending',
          countTone: 'warning',
        },
        { value: 'customers', label: 'Customers', href: '/customers' },
      ],
    },
  ]}
  status={{ title: 'All systems operational', meta: 'Last sync', value: '2 min ago' }}
  user={{ name: 'Ana Souza', role: 'Owner' }}
/>
```

#### Related components

- Renders: Avatar, NavItem

### Skeleton

> A placeholder block in the shape of content that is still loading. It is always hidden
from assistive technology: mark the region that is loading with `aria-busy="true"` and
remove the attribute (and the skeletons) when the content arrives.

The `width` and `height` props are the only dynamic values in the library that reach the
DOM as custom properties on `style`, because arbitrary sizes cannot be tokens.

A placeholder in the shape of content that is still loading: a block, a circle, or a few text lines.

- Import: `import { Skeleton } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Skeleton/Skeleton.tsx`
- Stories (Storybook title `Components/Skeleton`): Default, Block, Circle, Lines, SingleLine, Pill, BusyRegion, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `width` | `string \| number` |  |  | Width: a number in px or any CSS length. Default `100%`. Ignored when `circle` is set (the circle is as wide as it is tall). |
| `height` | `string \| number` |  |  | Height of the block, or of each line: a number in px or any CSS length. Default `12px` (`--ds-skeleton-height`). |
| `circle` | `boolean` |  | `false` | Renders a circle, for an avatar. The diameter is `height`. |
| `lines` | `number` |  |  | Renders this many text lines; the last one is shorter. Takes precedence over `circle`. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-radius-pill`, `--ds-radius-sm`, `--ds-skeleton-height`, `--ds-skeleton-pulse-duration`, `--ds-skeleton-pulse-opacity`, `--ds-space-2`, `--ds-surface-hover`

#### When to use

- The layout of the content is known (a list of rows, a card, an avatar next to text) and the wait is short.
- Keep the page from jumping when the data arrives.

#### When not to use

- For an action in progress (saving, sending): use `Spinner` or a loading `Button`.
- For a measurable task: use `Progress`.
- When there is nothing to show after loading: use `EmptyState`.

#### Anatomy

```
span[aria-hidden="true"]  block | circle
span[aria-hidden="true"]  lines → n × span (last one is 60% wide)
```

#### Accessibility

- Every skeleton is `aria-hidden="true"`: it is decoration and has no text.
- **Mark the region that is loading with `aria-busy="true"`** and remove it, together with the skeletons, when the content arrives. This tells assistive technology the region is being updated. A skeleton on its own does not do this.
- If the wait is long, also expose a polite status ("Loading orders") near the region; skeletons never announce it.
- The pulse (opacity only) is switched off under `prefers-reduced-motion`. In forced-colors mode the placeholder gets a border because background colors are dropped.

#### Content rules

- Match the final layout: the same number of rows and similar widths, so nothing moves when the data arrives.
- Show at most one screenful of placeholders.

#### Examples

```tsx
<section aria-busy={isLoading} aria-label="Recent orders">
  {isLoading ? (
    <>
      <Skeleton circle height={28} />
      <Skeleton lines={3} />
    </>
  ) : (
    <OrderList orders={orders} />
  )}
</section>
```

#### Related components

- Instead, see Spinner: For an action in progress (saving, sending): use `Spinner` or a loading `Button`.
- Instead, see Button: For an action in progress (saving, sending): use `Spinner` or a loading `Button`.
- Instead, see Progress: For a measurable task: use `Progress`.
- Instead, see EmptyState: When there is nothing to show after loading: use `EmptyState`.
- Used by: DataTable

### SkipLink

> A link that is invisible until a keyboard user focuses it, then jumps past the repeated
navigation to the main content (WCAG 2.4.1 Bypass Blocks). Put it as the very first
focusable element of the page, before the sidebar and the top bar.

It moves focus itself instead of relying on the hash navigation, so it also works with hash
based routers and with a target that is not focusable by default.

A link that stays invisible until a keyboard user focuses it, then jumps past the repeated navigation to the main content (WCAG 2.4.1 Bypass Blocks).

- Source: TODO `BASE-002` (there was no handoff component).

- Import: `import { SkipLink } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/SkipLink/SkipLink.tsx`
- Stories (Storybook title `Components/SkipLink`): Default, JumpsToMain, CustomTarget, Portuguese, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `targetId` | `string` |  | `main` | Id of the element to jump to, without the `#`. Default `main`. The element should be the page's `<main>` (or its first heading); it does not need a `tabindex`. |
| `children` | `ReactNode` |  |  | Link text. Defaults to "Skip to main content" from the message catalog. |
| `messages` | `Partial<{ label: string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ SkipLink: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `label` | `Skip to main content` | Default text of the skip link. |

#### Design tokens used

`--ds-focus-ring`, `--ds-font-sans`, `--ds-fs-small`, `--ds-lh-small`, `--ds-primary-bg`, `--ds-primary-fg`, `--ds-radius-md`, `--ds-skip-link-z-index`, `--ds-space-2`, `--ds-space-4`, `--ds-weight-medium`

#### When to use

- Once per page, as the first focusable element, before the sidebar and the top bar.

#### When not to use

- As a general "go to section" link: use `Link`.

#### Behavior

- Hidden with the same technique as `VisuallyHidden` (1px, clipped), so it is still focusable. On focus it becomes a primary-colored button at the top start corner, above everything (`--ds-skip-link-z-index`).
- On activation it focuses the target element itself and cancels the hash navigation. This works with hash-based routers and with targets that are not focusable (a temporary `tabindex="-1"` is added and removed on blur; an existing `tabindex` is kept). If the target does not exist, the browser's default behavior runs.
- Give the target `id="main"`; put it on `<main>`.

#### Accessibility

- It is a real link, so it appears in link lists and works with `Enter`.
- Visible focus with the accent ring; forced colors use `Highlight`.
- The text says where it goes. Do not shorten it to "Skip".

#### Content rules

- "Skip to main content" (default). For a second link use the destination: "Skip to the results".

#### Examples

```tsx
<>
  <SkipLink />
  <Sidebar … />
  <main id="main">…</main>
</>
```

#### `.ds-sr-only` (BASE-002)

The TODO asks for a `.ds-sr-only` utility class too. It belongs in `src/styles/base.css` (`@layer utilities`), a shared file this component does not own. The rule to add is the same as `.root` of `VisuallyHidden` (absolute, 1px, `clip-path: inset(50%)`, no overflow).

#### Related components

- Instead, see Link: As a general "go to section" link: use `Link`.
- Used by: AppShell, AppShellNavToggle

### Slider

> A single-value slider built on React Aria `Slider`: a labelled track with one thumb that is a
real `<input type="range">`, so keyboard, pointer, touch and form submission (`name`) work
natively. Keys: arrows step by `step`, `PageUp`/`PageDown` move by a larger step (10% of the
range, at least `step`), `Home`/`End` jump to the limits.

Range selection with two thumbs is not part of this component yet.

Single-value slider: a labelled track with one thumb and a formatted value. Built on React Aria `Slider` (`SliderTrack`, `SliderFill`, `SliderThumb`, `SliderOutput`). The thumb is a real `<input type="range">`, so keyboard, pointer, touch and form submission work natively. Task: CMP-INP-04.

- Import: `import { Slider } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Slider/Slider.tsx`
- Stories (Storybook title `Components/Slider`): Default, KeyboardContract, Percent, WithDescription, SteppedByTen, WithoutValue, Disabled, AriaLabelOnly, Controlled, LongLabel

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | `number` |  |  | The value when controlled. Pair with `onChange`. |
| `defaultValue` | `number` |  |  | The initial value when uncontrolled. Defaults to `minValue`. |
| `onChange` | `((value: number) => void)` |  |  | Called while the value changes (each key press, each pointer move). |
| `onChangeEnd` | `((value: number) => void)` |  |  | Called once when a drag ends or a key press is committed. Use it to save. |
| `formatOptions` | `NumberFormatOptions` |  |  | Formats the value shown next to the label and spoken to screen readers (`aria-valuetext`): `{ style: 'percent' }`, `{ style: 'unit', unit: 'kilometer' }`, ... Uses the locale of `DSProvider`. |
| `name` | `string` |  |  | Name for form submission; the form receives the number. |
| `showValue` | `boolean` |  | `true` | Shows the formatted value (mono) on the right of the label. Default `true`. |
| `description` | `ReactNode` |  |  | Helper text under the track, linked with `aria-describedby`. |
| `className` | `string` |  |  | Class name for the field root. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `SliderProps` (react-stately): `isDisabled`, `maxValue`, `minValue`, `step`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-fs-label`, `--ds-lh-label`, `--ds-line-control`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-pill`, `--ds-slider-thumb-dot-size`, `--ds-slider-thumb-size`, `--ds-slider-track-height`, `--ds-space-3`, `--ds-text`, `--ds-text-2`, `--ds-text-3`

#### When to use

- Picking a number from a bounded range where the approximate value matters more than the exact one (discount, opacity, threshold).

#### When not to use

- An exact quantity: `NumberField`. Money: `CurrencyInput`.
- A range with two ends: not supported yet (two-thumb range is P2).
- Fewer than about five discrete choices: `RadioGroup` or a segmented control.

#### Anatomy

- Header: `Label` (left) and the formatted value in mono (right, `SliderOutput`).
- Track: rail (`--ds-line-control`, 3:1 against the page), fill from the start to the thumb (`--ds-accent`), thumb.
- Thumb: a 24px hit area (`--ds-slider-thumb-size`, WCAG 2.5.8) with a 16px visible knob; the focus ring follows the hit area.
- Optional description under the track.

#### Props (key ones)

| Prop                                         | Notes                                                                                            |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `label` / `aria-label` / `aria-labelledby`   | One is required (types and a development warning).                                               |
| `value` / `defaultValue` / `onChange(value)` | Controlled / uncontrolled, RAC naming. `onChange` fires on every step; `onChangeEnd` on commit.  |
| `minValue`, `maxValue`, `step`               | Defaults `0`, `100`, `1`.                                                                        |
| `formatOptions`                              | `Intl.NumberFormat` options for the shown value and `aria-valuetext`, locale from `DSProvider`.  |
| `showValue`                                  | Default `true`.                                                                                  |
| `description`                                | Helper text, linked with `aria-describedby` on the thumb.                                        |
| `name`                                       | Submitted with the form as the number.                                                           |
| `isDisabled`                                 | Dimmed track; the text drops to `--ds-text-3` instead of using opacity so it keeps its contrast. |

#### Accessibility and keyboard

| Key                       | Behavior                                                                 |
| ------------------------- | ------------------------------------------------------------------------ |
| `ArrowRight` / `ArrowUp`  | Increase by `step`                                                       |
| `ArrowLeft` / `ArrowDown` | Decrease by `step`                                                       |
| `PageUp` / `PageDown`     | Increase / decrease by a larger step (10% of the range, at least `step`) |
| `Home` / `End`            | Minimum / maximum                                                        |

The thumb is `input[type=range]`, named by the label, with `aria-valuetext` from `formatOptions`. The value text is not a live region (RAC announces changes through the input).

#### Content rules

Label with the thing being set ("Discount"), not an instruction. Put the unit in `formatOptions` (`{ style: 'percent' }`, `{ style: 'unit', unit: 'kilometer' }`), never in the label.

#### Example

```tsx
<Slider
  label="Discount"
  name="discount"
  defaultValue={10}
  maxValue={50}
  formatOptions={{ style: 'unit', unit: 'percent' }}
/>
```

#### Related components

- Instead, see NumberField: An exact quantity: `NumberField`. Money: `CurrencyInput`.
- Instead, see CurrencyInput: An exact quantity: `NumberField`. Money: `CurrencyInput`.
- Instead, see RadioGroup: Fewer than about five discrete choices: `RadioGroup` or a segmented control.
- Renders: Label

### SourceList

> The numbered list of sources an answer is based on. Each source is a list item that
`Citation` markers jump to; the title is a link when the source has a `url`.

Source numbers are the position in `sources`: keep the order stable while the answer streams,
and append new sources at the end.

The numbered list of sources an answer is based on (`SourceList`) and the inline markers that point to it (`Citation`). Import both from `loui-ds/patterns`.

- Import: `import { SourceList } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/SourceList/SourceList.tsx`
- Stories (Storybook title `Patterns/SourceList`): Default, LongText, RightToLeft, WithCitations

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | yes |  | Id of the list. Required: citations use it to find their source. |
| `sources` | `readonly Source[]` | yes |  | The sources, in citation order. The first is source 1. |
| `title` | `string` |  |  | Heading text. Defaults to "Sources". |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `3` | Heading level of the title (`h1` to `h6`). Default `3`. |
| `messages` | `Partial<{ title: string; citation: (number: number, title: string) => string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ SourceList: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `title` | `Sources` | Default heading of the source list. |
| `citation(number: number, title: string)` | `Source 2: {title}` | Accessible name of a citation marker: "Source 2: Title". |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-citation-size`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-line-control`, `--ds-radius-sm`, `--ds-source-list-gap`, `--ds-source-list-indent`, `--ds-source-list-padding`, `--ds-space-1`, `--ds-space-2`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`, `--ds-weight-semibold`

#### When to use

- An assistant answer that rests on documents, pages or records, and the owner should be able to check them.

#### When not to use

- Footnotes in long-form documents: use plain links.
- A list of results the user searched for: use a table or a list of cards.

#### Anatomy

```
p            ... a claim [2] ...        Citation: <a href="#s-source-b" aria-label="Source 2: Title">2</a>
section      named by its heading ("Sources")
  ol
    li       tabIndex=-1 (focus target)    title (link when it has a url) · domain (mono) · snippet
```

#### Accessibility

- A citation is a real link (`href="#..."`) named "Source 2: Title"; the visible text is the number, which the name contains.
- Activating it moves focus to the matching list item and scrolls it into view. It does not change the URL hash, so it does not fight your router. Without JavaScript the hash link still works.
- Source titles with a `url` are links that open in a new tab (with the external-link icon and a screen-reader note).
- The marker is 24 px square (WCAG 2.5.8).

#### Content rules

- Keep source order stable while the answer streams; append new sources at the end, so numbers already shown never change.
- Titles say what the page is, not "Click here". Snippets are short, plain text.

#### Example

```tsx
<p>
  Orders move through four statuses
  <Citation number={1} title="Order lifecycle" listId="answer-1" sourceId="lifecycle" />.
</p>
<SourceList
  id="answer-1"
  sources={[{ id: 'lifecycle', title: 'Order lifecycle', url: 'https://example.com/orders' }]}
/>
```

#### Related components

- Renders: Link

### Sparkline

> A tiny trend line (or area) without axes, drawn in SVG, for tables, stat cards and lists. It
shows the shape of a series, not its values: put the current number next to it.

It is an image with a required text summary (`aria-label`), or `decorative` when the same
information is written next to it. It is not interactive and not focusable. The vertical
range is the data's own minimum to maximum, so a small change on a large number still
shows; use `Chart` when readers need axes, values per point or zero as a reference.

A tiny trend line (or area) without axes, drawn in SVG, for tables, stat cards and lists. It shows the shape of a series, not its values: put the current number next to it.

- TODO `GAP-007`.

- Import: `import { Sparkline } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Sparkline/Sparkline.tsx`
- Stories (Storybook title `Components/Sparkline`): Default, Area, Accent, Success, Warning, Danger, LastValue, MinMax, Larger, IncludeZero, FlatSeries, WithGaps, SinglePoint, Empty, Decorative, NarrowContainer, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | `readonly (number \| null \| undefined)[]` | yes |  | The values in display order, usually time. `null`, `undefined` and non-finite numbers are gaps: the line breaks there. An empty array draws nothing. |
| `variant` | `'area' \| 'line'` |  | `'line'` | `line` (default) or `area`, which also fills softly under the line. |
| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  | `'neutral'` | Color of the line: `neutral` (default), `accent`, `success`, `warning` or `danger`. Color is never the only signal: say what the trend means in the accessible name or next to it. |
| `width` | `number` |  | `96` | Width in px (user units). Shrinks to fit a narrower container. Default 96. |
| `height` | `number` |  | `24` | Height in px (user units). Default 24. |
| `showLast` | `boolean` |  | `false` | Draws a solid dot on the last value, the current one. |
| `showMinMax` | `boolean` |  | `false` | Draws hollow markers on the lowest and the highest value (omitted when all values are equal). |
| `includeZero` | `boolean` |  | `false` | Keeps 0 in the vertical range. Default: the range is the data's own minimum to maximum. |
| `className` | `string` |  |  |  |
| `aria-label` | `string` |  |  | Summary of the trend, required unless `decorative` or `aria-labelledby`: "Revenue, last 7 days: up 12%". |
| `aria-labelledby` | `string` |  |  | Id of the element that summarizes the trend. |
| `decorative` | `boolean` |  | `false` | Hides the sparkline from assistive technology. Use it only when the same information is in text next to it (a number and "+12%"): the line alone is never the only source. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `area`, `line`
- `tone`: `neutral`, `accent`, `success`, `warning`, `danger`

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-danger`, `--ds-sparkline-area-opacity`, `--ds-sparkline-color`, `--ds-sparkline-dot-r`, `--ds-sparkline-marker-r`, `--ds-sparkline-stroke-w`, `--ds-success`, `--ds-text-2`, `--ds-warning`

#### When to use

- Next to a number in a `StatCard`, a table row or a list item, to show the recent trend.
- When the shape matters more than exact values.

#### When not to use

- When readers need axes, values per point or keyboard exploration: use `Chart`.
- To show a quantity within a range: use `Meter` or `DonutMeter`.
- As the only place a number appears: the sparkline is a summary, not a source.

#### Anatomy

```
svg[role=img] aria-label            (or aria-hidden when decorative)
  path.area                         (variant="area" only)
  path.line                         (one per run of values, a gap starts a new one)
  circle.marker[min|max]            (showMinMax: hollow rings)
  circle.last                       (showLast: solid dot)
```

#### Accessibility

- It is an `img` with a required text summary: say what a sighted reader sees, with the numbers that matter ("Orders, last 7 days: up 12%"). Use `decorative` only when that text is already next to the sparkline.
- It is not focusable and not interactive; there are no tooltips. For exploration use `Chart`.
- Color is never the only signal: tone changes the line color, the trend must be in the name or next to it. Min and max are hollow rings and the last value is a solid dot, so they differ by shape.
- Line, markers and area use `--ds-text-2` or a signal color (3:1 or better on the dark surfaces). Forced colors: everything is drawn in `CanvasText`.
- Under 200% zoom and in narrow containers it shrinks with the container.

#### Content rules

- Summaries are one short sentence in sentence case with the period and the direction: "Revenue, last 30 days: up 8%".

#### Differences from `Chart`

The vertical range is the data's own minimum to maximum, not a "nice" axis that includes zero (`niceScale`), because a trend line on `98, 100, 102` must not be flattened. For that reason `niceScale` and the `Chart` layout helpers are not reused; the geometry lives in `sparklineLayout.ts` and is unit tested.

#### Examples

```tsx
<Sparkline data={daily} aria-label="Orders, last 7 days: up 12%" tone="success" showLast />

<p>
  Orders 1,248 <Sparkline data={daily} decorative /> +12%
</p>
```

#### Related components

- Instead, see Chart: When readers need axes, values per point or keyboard exploration: use `Chart`.
- Instead, see Meter: To show a quantity within a range: use `Meter` or `DonutMeter`.
- Instead, see DonutMeter: To show a quantity within a range: use `Meter` or `DonutMeter`.

### Spinner

> An indeterminate loading ring that inherits the text color.

It is a `progressbar` without a value, not a live region, so many spinners on a screen do
not each interrupt a screen reader. For large areas prefer `Skeleton`. Under
`prefers-reduced-motion` the ring is static.

An indeterminate loading ring that inherits the text color. Small, quiet, and not a live region.

- Handoff source: `components/feedback/Spinner` (CMP-FBK-06).
- Built on: a plain element with `role="progressbar"`. A pending `Button` wires it as its busy label through React Aria.

- Import: `import { Spinner } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Spinner/Spinner.tsx`
- Stories (Storybook title `Components/Spinner`): Default, Sizes, WithLabel, DecorativeWithText, InheritsColor

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Size token: `sm` 14px, `md` 18px (default), `lg` 20px. |
| `label` | `string` |  |  | Accessible name. Defaults to the "Loading" message. Say what is loading when it helps ("Loading orders"). |
| `decorative` | `boolean` |  | `false` | Hide the spinner from assistive technology. Use it only when the surrounding UI already announces the busy state (visible status text, `aria-busy` region). Not needed inside a pending `Button`, which wires the spinner as its busy label. |
| `messages` | `Partial<{ loading: string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Spinner: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `loading` | `Loading` |  |

#### Design tokens used

`--ds-icon-lg`, `--ds-icon-md`, `--ds-icon-sm`, `--ds-radius-pill`, `--ds-spinner-duration`, `--ds-spinner-stroke-width`

#### When to use

- Inside a pending `Button` (`isPending`), which renders it for you.
- Next to a short status text for a small, bounded wait ("Saving changes").
- A single small area that is loading and has no better placeholder.

#### When not to use

- For large areas or page loads: use `Skeleton` so the layout does not jump.
- When you know the progress: use `Progress` with a value.
- As a decoration. It means "busy", so remove it when the work ends.

#### Anatomy

One element: a ring with an open top edge. Size comes from `--ds-icon-sm|md|lg`, thickness from `--ds-spinner-stroke-width`, rotation time from `--ds-spinner-duration`.

#### Accessibility

- `role="progressbar"` with no value (indeterminate) and an accessible name. It is **not** `role="status"` or `aria-live`: a screen reader does not announce every spinner when it mounts. One announcement strategy per screen: the button (`Button` announces pending and done) or a single status region you control.
- Decorative mode: `aria-hidden="true"`. Pair it with visible status text in a `role="status"` region, as in the `DecorativeWithText` story.
- Reduced motion: under `prefers-reduced-motion: reduce` the ring does not rotate. It stays as a static open ring; the accessible name and the busy control state carry the meaning.
- Forced colors: the ring is drawn with `currentColor` borders, which follow the system text color.
- Color: inherits the text color, so it needs no extra contrast treatment beyond its container's.

#### Content rules

- The name is a short noun phrase in sentence case: "Loading", "Loading orders". No ellipsis, no exclamation mark.
- Default text comes from the `Spinner` message catalog (`en`: "Loading", `pt-BR`: "Carregando"). Override it per instance or through `DSProvider messages={{ Spinner: { loading: '...' } }}`.

#### Examples

```tsx
<Spinner />
<Spinner label="Loading orders" size="lg" />

<p role="status">
  <Spinner decorative size="sm" /> Saving changes
</p>
```

#### Related components

- Instead, see Skeleton: For large areas or page loads: use `Skeleton` so the layout does not jump.
- Instead, see Progress: When you know the progress: use `Progress` with a value.
- Used by: Button, ChatPanel, Combobox, MatrixGrid, ToolCallStep

### SplitLayout

> A main column with a fixed-width side panel beside it: an editor with a chat, a list with a
summary. The side panel can stay in view while the main content scrolls, and stacks under the
main content when the layout is narrow. Use `Grid` for equal columns, and the `AppShell`
`detail` prop for the detail pane of a whole screen.

The main content comes first in the DOM (reading and Tab order); `asidePosition="start"` only
changes where it is drawn.

A main column with a fixed-width side panel beside it. The side panel can stay in view while the main content scrolls, and it stacks under the main content when the layout is narrow.

- Import: `import { SplitLayout } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/SplitLayout/SplitLayout.tsx`
- Stories (Storybook title `Layout/SplitLayout`): End, Start, SmallAside, LargeAside, WithoutLandmark, Sticky, CollapsedNarrowContainer, CollapseNever, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` |  |  | The main content. It takes the free width and can shrink, so long words wrap instead of widening the page. |
| `aside` | `ReactNode` |  |  | The side panel: a chat, a filter, a summary. Without it, only the main content renders. |
| `asideLabel` | `string` |  |  | Accessible name of the side panel. With it the panel is an `aside` landmark; without it, a plain `div`, because a layout primitive must not add unnamed landmarks. |
| `asideWidth` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Width of the side panel: `sm` 280px, `md` 360px (default, same as the `AppShell` detail pane), `lg` 480px. |
| `asidePosition` | `'start' \| 'end'` |  | `'end'` | Side of the side panel in the reading direction: `end` (default) or `start`. It is logical, so it flips in right-to-left text. The DOM order stays main first. |
| `gap` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 12 \| 16 \| '1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '8' \| '12' \| '16'` |  | `6` | Space between the main content and the aside, as a key of the space scale. Default `6` (24px). |
| `sticky` | `boolean` |  | `false` | Keeps the aside in view while the main content scrolls (`position: sticky`). The aside is limited to the height of the viewport and scrolls on its own, and becomes a keyboard stop while it scrolls. Sticky only works beside the main content: it is off while collapsed. |
| `collapseBelow` | `'sm' \| 'md' \| 'lg' \| 'never'` |  | `'md'` | Width of the layout (its own width, measured with a container query) under which the aside stacks under the main content: `sm` 480px, `md` 768px (default), `lg` 1024px, or `never`. The widths are the `--ds-breakpoint-*` tokens. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-line-control`, `--ds-space-1`, `--ds-split-layout-aside-w-lg`, `--ds-split-layout-aside-w-md`, `--ds-split-layout-aside-w-sm`, `--ds-split-layout-gap`, `--ds-split-layout-sticky-offset`, `--ds-toast-clearance`

#### When to use

- An editor or a long form with a chat, a summary or a help panel that should stay visible: `sticky`.
- A list with a filter or preview panel next to it, inside a page.

#### When not to use

- Equal columns: use `Grid`.
- The detail pane of a whole screen (beside the page content, with its own scroll and landmark): use the `detail` prop of `AppShell`.
- A panel that slides over the page: use `Sheet`.

#### Anatomy

```
div (container)
  div (grid)
    div            main content (children)
    aside | div    side panel (aside), after the main content in the DOM
```

#### Responsive behavior

- The layout measures its own width (a container query), so it behaves the same inside a frame, a preview or a test as on the page. The pixel values in the CSS repeat the `--ds-breakpoint-*` tokens; the test suite asserts that they agree.
- Collapsed: one column, main content first, the aside under it. Sticky is off while collapsed.
- `sticky` limits the aside to the viewport height (`100dvh`). Inside a scrolling region shorter than the viewport, such as the `main` of an `AppShell`, give the aside content its own bounded height, or accept that the aside scrolls to its end when the region ends.

#### Accessibility

- The DOM order is main first, then aside: reading order and Tab order follow it, also with `asidePosition="start"` (only the drawing order changes). Put content people need first in `children`.
- `asideLabel` makes the panel a named `aside` (complementary) landmark. A layout primitive adds no unnamed landmark, so leave it off when the panel is not worth a landmark. Do not use it inside `AppShell` for the same content as `detail`.
- A sticky aside that is taller than the viewport scrolls on its own and becomes a keyboard stop (`tabindex="0"`) so the arrow keys scroll it; with nothing to scroll there is no extra tab stop. The scroll padding keeps focused controls clear of the toast region (WCAG 2.4.11).
- Reflow: nothing needs a minimum width; below the collapse width the layout is a single column (WCAG 1.4.10).

#### Examples

```tsx
<SplitLayout aside={<ChatPanel … />} asideLabel="Assistant" sticky>
  <Stack gap={4}>
    <EditorSection … />
    <EditorSection … />
  </Stack>
</SplitLayout>

<SplitLayout asidePosition="start" asideWidth="sm" aside={<FilterList … />}>
  <OrdersTable … />
</SplitLayout>
```

#### Related components

- Instead, see Grid: Equal columns: use `Grid`.
- Instead, see AppShell: The detail pane of a whole screen (beside the page content, with its own scroll and landmark): use the `detail` prop of `AppShell`.
- Instead, see Sheet: A panel that slides over the page: use `Sheet`.

### Stack

> Lays its children out in a vertical column with a consistent gap. The gap is a space token
key, never a pixel value. Children can shrink below their content width (`min-inline-size: 0`).

A vertical column of children with one consistent gap. The gap is a key of the space scale, never a pixel value.

- Import: `import { Stack } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Stack/Stack.tsx`
- Stories (Storybook title `Layout/Stack`): Default, SmallGap, LargeGap, AlignStart, AlignCenter, AlignEnd, AsList, LongText, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `gap` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 12 \| 16 \| '1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '8' \| '12' \| '16'` |  | `4` | Space between children, as a key of the space scale, a number or its string form (`4` = `--ds-space-4` = 16px). Default `4`. |
| `align` | `'center' \| 'start' \| 'end' \| 'stretch'` |  | `'stretch'` | Cross-axis (horizontal) alignment of the children. Default `stretch`. |
| `as` | `'div' \| 'article' \| 'aside' \| 'footer' \| 'form' \| 'header' \| 'li' \| 'main' \| 'nav' \| 'ol' \| 'section' \| 'ul'` |  | `'div'` | Element to render, `div` by default. Use `ul` or `ol` for a list of `li` children: the list reset is applied and `role="list"` keeps the list semantics in Safari. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-space-4`, `--ds-stack-gap`

#### When to use

- Stack blocks of content, fields or cards with the same rhythm.
- A list of items with a uniform gap (`as="ul"`).

#### When not to use

- For a row of items: use `Inline`.
- For a grid of equal cells: use `Grid`.
- To space one pair of elements apart once: a margin from the parent is simpler. Use the layout components for repeated structure.

#### Anatomy

```
div (flex column, gap)
  children
```

#### Accessibility

- A `div` Stack adds no semantics. Choose `as` for the meaning: `ul`/`ol` for lists, `section` with a label for a region.
- `list-style: none` removes list semantics in Safari/VoiceOver, so lists get an explicit `role="list"`.
- Children can shrink below their content width (`min-inline-size: 0`), so long text wraps instead of overflowing at 320px.
- Direction-neutral: `start` and `end` follow the writing direction.

#### Content rules

- None. Stack holds whatever its children are.

#### Examples

```tsx
<Stack gap={6}>
  <Heading level={2}>Account</Heading>
  <Stack gap={3}>
    <Input label="Name" />
    <Input label="Email" />
  </Stack>
</Stack>

<Stack as="ul" gap={2}>
  <li>Orders</li>
  <li>Customers</li>
</Stack>
```

#### Related components

- Instead, see Inline: For a row of items: use `Inline`.
- Instead, see Grid: For a grid of equal cells: use `Grid`.

### StackedBar

> Stacked bars: how each category divides into the same set of parts, horizontal (a row per
category) or vertical (a column per category). Drawn in HTML and CSS, no axis: the total of
each bar is printed with it and the bars share one scale.

Series are told apart without color: a gap separates neighbouring parts, the neutral ramp
differs in lightness, and beyond four series a hatch pattern repeats the ramp. The legend
names every series (and can hide them), and a visually hidden table carries all the numbers.

Each bar is an image with a text summary ("Q1: Online 40 and Store 30. Total 70."). The bars
are one tab stop; the arrow keys move between them, and the active bar's summary is also
printed in a readout line under the chart (hover works the same). A single readout per bar,
not per segment, keeps the keyboard path short and the focus target large.

Stacked bars for parts of a whole per category, horizontal (a row per category) or vertical (a column per category). Each bar has a text summary, a total, and the chart comes with a legend and a hidden data table.

- Import: `import { StackedBar } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/StackedBar/StackedBar.tsx`
- Stories (Storybook title `Components/StackedBar`): Default, Vertical, VerticalTall, Normalized, NormalizedVertical, WithCurrency, EightSeries, ExplicitColors, InteractiveLegend, InteractiveLegendControlled, AllSeriesHidden, KeyboardReadout, WithoutLegend, ZeroBar, Empty, LongLabels, PortugueseBrazil, RightToLeft, LegendShare

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | `readonly StackedBarDatum[]` | yes |  | One bar per datum, in display order. The chart does not sort. |
| `series` | `readonly StackedBarSeries[]` | yes |  | The parts of each bar, bottom to top (vertical) or start to end (horizontal). Without `color` they follow a neutral ramp of four steps; from the fifth series on the ramp repeats with a hatch (up to eight; beyond that pass `color` or group the tail into "Other"). |
| `orientation` | `'horizontal' \| 'vertical'` |  | `'horizontal'` | `horizontal` (default): one row per datum. `vertical`: one column per datum. |
| `normalize` | `boolean` |  | `false` | Draws every bar at full length so each shows the share of its parts (100% stacked). By default bars are scaled to the largest total, so lengths also compare the totals. |
| `format` | `(value: number) => string` |  |  | Formats values in the totals, the legend, the readout and the data table. Default: `Intl` for the active locale. Use `formatCurrency` for money. |
| `legend` | `boolean` |  | `true` | Shows the legend under the bars. On by default: the legend is what names the series. |
| `interactiveLegend` | `boolean` |  | `false` | Makes the legend items toggle buttons that hide and show series. Hidden series leave the bars, totals, summaries and the data table. |
| `legendShare` | `boolean` |  | `false` | Adds the share of each series (its total over the total of the visible series) to the legend, next to the formatted total. Hidden series leave the denominator. Shares are rounded one by one and may not add up to exactly 100%. |
| `hiddenSeries` | `readonly string[]` |  |  | Controlled list of hidden series ids. |
| `defaultHiddenSeries` | `readonly string[]` |  | `[]` | Initial hidden series ids when uncontrolled. |
| `onHiddenSeriesChange` | `(hiddenSeries: string[]) => void` |  |  | Called with the new list of hidden series ids when the user toggles a legend item. |
| `height` | `string \| number` |  |  | Height of the plot area of a vertical chart (a number is px, or any CSS length). Default `--ds-stacked-bar-height` (200px). Ignored when horizontal. |
| `description` | `string` |  |  | Longer description of what the chart shows. Read after the name, together with the keyboard instructions. |
| `categoryLabel` | `string` |  |  | Header of the category column in the hidden data table. Default: the "Category" message. |
| `messages` | `Partial<{ instructions: (count: number, formatted: string) => string; series: (label: string, value: string) => string; bar: (label: string, items: string, total: string) => string; tableCaption: (name?: string) => string; category: string; total: string; empty: string; allHidden: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `aria-label` | `string` |  |  | Accessible name of the chart: what it shows ("Orders by channel, per quarter"). Required unless `aria-labelledby` is set. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the chart (a visible heading). |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ StackedBar: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `instructions(count: number, formatted: string)` | `{formatted} bars. Use the arrow keys to move between bars, Home and End for the first and last.` | Instructions linked to the chart with `aria-describedby`. `count` is the number of bars; `formatted` is the same number formatted for the locale. |
| `series(label: string, value: string)` | `{label} {value}` | One series inside the summary of a bar: "Online 40". Both arguments are already formatted. |
| `bar(label: string, items: string, total: string)` | `{label}: {items}. Total {total}.` | Accessible name of a bar, also shown in the readout. `items` is the list of series joined for the locale ("Online 40 and Store 30"); `total` is the formatted sum of the visible series. |
| `tableCaption(name?: string)` | `Data for {name?}` | Caption of the visually hidden data table. `name` is the accessible name of the chart, if it has a text one. |
| `category` | `Category` | Header of the category column of the data table, unless `categoryLabel` is given. |
| `total` | `Total` | Header of the total column of the data table. |
| `empty` | `No data to show` | Text shown in place of the bars when there is no data. |
| `allHidden` | `All series are hidden. Show one in the legend.` | Text shown in place of the bars when every series is hidden through the legend. |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-chart-series-1`, `--ds-chart-series-2`, `--ds-chart-series-3`, `--ds-chart-series-4`, `--ds-chart-series-hatch-size`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-3`, `--ds-stacked-bar-bar-thickness`, `--ds-stacked-bar-category-w`, `--ds-stacked-bar-color`, `--ds-stacked-bar-column-max-w`, `--ds-stacked-bar-extent`, `--ds-stacked-bar-height`, `--ds-stacked-bar-readout-min-h`, `--ds-stacked-bar-segment-gap`, `--ds-stacked-bar-share`, `--ds-text`, `--ds-text-2`, `--ds-text-3`

#### When to use

- Showing how each of a few categories (2 to about 12) divides into the same 2 to 8 parts: orders per channel per quarter, tasks per status per team.
- Comparing totals and composition together (default), or composition only (`normalize`).

#### When not to use

- One whole divided into parts: `ProportionBar`.
- One series over time or categories: `Chart`. Ranked values: `RankList`.
- Exact figures the reader must look up: give them a table; the hidden table is for assistive technology.
- More than eight series: group the tail into "Other".

#### Anatomy

```
div.root
  div[role=group][aria-label][aria-describedby]
    ul
      li  category (aria-hidden) · div.slot > div[role=img][tabindex][aria-label="Q1: Online 40…"] · total (aria-hidden)
  p[aria-hidden]  readout of the focused or hovered bar
  Legend           names the series (optionally toggles them)
  VisuallyHidden   instructions (aria-describedby) and a <table> with all values
```

Drawn with HTML and CSS: bars use one scale (the largest total is full length), parts are `flex` shares of their bar. There is no value axis; the total is printed with each bar and the legend shows the total of each series.

#### Props (key ones)

| Prop                   | Type                         | Default        | Notes                                                                                               |
| ---------------------- | ---------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
| `data`                 | `{ label, values }[]`        | -              | `values` is keyed by series `id`; missing or negative counts as 0                                   |
| `series`               | `{ id, label, color? }[]`    | -              | Part order: start to end (horizontal), bottom to top (vertical)                                     |
| `orientation`          | `'horizontal' \| 'vertical'` | `'horizontal'` |                                                                                                     |
| `normalize`            | `boolean`                    | `false`        | Every bar at full length (100% stacked)                                                             |
| `format`               | `(value) => string`          | `Intl`         | Totals, legend, summaries, table. Use `formatCurrency` for money                                    |
| `legend`               | `boolean`                    | `true`         | The legend names the series; turn it off only if you name them nearby                               |
| `interactiveLegend`    | `boolean`                    | `false`        | Legend items hide and show series                                                                   |
| `legendShare`          | `boolean`                    | `false`        | Legend also shows each series' share of the visible total (rounded one by one, may not sum to 100%) |
| `hiddenSeries`         | `readonly string[]`          |                | Controlled hidden series                                                                            |
| `defaultHiddenSeries`  | `readonly string[]`          | `[]`           | Initial hidden series when uncontrolled                                                             |
| `onHiddenSeriesChange` | `(ids: string[]) => void`    |                |                                                                                                     |
| `height`               | `number \| string`           | 200px          | Vertical only (`--ds-stacked-bar-height`)                                                           |
| `description`          | `string`                     |                | Read after the name                                                                                 |
| `categoryLabel`        | `string`                     | "Category"     | Header of the first table column                                                                    |
| `messages`             | `Partial<messages>`          |                | Instructions, summaries, table headers, empty states                                                |

`aria-label` or `aria-labelledby` is required.

#### Telling series apart without color

- A 2px gap (the track shows through) separates neighbouring parts.
- Series follow a neutral ramp of four steps that differ in lightness (`--ds-chart-series-1` to `-4`), so they also differ for readers with color vision deficiencies. From the fifth series the ramp repeats with a hatch pattern (up to eight). The series `color` prop is for when that is not enough; it is never hatched.
- The legend names every series and its swatch uses the same fill. A series keeps its fill when another is hidden.
- Each bar's summary and the data table list every series by name with its value.

The single-accent rule holds: the accent appears only in the focus ring. Signal colors appear only if you pass them as explicit series colors.

#### Accessibility

- A group named by `aria-label`/`aria-labelledby`, described by the instructions and your `description`. Each bar is an image whose name is its summary: "Q1: Online 40, Store 30, and Phone 10. Total 80."
- Keyboard: one tab stop for all bars (roving). Arrow keys (and `Home`/`End`) move between bars, `Escape` dismisses the readout. The focused bar has a visible focus ring (system colors in forced colors).
- Why per-bar and not per-segment: a bar is a large target, the path through a chart stays short (one stop), and its single summary gives screen reader users the whole composition at once. The same text is printed in the readout line under the chart for keyboard and pointer users; the readout is `aria-hidden` because the focused bar is already announced.
- Hover shows the same readout. The line has reserved height, so nothing shifts.
- A visually hidden `<table>` (caption, category and one column per visible series, total) carries all values.
- Hidden series leave the bars, totals, summaries and table. If all are hidden, a message says so. An empty `data` shows "No data to show".
- Contrast: every ramp step keeps 3:1 against the track (`--ds-bg`); labels use `text-2`.
- Forced colors: segments use system colors; the track gets a border.
- Category labels are truncated in horizontal bars (96px column, `--ds-stacked-bar-category-w`); the summary and the table carry the full text. Keep labels short.

#### Content rules

- Bar labels: short ("Q1", "North"). Series labels: short nouns in sentence case.
- Name the chart for what it shows ("Orders per quarter, by channel").
- Formatted values come from `Intl`; pass `format` for currency.

#### Example

```tsx
<StackedBar
  aria-label="Orders per quarter, by channel"
  interactiveLegend
  series={[
    { id: 'online', label: 'Online' },
    { id: 'store', label: 'Store' },
    { id: 'phone', label: 'Phone' },
  ]}
  data={[
    { label: 'Q1', values: { online: 40, store: 30, phone: 10 } },
    { label: 'Q2', values: { online: 50, store: 20, phone: 30 } },
  ]}
/>
```

#### Not included

- Value axis and grid lines, negative values, grouped (side by side) bars, per-segment focus, zoom. Use `Chart` for a single series with an axis.
- Series order in vertical bars is fixed (first series at the bottom); the chart never sorts.

#### Related components

- Instead, see ProportionBar: One whole divided into parts: `ProportionBar`.
- Instead, see Chart: One series over time or categories: `Chart`. Ranked values: `RankList`.
- Instead, see RankList: One series over time or categories: `Chart`. Ranked values: `RankList`.
- Renders: Legend, VisuallyHidden

### StatCard

> An indicator card: a mono caption, a large mono number and a short note, optionally with a
trend and a small visual (such as a `ProportionBar`) in between.

It is a description list: the label is the term, the value and the note are its
descriptions, so a screen reader announces "Sold, $37,655.30, Up 12% vs previous 30 days".
A colored value is never the only signal: `tone` other than `neutral` requires a `note` or a
`trend` (a computed `StatCardTone` is accepted when either is passed), and the trend is written as text ("Up 12%").

An indicator card for the top of a screen: a mono caption, a large mono number, an optional small visual and a short note or trend in words.

- Import: `import { StatCard } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/StatCard/StatCard.tsx`
- Stories (Storybook title `Components/StatCard`): Default, Large, WithAside, WarningTone, DangerTone, SuccessTone, TrendUp, TrendUpIsBad, TrendDownAndFlat, WithProportionBar, LongText, Grid, PortugueseBrazil

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | `ReactNode` | yes |  | What the number is, in a few words: "Sold", "Overdue". Shown as a mono caption (uppercase by CSS) and used as the term of the card. |
| `value` | `ReactNode` | yes |  | The number or amount. Format it with `formatCurrency` or `formatNumber` for the active locale. |
| `size` | `'md' \| 'lg'` |  | `'md'` | `md` (default, 24px) or `lg` (30px). |
| `aside` | `ReactNode` |  |  | Short mono text at the end of the label row: "42%". Read after the value. |
| `children` | `ReactNode` |  |  | Content between the value and the note, for example a 4px `ProportionBar`. |
| `noteTone` | `'neutral' \| 'success' \| 'warning' \| 'danger'` |  | `'neutral'` | Color of the note text. Default `neutral`. Only affects color: the note is text anyway. |
| `messages` | `Partial<{ trendUp: (percent: string) => string; trendDown: (percent: string) => string; trendFlat: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `tone` | `'neutral' \| 'success' \| 'warning' \| 'danger'` |  | `'neutral'` | Color of the value. Use `danger` or `warning` only when the number asks for action, `success` when everything is fine. Default `neutral`. A colored value must be backed by text: pass `note` or `trend` (type error otherwise). Accepts any `StatCardTone`, so a computed tone such as `flag ? 'warning' : 'neutral'` type-checks as long as `note` or `trend` is present. |
| `note` | `ReactNode` |  |  | Context or change in words: "3 sales · average ticket $120". |
| `trend` | `StatCardTrend` |  |  | A change versus a previous period, rendered as text through the messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `md`, `lg`
- `tone`: `neutral`, `success`, `warning`, `danger`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ StatCard: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `trendUp(percent: string)` | `Up {percent}` | Text of an upward trend. `percent` is already formatted for the locale ("12%"). |
| `trendDown(percent: string)` | `Down {percent}` | Text of a downward trend. |
| `trendFlat` | `No change` | Text of a trend without change. |

#### Design tokens used

`--ds-danger`, `--ds-font-mono`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-fs-num`, `--ds-fs-num-lg`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-lh-num`, `--ds-lh-num-lg`, `--ds-line`, `--ds-radius-lg`, `--ds-space-1`, `--ds-space-2`, `--ds-stat-card-gap`, `--ds-stat-card-padding`, `--ds-success`, `--ds-surface`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tracking-caption`, `--ds-tracking-display`, `--ds-tracking-title`, `--ds-warning`, `--ds-weight-medium`, `--ds-weight-regular`, `--ds-weight-semibold`

#### When to use

- A handful of key numbers at the top of a page (Today, Purchases, Finance, Reports).
- A number with context: "3 sales · average ticket $120.00", or a change versus a previous period.

#### When not to use

- Many numbers that need comparing or sorting: use `DataTable`.
- A value the user edits: use a field.
- A status without a number: use `Badge`.

#### Anatomy

```
dl.root (surface, 1px line, radius lg, padding 20)
  dt   label        mono caption, uppercase by CSS
  dd   value        mono 24px (md) or 30px (lg); colored by tone
  dd   aside        short mono text at the end of the label row (optional)
  dd   children     small visual, e.g. a 4px ProportionBar (optional)
  dd   note         trend (arrow + "Up 12%" + comparison) and/or note text
```

#### Props (key ones)

| Prop       | Type                                        | Default   | Notes                                                                                   |
| ---------- | ------------------------------------------- | --------- | --------------------------------------------------------------------------------------- |
| `label`    | `ReactNode`                                 | -         | A few words: "Sold", "Overdue"                                                          |
| `value`    | `ReactNode`                                 | -         | Format with `formatCurrency` / `formatNumber`                                           |
| `size`     | `md \| lg`                                  | `md`      | `--ds-fs-num` / `--ds-fs-num-lg`                                                        |
| `tone`     | `neutral \| success \| warning \| danger`   | `neutral` | Color of the value. Any other tone requires `note` or `trend` (type error, dev warning) |
| `note`     | `ReactNode`                                 |           | Context in words                                                                        |
| `noteTone` | `neutral \| success \| warning \| danger`   | `neutral` | Color of the note text                                                                  |
| `trend`    | `{ direction, value?, tone?, comparedTo? }` |           | Change as text: "Up 12%", "Down 4.5%", "No change". `value` is a ratio (`0.12`)         |
| `aside`    | `ReactNode`                                 |           | "42%"                                                                                   |
| `children` | `ReactNode`                                 |           | Between the value and the note                                                          |
| `messages` | `Partial<messages>`                         |           | `trendUp(percent)`, `trendDown(percent)`, `trendFlat`                                   |

#### Accessibility

- It is a description list: the label is the term (`dt`), the value and the note are its descriptions (`dd`). A screen reader announces "Sold, $37,655.30, Up 12% vs previous 30 days".
- Color is never the only signal. A non-neutral `tone` must come with a `note` or a `trend` (enforced by types, with a one-time development warning for untyped callers). The trend direction is written as text and the arrow icon is decorative.
- Contrast: the signal colors on `surface` pass 4.5:1; notes use `text-2`; the caption uses `text-3` (do not put the card on a raised or hover surface).
- No interaction. If the card should open something, wrap the label in a link or add a button in the note area.

#### Content rules

- Tone only changes when there is something to do: `danger`/`warning` for numbers that ask for action, `success` for "all done". Do not decorate.
- At most four cards per row; use a grid with `repeat(auto-fit, minmax(240px, 1fr))` so large numbers are not cut.
- Trends say what changed and compared to what ("Up 12% vs previous 30 days"). When up is bad (costs, returns) set `trend.tone: 'danger'`.

#### Example

```tsx
<StatCard
  label="Sold"
  value={formatCurrency(3765530, 'USD', locale)}
  trend={{ direction: 'up', value: 0.12, comparedTo: 'vs previous 30 days' }}
/>
<StatCard label="Overdue" value="$96.40" tone="danger" note="Water bill since Oct 28" />
```

A computed tone type-checks as long as `note` or `trend` is passed; a literal non-neutral tone without either is still a type error:

```tsx
<StatCard
  label="Overdue"
  value={total}
  tone={overdue ? 'warning' : 'neutral'}
  note={`${count} bills`}
/>
```

#### Related components

- Instead, see DataTable: Many numbers that need comparing or sorting: use `DataTable`.
- Instead, see Badge: A status without a number: use `Badge`.
- Renders: Icon

### StatusSteps

> A horizontal indicator of progress through a linear status flow (Draft, Packed, Shipped).
It is an ordered list; every step states its progress as text read by assistive technology
("Completed", "Current", "Not started", from messages), and the current step has
`aria-current="step"`. The marker (number or check) and the connector lines are decorative.

With `onSelect` each step becomes a real button, so the status can be changed from here.

A horizontal indicator of progress through a linear status flow (Draft, Packed, Shipped, Delivered). It is an ordered list; each step states its progress as text for assistive technology, and the steps can optionally be buttons to change the status.

- Handoff source: `components/erp/StatusSteps.jsx` (TODO `CMP-PAT-05`).

- Import: `import { StatusSteps } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/StatusSteps/StatusSteps.tsx`
- Stories (Storybook title `Components/StatusSteps`): Default, FirstStep, Complete, ManySteps, LongLabels, Interactive, Controlled, Portuguese, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `steps` | `readonly StatusStep[]` | yes |  | The steps, in order. |
| `current` | `number` | yes |  | Index of the current step (0-based). Steps before it are complete. |
| `aria-label` | `string` |  |  | Accessible name of the list ("Order status"). Required: name this or use `aria-labelledby`. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the list. |
| `complete` | `boolean` |  | `false` | When `true`, the current step is complete too (the whole flow is done). |
| `onSelect` | `(index: number, step: StatusStep) => void` |  |  | Makes every step a button. Called with the index and the step; the consumer decides whether going back or skipping ahead is allowed. Reversible changes need no confirmation (offer Undo). |
| `messages` | `Partial<{ complete: string; current: string; upcoming: string; }>` |  |  | Message overrides for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ StatusSteps: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `complete` | `Completed` | Read after the label of a step that is done. |
| `current` | `Current` | Read after the label of the step in progress. |
| `upcoming` | `Not started` | Read after the label of a step that has not started. |

#### Design tokens used

`--ds-accent`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-meta`, `--ds-lh-meta`, `--ds-line-control`, `--ds-line-strong`, `--ds-primary-bg`, `--ds-radius-md`, `--ds-radius-pill`, `--ds-space-2`, `--ds-status-steps-connector-thickness`, `--ds-status-steps-content-z-index`, `--ds-status-steps-gap`, `--ds-status-steps-marker-border-width`, `--ds-status-steps-marker-hover-border`, `--ds-status-steps-marker-size`, `--ds-status-steps-padding-block`, `--ds-success`, `--ds-surface`, `--ds-surface-hover`, `--ds-text`, `--ds-text-2`, `--ds-text-inverse`, `--ds-weight-medium`, `--ds-weight-semibold`

#### When to use

- Show where a record is in a fixed, ordered flow, optionally letting people move it.
- A flow of 3 to 6 short steps.

#### When not to use

- A multi-page form with validation and Back/Next: build it with `Tabs` or your router.
- Non-linear or parallel states: use `Badge`.
- A percentage of something: use `Progress`.

#### Anatomy

```
ol aria-label="Order status"
  li[data-state=complete|current|upcoming]
    span | button            (button only with onSelect; aria-current="step" on the current one)
      marker                 (number or check, aria-hidden)
      label
      visually hidden state  ("Completed", "Current", "Not started")
  connector lines            (CSS pseudo-elements, decorative)
```

#### Accessibility

- `ol` / `li` semantics; the position is implied by the list ("2 of 4").
- Every step's state is real text read after its label (`Completed`, `Current`, `Not started`, from messages). The number or check is `aria-hidden`; color and the check are not the only signal.
- The current step has `aria-current="step"`.
- With `onSelect`, steps are native buttons: Tab / Shift+Tab move, Enter and Space select, focus has the accent ring. There is no roving focus because this is a list of buttons, not a composite widget.
- Contrast: upcoming labels use `--ds-text-2` and the upcoming marker border `--ds-line-control` (3:1).
- Forced colors: current and complete markers use `Highlight`; connectors use `ButtonText`.

#### Content rules

- Labels are nouns or past participles in sentence case ("Packed", "In production").
- Moving a status is reversible: do not confirm; offer Undo in a toast.

#### Examples

```tsx
<StatusSteps
  aria-label="Order status"
  steps={[
    { id: 'draft', label: 'Draft' },
    { id: 'packed', label: 'Packed' },
    { id: 'shipped', label: 'Shipped' },
  ]}
  current={1}
  onSelect={(index) => setStatus(index)}
/>
```

#### Related components

- Instead, see Tabs: A multi-page form with validation and Back/Next: build it with `Tabs` or your router.
- Instead, see Badge: Non-linear or parallel states: use `Badge`.
- Instead, see Progress: A percentage of something: use `Progress`.
- Renders: Icon, VisuallyHidden

### Stepper

> Progress through a multi-step flow such as a setup assistant. It is an ordered list; every
step states its progress as text for assistive technology ("Completed", "Current", "Not
started") and the current step has `aria-current="step"`. Markers and connectors are
decorative. Completed steps can be buttons with `onStepPress`.

In narrow containers the horizontal orientation shows only the markers and a visible summary
("Step 3 of 9"), so nine steps fit in 320 px. The width at which this happens grows with the step count
(6, 7 to 8 and 9 or more steps switch at 600, 720 and 800 px), and a label that does not fit
is clipped after two lines instead of breaking inside a word.

Progress through a multi-step flow, such as a 9-step setup assistant. It is an ordered list; each step states its progress as text for assistive technology, and completed steps can optionally be buttons to go back.

- Import: `import { Stepper } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Stepper/Stepper.tsx`
- Stories (Storybook title `Components/Stepper`): Default, FirstStep, AllComplete, Vertical, NineStepsNarrow, NineStepsWide, NineLongLabels700, NineLongLabels900, LongLabels, GoBackToCompletedSteps, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `steps` | `readonly StepperStep[]` | yes |  | The steps, in order. |
| `current` | `number` | yes |  | Index of the current step (0-based). Steps before it are completed. |
| `aria-label` | `string` |  |  | Accessible name of the list ("New agent steps"). Required: name this or use `aria-labelledby`. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the list. |
| `complete` | `boolean` |  | `false` | When `true`, the current step is completed too (the whole flow is done). |
| `orientation` | `'horizontal' \| 'vertical'` |  | `'horizontal'` | `horizontal` (default) or `vertical`. Horizontal collapses to markers and "Step 3 of 9" in narrow containers. |
| `onStepPress` | `(index: number, step: StepperStep) => void` |  |  | Makes every completed step a button that calls this with its index and the step, so people can go back. The current and upcoming steps are never buttons: the flow itself (Next) moves forward. |
| `messages` | `Partial<{ complete: string; current: string; upcoming: string; summary: (current: string, total: string) => string; }>` |  |  | Message overrides for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Stepper: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `complete` | `Completed` | Read after the label of a step that is done. |
| `current` | `Current` | Read after the label of the step in progress. |
| `upcoming` | `Not started` | Read after the label of a step that has not started. |
| `summary(current: string, total: string)` | `Step {current} of {total}` | Visible summary of the progress when the labels do not fit; `current` and `total` are formatted numbers. |

#### Design tokens used

`--ds-accent`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-line-control`, `--ds-line-strong`, `--ds-primary-bg`, `--ds-radius-md`, `--ds-radius-pill`, `--ds-space-2`, `--ds-stepper-connector-thickness`, `--ds-stepper-content-z-index`, `--ds-stepper-gap`, `--ds-stepper-marker-border-width`, `--ds-stepper-marker-size`, `--ds-stepper-padding-block`, `--ds-stepper-step-gap`, `--ds-success`, `--ds-surface`, `--ds-surface-hover`, `--ds-text`, `--ds-text-2`, `--ds-text-inverse`, `--ds-weight-medium`, `--ds-weight-semibold`

#### When to use

- A guided flow with several steps shown one at a time (assistant, onboarding, checkout), where people need to know where they are and how much is left.
- Flows of 3 to 10 steps. In narrow containers it collapses to markers plus "Step 3 of 9".

#### When not to use

- The status of a record in a fixed flow (Draft, Packed, Shipped): use `StatusSteps`.
- A percentage of something: use `Progress`.
- Switching between views of the same content: use `Tabs`.

##### Stepper and StatusSteps

|                    | Stepper                                        | StatusSteps                              |
| ------------------ | ---------------------------------------------- | ---------------------------------------- |
| Describes          | Your progress through a flow you are doing now | The state a record is in                 |
| Typical length     | 3 to 10 steps                                  | 3 to 6 steps                             |
| Interaction        | Only completed steps can be pressed (go back)  | Every step can be pressed (change state) |
| Orientation        | Horizontal or vertical                         | Horizontal                               |
| Narrow containers  | Markers plus "Step 3 of 9"                     | Same layout                              |
| Per-step help text | `description` (vertical)                       | None                                     |

#### Anatomy

```
div[data-orientation]
  p (aria-hidden)           "Step 3 of 9: Label", visible only in narrow containers
  ol aria-label="Setup progress"
    li[data-state=complete|current|upcoming]
      span | button         (button only for completed steps with onStepPress; aria-current="step" on the current one)
        marker              (number or check, aria-hidden)
        label + visually hidden state ("Completed", "Current", "Not started")
        description         (vertical only)
  connector lines           (CSS pseudo-elements, decorative)
```

#### Accessibility

- A real ordered list named by `aria-label` or `aria-labelledby`. The current step has `aria-current="step"` (on the button when it is one).
- Progress is text, not only color or a check: every step ends with a visually hidden "Completed", "Current" or "Not started" (messages).
- Markers, connectors and the "Step 3 of 9" summary are decorative duplicates (`aria-hidden`); the list conveys the same information.
- Keyboard: completed step buttons are in the Tab order and activate with `Enter` or `Space`. Upcoming steps are not focusable, so people cannot skip ahead; move forward with the flow's own Next button.
- Target size: the marker is 24 px, so step buttons meet WCAG 2.5.8 even at 320 px with 9 steps.
- Reflow: labels never break inside a word; one that does not fit is clipped after two lines. The container width below which the horizontal stepper collapses grows with the step count: 480 px, 600 px for 6 steps, 720 px for 7 or 8 steps and 800 px for 9 or more. Below that width the horizontal labels are visually hidden (still read by screen readers) and a visible "Step N of M: label" line appears. The vertical orientation needs no collapse.
- Forced colors: markers and connectors use system colors; the state text still names every step.

#### Content rules

- Labels: a few words, sentence case, nouns ("Source", "Review"), not sentences.
- The description says what the step is for, in one line ("Name and purpose").
- Name the list for what it is: "New agent steps", not "Steps".

#### Examples

```tsx
<Stepper aria-label="Setup progress" steps={steps} current={step} />

<Stepper
  aria-label="Setup progress"
  orientation="vertical"
  steps={steps}
  current={step}
  onStepPress={(index) => setStep(index)}
/>
```

#### Related components

- Instead, see StatusSteps: The status of a record in a fixed flow (Draft, Packed, Shipped): use `StatusSteps`.
- Instead, see Progress: A percentage of something: use `Progress`.
- Instead, see Tabs: Switching between views of the same content: use `Tabs`.
- Renders: Icon, VisuallyHidden

### SubMenu

> An item that opens a nested menu. Arrow Right (Arrow Left in right-to-left) opens it and
Arrow Left closes it; Escape closes the submenu first, then the menu.

A menu of commands that opens from a trigger. Built on React Aria `MenuTrigger`, `Popover` and `Menu`. Exports `Menu`, `MenuItem`, `MenuSection`, `MenuSeparator`, `SubMenu` and `MoreActionsMenu`.

- Handoff source: `components/navigation/Menu` (CMP-NAV-02).

- Import: `import { SubMenu } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Menu/Menu.tsx`
- Stories (Storybook title `Components/Menu`): Default, EscapeRestoresFocus, TypeaheadAndHomeEnd, Open, CheckboxItems, RadioItems, WithSections, WithSubmenu, LongLabels, MoreActions

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | `ReactNode` | yes |  | Label of the item that opens the submenu; end it with an ellipsis when it opens more choices ("Move to…"). |
| `children` | `ReactNode` | yes |  | `MenuItem`, `MenuSection` and `MenuSeparator` elements of the submenu. |
| `textValue` | `string` |  |  | Used for typeahead and as the item's name when `label` is not a string. |
| `isDisabled` | `boolean` |  |  | Disables the item: it cannot be opened or focused by typeahead. |
| `delay` | `number` |  |  | Milliseconds the pointer must rest on the item before the submenu opens. Default 200. |
| `className` | `string` |  |  | Class name for the submenu list. |

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-danger-soft-hover`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-small`, `--ds-item-h`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-line-strong`, `--ds-menu-indicator-size`, `--ds-menu-max-width`, `--ds-menu-min-width`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-select-popover-max-height`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-4`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-tracking-caption`

#### When to use

- Row, card or toolbar actions that do not deserve their own button.
- View options with check or radio items (columns shown, sort order, density).

#### When not to use

- Choosing a value for a field: use `Select` or `Combobox`.
- Content the user types into or operates (filters, forms): use `Popover`.
- Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- The only way to reach an important action: keep primary actions visible.

#### Anatomy

```
MenuTrigger
  trigger            Button | IconButton    aria-haspopup=true, aria-expanded
  Popover            raised surface, radius lg, overlay shadow, z popover
    Menu             role=menu, named by the trigger (aria-labelledby)
      MenuItem       role=menuitem | menuitemcheckbox | menuitemradio, height --ds-item-h
        indicator    check / dot (selectable menus)
        label
        shortcut     mono hint, optional
        chevron      when it opens a SubMenu
      MenuSection    role=group, caption optional (mono uppercase)
      MenuSeparator  1px line
```

#### Accessibility

Keyboard contract (AGENTS.md section 8):

| Key                                     | Behavior                                                        |
| --------------------------------------- | --------------------------------------------------------------- |
| `Enter`, `Space`, `ArrowDown` (trigger) | Opens the menu and focuses the first item                       |
| `ArrowUp` (trigger)                     | Opens the menu and focuses the last item                        |
| `ArrowUp` / `ArrowDown`                 | Move between items; disabled items are skipped                  |
| `Home` / `End`                          | First / last item                                               |
| Typing                                  | Typeahead: focus moves to the item whose label starts with it   |
| `Enter` / `Space`                       | Activates the item (checkbox and radio items toggle) and closes |
| `ArrowRight` / `ArrowLeft`              | Open / close a submenu (mirrored in right-to-left)              |
| `Escape`                                | Closes one level; focus returns to the trigger                  |

- Items are real `menuitem`, `menuitemcheckbox` or `menuitemradio` elements with `aria-checked`; the handoff used `tabIndex=0` divs with no keyboard activation.
- Danger is red text plus the item's own label ("Delete order"); the colour is never the only signal. `tone="danger"` does not confirm: open a `ConfirmDialog` from `onAction`.
- The shortcut hint is visual; bind the key yourself. It uses `--ds-text-2` so the hint stays legible next to the label.
- Focus is shown with the accent ring; forced colors use a `Highlight` outline.
- Layer: `--ds-z-popover` (see Dialog doc, "Layers", for menus opened inside a Dialog or Sheet).
- The `MoreActionsMenu` trigger has a tooltip that repeats its name.

#### Content rules

- Items are a verb plus object in sentence case ("Duplicate order"). End with an ellipsis only when the item opens something that needs more input ("Move to…").
- Order: most common first, destructive last, separated by a `MenuSeparator`.

#### Examples

```tsx
<MoreActionsMenu onAction={(key) => run(String(key))}>
  <MenuItem id="edit" shortcut="Ctrl+E">Edit order</MenuItem>
  <MenuItem id="duplicate">Duplicate order</MenuItem>
  <MenuSeparator />
  <MenuItem id="delete" tone="danger">Delete order</MenuItem>
</MoreActionsMenu>

<Menu trigger={<Button>View</Button>} selectionMode="multiple" defaultSelectedKeys={['id']}>
  <MenuItem id="id">Show ID</MenuItem>
  <MenuItem id="status">Show status</MenuItem>
</Menu>
```

#### Related components

- Instead, see Select: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Combobox: Choosing a value for a field: use `Select` or `Combobox`.
- Instead, see Popover: Content the user types into or operates (filters, forms): use `Popover`.
- Instead, see Tabs: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Sidebar: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Instead, see Breadcrumb: Navigation between pages: use `Tabs`, `Sidebar` or `Breadcrumb`.
- Renders: Icon, IconButton

### SuggestionChip

> A dashed chip that proposes a piece of text. Pressing it **inserts** that text into a
nearby field (for example a message composer); it never submits or navigates.

The dashed border and the leading plus tell sighted users that it adds something. The plus
is decorative: screen readers hear the label, so word the label as the text itself and put
the chips in a labelled group ("Suggested replies") so the purpose is announced once.

A dashed chip that proposes a piece of text. Pressing it **inserts** that text into a nearby field (a message composer, a note, a search box). Built on React Aria `Button`.

- Handoff source: `components/forms/SuggestionChip.jsx` (TODO `CMP-FRM-10`).

- Import: `import { SuggestionChip } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/SuggestionChip/SuggestionChip.tsx`
- Stories (Storybook title `Components/SuggestionChip`): Default, Disabled, LongText, InsertsText, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | The suggested text. The chip is named by it and, when pressed, the consumer inserts exactly this text (or the text it stands for) into the field it belongs to. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLButtonElement>` |  |  | Ref to the underlying `<button>` element. |

##### Inherited props

- From `AriaBaseButtonProps` (react-aria): `aria-controls`, `aria-current`, `aria-disabled`, `aria-expanded`, `aria-haspopup`, `aria-pressed`, `form`, `formAction`, `formEncType`, `formMethod`, `formNoValidate`, `formTarget`, `name`, `preventFocusOnPress`, `type`, `value`
- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `ButtonProps` (react-aria): `isDisabled`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `HoverEvents` (@react-types/shared): `onHoverChange`, `onHoverEnd`, `onHoverStart`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `SlotProps` (react-aria-components): `slot`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-control-h-sm`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-sans`, `--ds-fs-label`, `--ds-lh-label`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-lg`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-weight-medium`

#### When to use

- Suggested replies, snippets, prompts or tags that save typing.
- The result of pressing is always "this text appears in the field"; the user still reviews and sends it.

#### When not to use

- To run an action (save, send, delete): use `Button`.
- To filter or toggle a state: use `Tag` in a `TagGroup` with selection, or `SegmentedControl`.
- To navigate: use `Link`.

#### Behavior

`SuggestionChip` does not know about the field. `onPress` is where the consumer inserts the text (append at the caret, replace the selection, or set the value) and, usually, returns focus to the field. The chip never submits a form and never sends anything.

#### Accessibility

- A real `<button type="button">`: `Enter` and `Space` press it.
- The leading plus is decorative (`aria-hidden`) and the dashed border is visual. Neither is the only cue: the chip sits in a group whose label says what the chips are, so give the container a name (`role="group"` with `aria-label="Suggested replies"`).
- Word the label as the text itself ("Your order has shipped."), not as an instruction. Screen reader users then hear exactly what will be inserted.
- Long text wraps inside the available width; the chip keeps a 32px minimum height.
- Disabled: reduced opacity and no hover. The handoff's .45 and .35 values are unified into one token.
- Focus: accent border and ring.

#### Content rules

- The label is the text to insert, in sentence case, in the voice of the product (see AGENTS.md section 6).
- Keep it to one sentence; very long snippets belong in a template picker.

#### Examples

```tsx
<div role="group" aria-label="Suggested replies">
  {replies.map((reply) => (
    <SuggestionChip key={reply} onPress={() => insert(reply)}>
      {reply}
    </SuggestionChip>
  ))}
</div>
```

#### Related components

- Instead, see Button: To run an action (save, send, delete): use `Button`.
- Instead, see Tag: To filter or toggle a state: use `Tag` in a `TagGroup` with selection, or `SegmentedControl`.
- Instead, see TagGroup: To filter or toggle a state: use `Tag` in a `TagGroup` with selection, or `SegmentedControl`.
- Instead, see SegmentedControl: To filter or toggle a state: use `Tag` in a `TagGroup` with selection, or `SegmentedControl`.
- Instead, see Link: To navigate: use `Link`.
- Renders: Icon

### Swatch

> A small circle filled with a color, with a subtle inset ring so dark colors stay visible on
dark surfaces. It needs either a `label` (the color's name) or `decorative`, so the color is
never the only carrier of meaning.

Built as a plain element rather than React Aria `ColorSwatch`: that one paints an inline
`background` and names itself with a generated description ("vibrant blue"), while this one
sets only the `--ds-swatch-color` custom property and uses the name you give it.

A small circle filled with a color, with a subtle inset ring so dark colors stay visible on dark surfaces. It shows a color; it never names it, so every swatch is either labelled or explicitly decorative.

- Handoff source: `components/erp/Swatch.jsx` (TODO `CMP-PAT-03`).

- Import: `import { Swatch } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Swatch/Swatch.tsx`
- Stories (Storybook title `Components/Swatch`): Default, Sizes, ExtremeColors, Decorative, ShortHex, NoColor

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` |  |  | Name of the color ("Navy"). Required whenever the swatch is the only thing that identifies the color: a color on its own says nothing to a screen reader or to a color-blind user. |
| `decorative` | `true` |  |  | Hides the swatch from assistive technology. Use it only when the color is also named by adjacent text (a table cell, an option label). |
| `color` | `string \| null` |  |  | The color to show, as `#rgb` or `#rrggbb`. `undefined`, `null` and `''` mean "no color" and render an empty dashed circle (use it for model data that may have no color). Any other value throws in development and renders the same empty circle in production. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Diameter token: `sm` 16px, `md` 20px (default), `lg` 32px. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Design tokens used

`--ds-line-control`, `--ds-radius-pill`, `--ds-swatch-color`, `--ds-swatch-ring`, `--ds-swatch-size-lg`, `--ds-swatch-size-md`, `--ds-swatch-size-sm`

#### When to use

- Next to the name of a color, tag or category (a legend, a table cell, an option).
- On its own, with a `label`, when the color is the whole content (a color chip in a toolbar).

#### When not to use

- To carry a status: use `Badge` (text plus tone).
- To pick a color: use `ColorOption` from `loui-ds/patterns`.
- For arbitrary CSS colors (`rgb()`, names): only `#rgb` and `#rrggbb` are accepted.

#### Anatomy

```
span[role=img] aria-label="Navy"        (labelled)
span[aria-hidden]                        (decorative)
  background: var(--ds-swatch-color)
  inset ring: var(--ds-swatch-ring)
```

#### Accessibility

- A color on its own is not information: it is invisible to screen readers and ambiguous for color-blind users, hence the required `label` or `decorative`.
- Labelled swatches are `role="img"`. Decorative ones are `aria-hidden`.
- The inset ring uses `--ds-swatch-ring`, a low-contrast outline that keeps near-black swatches visible. It is not a boundary meant to reach 3:1: the name next to or on the swatch is what identifies it.
- Forced colors: `forced-color-adjust: none` keeps the fill, and a `ButtonText` border is added.

#### Content rules

- Labels are plain color names in sentence case ("Navy", "Brick red"), not hex codes.

#### Examples

```tsx
<Swatch color="#1f3a93" label="Navy" />

<span>
  <Swatch color="#c0392b" decorative size="sm" /> Brick red
</span>
```

#### Related components

- Instead, see Badge: To carry a status: use `Badge` (text plus tone).
- Instead, see ColorOption: To pick a color: use `ColorOption` from `loui-ds/patterns`.
- Used by: ApprovalCard, ColorField, ColorOption, MatrixGrid, RankList

### Switch

> An on/off setting that applies immediately. Renders a native checkbox with `role="switch"`
(so `name` / `value` take part in form submission), a 36x20 track and a 16px knob.

State props follow React Aria: `isSelected`, `defaultSelected` and `onChange(isSelected)`.
For a choice that is confirmed later with a Save button, prefer `Checkbox`.

An on/off setting that takes effect immediately. A native checkbox with `role="switch"`, a 36x20 track and a 16px knob. Built on React Aria `SwitchField` + `SwitchButton` (the non-deprecated pair that supports a description and an error outside the label). Shared field behavior is in [Field](../Field/Field.md).

- Import: `import { Switch } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Switch/Switch.tsx`
- Stories (Storybook title `Components/Switch`): Default, On, WithDescription, LabelAtEnd, Disabled, ReadOnly, Required, Invalid, LongLabel, WithoutVisibleLabel

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | `ReactNode` |  |  | Secondary text under the label. Linked with `aria-describedby`, not part of the name. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while the switch is invalid and the error is displayed. |
| `labelPlacement` | `'start' \| 'end'` |  | `'start'` | Where the label sits relative to the track. `start` (default): text on the leading side, track on the trailing side, spread across the row, the settings-list layout. `end`: track first. |
| `className` | `string` |  |  | Class name for the field root. |
| `messages` | `Partial<{ requiredMark: string; }>` |  |  | Message overrides for this instance (`requiredMark`). |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. Use `inputRef` for the `<input>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaSwitchProps` (react-aria): `aria-controls`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `SwitchFieldProps` (react-aria-components): `inputRef`
- From `ToggleProps` (react-stately): `value`
- From `ToggleStateOptions` (react-stately): `defaultSelected`, `isSelected`, `onChange`
- From `Validation` (@react-types/shared): `isInvalid`, `isRequired`, `validate`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-focus-ring-danger`, `--ds-fs-small`, `--ds-lh-small`, `--ds-line-control`, `--ds-opacity-disabled`, `--ds-radius-pill`, `--ds-space-1`, `--ds-space-4`, `--ds-switch-knob-offset`, `--ds-switch-knob-size`, `--ds-switch-track-height`, `--ds-switch-track-width`, `--ds-text`, `--ds-text-3`

#### When to use

- Settings that apply as soon as they change ("Email notifications"), with the state obvious from the label.

#### When not to use

- Choices confirmed later with a Save button or submitted as an agreement: `Checkbox`.
- One of several options: `RadioGroup`.

#### Props (key ones)

| Prop                                                                  | Notes                                                                                                               |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `label`                                                               | Visible label. Without it pass `aria-label` or `aria-labelledby` (renders only the track).                          |
| `description`                                                         | Secondary text under the label, linked by `aria-describedby`, not part of the name.                                 |
| `labelPlacement`                                                      | `start` (default): text on the leading side, track on the trailing side, spread across the row. `end`: track first. |
| `isSelected` / `defaultSelected` / `onChange(isSelected)`             | React Aria naming.                                                                                                  |
| `name`, `value`                                                       | Submitted with the form while on (`value` defaults to `on`).                                                        |
| `isDisabled`, `isReadOnly`, `isRequired`, `isInvalid`, `errorMessage` | Standard states.                                                                                                    |
| `inputRef` / `ref`                                                    | `inputRef` is the `<input>`, `ref` the field root.                                                                  |

#### Look

- Off: track in `--ds-line-control` (3:1 or better against the page, also on hover); on: `--ds-accent`. The knob uses `--ds-text` and moves with `inset-inline-start`, so it mirrors in right-to-left.
- Sizes come from component tokens: `--ds-switch-track-width`, `--ds-switch-track-height`, `--ds-switch-knob-size`, `--ds-switch-knob-offset`.
- The row is at least as tall as the track and the whole row is the click target, with one toggle per click.
- Reduced motion: transitions are removed by the base layer.
- Forced colors: the track gets a system border and a `Highlight` fill when on; the knob uses `CanvasText`.

#### Accessibility

- `Space` toggles the focused switch. `Enter` does not toggle (it submits the form, as for any native checkbox).
- Announced as "switch, on/off", named by the label only; the description is `aria-describedby`.
- State is conveyed by position and by color, and by the announced state.

#### Example

```tsx
<Switch label="Email notifications" description="A summary every morning." defaultSelected />
<Switch label="Dark mode" labelPlacement="end" name="theme" value="dark" />
<Switch aria-label="Enable sync" />
```

#### Related components

- Instead, see Checkbox: Choices confirmed later with a Save button or submitted as an agreement: `Checkbox`.
- Instead, see RadioGroup: One of several options: `RadioGroup`.
- Renders: FieldMessages, RequiredMark

### Tab

> One tab of a `TabList`, with an optional count and shortcut hint.

Tabs switch between panels of related content on the same page. Built on React Aria `Tabs`, `TabList`, `Tab` and `TabPanel`: one tab stop, arrow keys between tabs, panels linked to their tabs.

- Handoff source: `components/navigation/Tabs.jsx` (TODO `CMP-NAV-01`).

- Import: `import { Tab } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Tabs/Tabs.tsx`
- Stories (Storybook title `Components/Tabs`): Default, ArrowKeys, FocusMovesIntoPanel, ManualActivation, Counts, ShortcutHints, DisabledTab, Controlled, LongLabels, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | Tab label: a noun in sentence case ("Orders"). |
| `count` | `string \| number` |  |  | A count shown after the label. Numbers are formatted for the active locale. The count is part of the tab's accessible name, so pair it with `countLabel` when the bare number is ambiguous. |
| `countLabel` | `string` |  |  | Accessible text for the count ("3 pending"). When set, it replaces the visible count in the accessible name. Recommended whenever `countTone` is not `neutral`. |
| `countTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  | `'neutral'` | Tone of the count. `neutral` (default) is plain mono text; the other tones draw a soft pill. Color never carries the meaning alone: use `countLabel` to say what the count means. |
| `shortcut` | `readonly string[]` |  |  | Keys of a shortcut hint shown after the label, as for `Kbd` (`['1']`, `['Mod', 'K']`). Decorative: hidden from assistive technology, and it registers nothing. Register the shortcut itself with `useHotkey`. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the tab element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `HoverEvents` (@react-types/shared): `onHoverChange`, `onHoverEnd`, `onHoverStart`
- From `LinkDOMProps` (@react-types/shared): `download`, `href`, `hrefLang`, `ping`, `referrerPolicy`, `rel`, `routerOptions`, `target`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `TabProps` (react-aria-components): `id`, `isDisabled`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-danger`, `--ds-danger-soft`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-opacity-disabled`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-success`, `--ds-success-soft`, `--ds-tabs-count-padding-inline`, `--ds-tabs-count-size`, `--ds-tabs-divider-width`, `--ds-tabs-gap`, `--ds-tabs-indicator-height`, `--ds-target-min`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-warning-soft`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- Several views of the same object (Details, Items, History) where only one is shown at a time.
- Filtering a list into a few named groups that each have their own panel.

#### When not to use

- To pick a value without panels (a view mode, a unit): use `SegmentedControl`.
- To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- For more than about seven tabs, or for steps of a process.

#### Anatomy

```
Tabs                         (root, flex column)
  TabList  aria-label        (role=tablist, 1px bottom line)
    Tab id                   (role=tab; 2px ink underline when selected)
      label
      count                  (optional; neutral text or a toned pill)
      shortcut hint          (optional Kbd, aria-hidden)
  TabPanel id                (role=tabpanel, labelled by its tab)
```

#### Accessibility

- Roles: `tablist` > `tab` (with `aria-selected`, `aria-controls`) and `tabpanel` (`aria-labelledby` the tab).
- Keyboard: `Tab` enters the list once (roving tab stop) and the next `Tab` goes to the panel; `←` / `→` move (and wrap), `Home` / `End` jump. In right-to-left locales the arrows swap. Disabled tabs are skipped.
- Activation: automatic by default. Use `keyboardActivation="manual"` when showing a panel is slow or has side effects, so arrowing across tabs does not trigger work.
- Count: the visible count is part of the tab name ("Orders 12"). With `countLabel` the visible number is hidden from assistive technology and the label is read instead ("Pending 3 pending"). Color never carries the meaning, so a toned count always needs words.
- Shortcut hint: decorative; it does not change the name. Tell users about the shortcut elsewhere (help, tooltip) if it matters.
- Contrast: inactive tab text is `--ds-text-3` on `--ds-bg` (passes). Do not place tabs on a raised or hover surface without checking.
- Focus: accent ring on the tab and on a focused panel. Forced colors: the selected underline uses `Highlight`.
- Reduced motion: only a color transition, neutralized by the base styles.

#### Content rules

- Labels are nouns in sentence case ("Order items"), one or two words.
- Do not repeat the count in the label. `countLabel` says what the number counts ("3 pending").

#### Examples

```tsx
<Tabs defaultSelectedKey="items">
  <TabList aria-label="Order sections">
    <Tab id="details">Details</Tab>
    <Tab id="items" count={12} countTone="warning" countLabel="12 pending">
      Items
    </Tab>
    <Tab id="history" shortcut={['3']}>
      History
    </Tab>
  </TabList>
  <TabPanel id="details">…</TabPanel>
  <TabPanel id="items">…</TabPanel>
  <TabPanel id="history">…</TabPanel>
</Tabs>
```

#### Related components

- Instead, see SegmentedControl: To pick a value without panels (a view mode, a unit): use `SegmentedControl`.
- Instead, see NavItem: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Instead, see Link: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Renders: Kbd, VisuallyHidden

### TabList

> The row of tabs. Name it with `aria-label` (or `aria-labelledby`) so screen readers can
tell several tab lists apart.

Tabs switch between panels of related content on the same page. Built on React Aria `Tabs`, `TabList`, `Tab` and `TabPanel`: one tab stop, arrow keys between tabs, panels linked to their tabs.

- Handoff source: `components/navigation/Tabs.jsx` (TODO `CMP-NAV-01`).

- Import: `import { TabList } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Tabs/Tabs.tsx`
- Stories (Storybook title `Components/Tabs`): Default, ArrowKeys, FocusMovesIntoPanel, ManualActivation, Counts, ShortcutHints, DisabledTab, Controlled, LongLabels, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | The `Tab`s. Each `Tab` needs an `id` that matches a `TabPanel`. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the `tablist` element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `CollectionBase` (@react-types/shared): `items`
- From `CollectionProps` (react-aria-components): `dependencies`
- From `DOMRenderProps` (react-aria-components): `render`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-danger`, `--ds-danger-soft`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-opacity-disabled`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-success`, `--ds-success-soft`, `--ds-tabs-count-padding-inline`, `--ds-tabs-count-size`, `--ds-tabs-divider-width`, `--ds-tabs-gap`, `--ds-tabs-indicator-height`, `--ds-target-min`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-warning-soft`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- Several views of the same object (Details, Items, History) where only one is shown at a time.
- Filtering a list into a few named groups that each have their own panel.

#### When not to use

- To pick a value without panels (a view mode, a unit): use `SegmentedControl`.
- To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- For more than about seven tabs, or for steps of a process.

#### Anatomy

```
Tabs                         (root, flex column)
  TabList  aria-label        (role=tablist, 1px bottom line)
    Tab id                   (role=tab; 2px ink underline when selected)
      label
      count                  (optional; neutral text or a toned pill)
      shortcut hint          (optional Kbd, aria-hidden)
  TabPanel id                (role=tabpanel, labelled by its tab)
```

#### Accessibility

- Roles: `tablist` > `tab` (with `aria-selected`, `aria-controls`) and `tabpanel` (`aria-labelledby` the tab).
- Keyboard: `Tab` enters the list once (roving tab stop) and the next `Tab` goes to the panel; `←` / `→` move (and wrap), `Home` / `End` jump. In right-to-left locales the arrows swap. Disabled tabs are skipped.
- Activation: automatic by default. Use `keyboardActivation="manual"` when showing a panel is slow or has side effects, so arrowing across tabs does not trigger work.
- Count: the visible count is part of the tab name ("Orders 12"). With `countLabel` the visible number is hidden from assistive technology and the label is read instead ("Pending 3 pending"). Color never carries the meaning, so a toned count always needs words.
- Shortcut hint: decorative; it does not change the name. Tell users about the shortcut elsewhere (help, tooltip) if it matters.
- Contrast: inactive tab text is `--ds-text-3` on `--ds-bg` (passes). Do not place tabs on a raised or hover surface without checking.
- Focus: accent ring on the tab and on a focused panel. Forced colors: the selected underline uses `Highlight`.
- Reduced motion: only a color transition, neutralized by the base styles.

#### Content rules

- Labels are nouns in sentence case ("Order items"), one or two words.
- Do not repeat the count in the label. `countLabel` says what the number counts ("3 pending").

#### Examples

```tsx
<Tabs defaultSelectedKey="items">
  <TabList aria-label="Order sections">
    <Tab id="details">Details</Tab>
    <Tab id="items" count={12} countTone="warning" countLabel="12 pending">
      Items
    </Tab>
    <Tab id="history" shortcut={['3']}>
      History
    </Tab>
  </TabList>
  <TabPanel id="details">…</TabPanel>
  <TabPanel id="items">…</TabPanel>
  <TabPanel id="history">…</TabPanel>
</Tabs>
```

#### Related components

- Instead, see SegmentedControl: To pick a value without panels (a view mode, a unit): use `SegmentedControl`.
- Instead, see NavItem: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Instead, see Link: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Instead, see Tab: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Renders: Kbd, VisuallyHidden

### TabPanel

> The content of one tab. `id` must equal the `id` of its `Tab`; the panel is then labelled by
the tab and the tab points to the panel (`aria-controls`). The panel is focusable when it
has no focusable content, so keyboard users can reach it.

Tabs switch between panels of related content on the same page. Built on React Aria `Tabs`, `TabList`, `Tab` and `TabPanel`: one tab stop, arrow keys between tabs, panels linked to their tabs.

- Handoff source: `components/navigation/Tabs.jsx` (TODO `CMP-NAV-01`).

- Import: `import { TabPanel } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Tabs/Tabs.tsx`
- Stories (Storybook title `Components/Tabs`): Default, ArrowKeys, FocusMovesIntoPanel, ManualActivation, Counts, ShortcutHints, DisabledTab, Controlled, LongLabels, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` |  |  | Panel content. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the `tabpanel` element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `AriaTabPanelProps` (react-aria): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `TabPanelProps` (react-aria-components): `shouldForceMount`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-danger`, `--ds-danger-soft`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-opacity-disabled`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-success`, `--ds-success-soft`, `--ds-tabs-count-padding-inline`, `--ds-tabs-count-size`, `--ds-tabs-divider-width`, `--ds-tabs-gap`, `--ds-tabs-indicator-height`, `--ds-target-min`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-warning-soft`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- Several views of the same object (Details, Items, History) where only one is shown at a time.
- Filtering a list into a few named groups that each have their own panel.

#### When not to use

- To pick a value without panels (a view mode, a unit): use `SegmentedControl`.
- To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- For more than about seven tabs, or for steps of a process.

#### Anatomy

```
Tabs                         (root, flex column)
  TabList  aria-label        (role=tablist, 1px bottom line)
    Tab id                   (role=tab; 2px ink underline when selected)
      label
      count                  (optional; neutral text or a toned pill)
      shortcut hint          (optional Kbd, aria-hidden)
  TabPanel id                (role=tabpanel, labelled by its tab)
```

#### Accessibility

- Roles: `tablist` > `tab` (with `aria-selected`, `aria-controls`) and `tabpanel` (`aria-labelledby` the tab).
- Keyboard: `Tab` enters the list once (roving tab stop) and the next `Tab` goes to the panel; `←` / `→` move (and wrap), `Home` / `End` jump. In right-to-left locales the arrows swap. Disabled tabs are skipped.
- Activation: automatic by default. Use `keyboardActivation="manual"` when showing a panel is slow or has side effects, so arrowing across tabs does not trigger work.
- Count: the visible count is part of the tab name ("Orders 12"). With `countLabel` the visible number is hidden from assistive technology and the label is read instead ("Pending 3 pending"). Color never carries the meaning, so a toned count always needs words.
- Shortcut hint: decorative; it does not change the name. Tell users about the shortcut elsewhere (help, tooltip) if it matters.
- Contrast: inactive tab text is `--ds-text-3` on `--ds-bg` (passes). Do not place tabs on a raised or hover surface without checking.
- Focus: accent ring on the tab and on a focused panel. Forced colors: the selected underline uses `Highlight`.
- Reduced motion: only a color transition, neutralized by the base styles.

#### Content rules

- Labels are nouns in sentence case ("Order items"), one or two words.
- Do not repeat the count in the label. `countLabel` says what the number counts ("3 pending").

#### Examples

```tsx
<Tabs defaultSelectedKey="items">
  <TabList aria-label="Order sections">
    <Tab id="details">Details</Tab>
    <Tab id="items" count={12} countTone="warning" countLabel="12 pending">
      Items
    </Tab>
    <Tab id="history" shortcut={['3']}>
      History
    </Tab>
  </TabList>
  <TabPanel id="details">…</TabPanel>
  <TabPanel id="items">…</TabPanel>
  <TabPanel id="history">…</TabPanel>
</Tabs>
```

#### Related components

- Instead, see SegmentedControl: To pick a value without panels (a view mode, a unit): use `SegmentedControl`.
- Instead, see NavItem: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Instead, see Link: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Instead, see Tab: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Renders: Kbd, VisuallyHidden

### Tabs

> Tabs switch between panels of related content. Built on React Aria `Tabs`: one tab stop,
`Left` / `Right` / `Home` / `End` move between tabs, `Tab` moves into the panel.

Selection follows RAC: `selectedKey` / `defaultSelectedKey` / `onSelectionChange`.
`keyboardActivation="manual"` makes the arrow keys only move focus; `Enter` or `Space`
then activates the tab (use it when showing a panel is slow or has side effects).

Tabs switch between panels of related content on the same page. Built on React Aria `Tabs`, `TabList`, `Tab` and `TabPanel`: one tab stop, arrow keys between tabs, panels linked to their tabs.

- Handoff source: `components/navigation/Tabs.jsx` (TODO `CMP-NAV-01`).

- Import: `import { Tabs } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Tabs/Tabs.tsx`
- Stories (Storybook title `Components/Tabs`): Default, ArrowKeys, FocusMovesIntoPanel, ManualActivation, Counts, ShortcutHints, DisabledTab, Controlled, LongLabels, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | A `TabList` followed by one `TabPanel` per tab. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the root element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `AriaTabListProps` (react-aria): `keyboardActivation`
- From `CollectionBase` (@react-types/shared): `disabledKeys`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `SlotProps` (react-aria-components): `slot`
- From `TabListProps` (react-stately): `defaultSelectedKey`, `isDisabled`, `onSelectionChange`, `selectedKey`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-danger`, `--ds-danger-soft`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-caption`, `--ds-lh-small`, `--ds-line`, `--ds-opacity-disabled`, `--ds-radius-pill`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-success`, `--ds-success-soft`, `--ds-tabs-count-padding-inline`, `--ds-tabs-count-size`, `--ds-tabs-divider-width`, `--ds-tabs-gap`, `--ds-tabs-indicator-height`, `--ds-target-min`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-warning`, `--ds-warning-soft`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- Several views of the same object (Details, Items, History) where only one is shown at a time.
- Filtering a list into a few named groups that each have their own panel.

#### When not to use

- To pick a value without panels (a view mode, a unit): use `SegmentedControl`.
- To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- For more than about seven tabs, or for steps of a process.

#### Anatomy

```
Tabs                         (root, flex column)
  TabList  aria-label        (role=tablist, 1px bottom line)
    Tab id                   (role=tab; 2px ink underline when selected)
      label
      count                  (optional; neutral text or a toned pill)
      shortcut hint          (optional Kbd, aria-hidden)
  TabPanel id                (role=tabpanel, labelled by its tab)
```

#### Accessibility

- Roles: `tablist` > `tab` (with `aria-selected`, `aria-controls`) and `tabpanel` (`aria-labelledby` the tab).
- Keyboard: `Tab` enters the list once (roving tab stop) and the next `Tab` goes to the panel; `←` / `→` move (and wrap), `Home` / `End` jump. In right-to-left locales the arrows swap. Disabled tabs are skipped.
- Activation: automatic by default. Use `keyboardActivation="manual"` when showing a panel is slow or has side effects, so arrowing across tabs does not trigger work.
- Count: the visible count is part of the tab name ("Orders 12"). With `countLabel` the visible number is hidden from assistive technology and the label is read instead ("Pending 3 pending"). Color never carries the meaning, so a toned count always needs words.
- Shortcut hint: decorative; it does not change the name. Tell users about the shortcut elsewhere (help, tooltip) if it matters.
- Contrast: inactive tab text is `--ds-text-3` on `--ds-bg` (passes). Do not place tabs on a raised or hover surface without checking.
- Focus: accent ring on the tab and on a focused panel. Forced colors: the selected underline uses `Highlight`.
- Reduced motion: only a color transition, neutralized by the base styles.

#### Content rules

- Labels are nouns in sentence case ("Order items"), one or two words.
- Do not repeat the count in the label. `countLabel` says what the number counts ("3 pending").

#### Examples

```tsx
<Tabs defaultSelectedKey="items">
  <TabList aria-label="Order sections">
    <Tab id="details">Details</Tab>
    <Tab id="items" count={12} countTone="warning" countLabel="12 pending">
      Items
    </Tab>
    <Tab id="history" shortcut={['3']}>
      History
    </Tab>
  </TabList>
  <TabPanel id="details">…</TabPanel>
  <TabPanel id="items">…</TabPanel>
  <TabPanel id="history">…</TabPanel>
</Tabs>
```

#### Related components

- Instead, see SegmentedControl: To pick a value without panels (a view mode, a unit): use `SegmentedControl`.
- Instead, see NavItem: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Instead, see Link: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Instead, see Tab: To move between pages or routes: use `NavItem` in a navigation list, or `Link`s. (`Tab` does accept `href`, but a primary navigation is not a tab list.)
- Renders: Kbd, VisuallyHidden

### Tag

> A mono outlined label for versions, SKUs and filters. Standalone it is static text (with an
optional remove button); inside a `TagGroup` it is a keyboard-navigable item that can be
removed with Backspace or Delete.

A mono outlined label for versions, SKUs and filters. `Tag` is static text on its own (with an optional remove button); inside a `TagGroup` it is an item with keyboard navigation, selection and removal. `TagGroup` is built on React Aria `TagGroup`, `TagList` and `Tag`.

- Import: `import { Tag } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Tag/Tag.tsx`
- Stories (Storybook title `Components/Tag`): Default, Removable, Disabled, LongText, RightToLeft, RemovableGroupStory, GroupStatic, GroupSelectable, GroupWithDisabledTag, GroupEmpty

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | The text of the tag. Plain text, or any node together with `textValue`. |
| `textValue` | `string` |  |  | Plain-text version of the tag. Required when `children` is not a string: it names the tag for screen readers and is used in the name of the remove button ("Remove {textValue}"). |
| `id` | `Key` |  |  | Inside a `TagGroup`: the key of the tag (used by `onRemove`, selection and `disabledKeys`). Outside a group: the DOM `id`. |
| `isDisabled` | `boolean` |  |  | Disables the tag (inside a group: keyboard removal and selection too). |
| `onRemove` | `() => void` |  |  | Standalone tag only: shows a remove button that calls this. Inside a `TagGroup` use the group's `onRemove` instead (it also enables Backspace and Delete on the focused tag). |
| `messages` | `Partial<{ remove: (label: string) => string; }>` |  |  | Per-instance overrides of the built-in messages. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Tag: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `remove(label: string)` | `Remove {label}` | Name of the remove button of a tag: it includes the text of the tag. |

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-2`, `--ds-surface-hover`, `--ds-tag-height`, `--ds-tag-padding-inline`, `--ds-tag-remove-size`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`

#### When to use

- Show an attribute or identifier: `v2.4.0`, `ORD-1048`, `notebook`.
- Show applied filters that the user can remove (`TagGroup` with `onRemove`).
- Let the user toggle filters (`TagGroup` with `selectionMode`).

#### When not to use

- For a status (Shipped, Failed): use `Badge`.
- For a command: use `Button`.
- For choosing one option from a list: use `Select` or `RadioGroup`.

#### Anatomy

```
TagGroup           (grid; optional visible label)
  Label
  TagList          (flex wrap)
    Tag            (row)
      text
      remove button  only when the group has onRemove (24x24 target)
```

#### Accessibility

- A group is a `grid` with one `row` per tag. Arrow keys move between tags (roving focus); the focused tag is the only one in the tab order.
- **Backspace and Delete remove the focused tag** (or all selected tags) when the group has `onRemove`. Keyboard users are told so by a description that React Aria adds to the focused tag.
- **The remove button is named "Remove {text}"** from the message catalog (pt-BR: "Remover {text}"), not just "Remove". The button is also a tab stop after its tag, and is a 24 by 24 pixel target (WCAG 2.5.8).
- After a removal, focus moves to a neighbouring tag (React Aria); handle the empty state with `renderEmptyState` and move focus to something sensible yourself if the whole group disappears.
- Selection is exposed as `aria-selected`, and shown with the accent border and tint (a permitted use of the accent). Selection is never signalled by color alone: the state is announced.
- A standalone `Tag` is plain text. With `onRemove` it contains a real `<button>` (Enter or Space); Backspace and Delete do nothing there because the tag itself is not focusable. Use a `TagGroup` when keyboard removal matters.
- Text is `--ds-text-2` on the page surface; disabled tags are exempt from contrast and carry `aria-disabled`.

#### Content rules

- Short, lowercase or code-like values are fine (`v2.4.0`, `ORD-1048`); filters use the user's own words.
- Write a `textValue` that reads well after "Remove": "Remove notebook".

#### Examples

```tsx
<Tag>v2.4.0</Tag>

<TagGroup label="Product" onRemove={(keys) => setTags((t) => t.filter((x) => !keys.has(x)))}>
  {tags.map((tag) => <Tag key={tag} id={tag}>{tag}</Tag>)}
</TagGroup>
```

#### Related components

- Instead, see Badge: For a status (Shipped, Failed): use `Badge`.
- Instead, see Button: For a command: use `Button`.
- Instead, see Select: For choosing one option from a list: use `Select` or `RadioGroup`.
- Instead, see RadioGroup: For choosing one option from a list: use `Select` or `RadioGroup`.
- Renders: Icon
- Used by: TagInput

### TagGroup

> A group of tags with one tab stop and arrow-key navigation. With `onRemove`, Backspace and
Delete remove the focused tag (or the selected tags) and every tag gets a remove button.
Built on React Aria `TagGroup`.

A mono outlined label for versions, SKUs and filters. `Tag` is static text on its own (with an optional remove button); inside a `TagGroup` it is an item with keyboard navigation, selection and removal. `TagGroup` is built on React Aria `TagGroup`, `TagList` and `Tag`.

- Import: `import { TagGroup } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Tag/Tag.tsx`
- Stories (Storybook title `Components/Tag`): Default, Removable, Disabled, LongText, RightToLeft, RemovableGroupStory, GroupStatic, GroupSelectable, GroupWithDisabledTag, GroupEmpty

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode \| ((item: T) => ReactNode)` | yes |  | Static `Tag` children, or a render function when `items` is given. |
| `label` | `ReactNode` |  |  | Visible label of the group. Without it, give the group an `aria-label` or `aria-labelledby`. |
| `onRemove` | `(keys: Set<Key>) => void` |  |  | Called with the keys of the tags to remove (Backspace, Delete or the remove button). Makes the tags removable. |
| `items` | `Iterable<T>` |  |  | Data for the render function. Each item needs an `id` (or pass `id` to the rendered `Tag`). |
| `renderEmptyState` | `() => ReactNode` |  |  | Content shown when there are no tags (for example "No filters applied"). |
| `className` | `string` |  |  |  |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`, `aria-label`, `aria-labelledby`
- From `AriaTagGroupProps` (react-aria): `escapeKeyBehavior`, `selectionBehavior`, `shouldSelectOnPressUp`
- From `CollectionBase` (@react-types/shared): `disabledKeys`
- From `DOMProps` (@react-types/shared): `id`
- From `GridListProps` (react-aria): `onAction`
- From `MultipleSelection` (@react-types/shared): `defaultSelectedKeys`, `disallowEmptySelection`, `onSelectionChange`, `selectedKeys`, `selectionMode`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-accent`, `--ds-accent-soft`, `--ds-focus-ring`, `--ds-font-mono`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-2`, `--ds-surface-hover`, `--ds-tag-height`, `--ds-tag-padding-inline`, `--ds-tag-remove-size`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-weight-medium`

#### When to use

- Show an attribute or identifier: `v2.4.0`, `ORD-1048`, `notebook`.
- Show applied filters that the user can remove (`TagGroup` with `onRemove`).
- Let the user toggle filters (`TagGroup` with `selectionMode`).

#### When not to use

- For a status (Shipped, Failed): use `Badge`.
- For a command: use `Button`.
- For choosing one option from a list: use `Select` or `RadioGroup`.

#### Anatomy

```
TagGroup           (grid; optional visible label)
  Label
  TagList          (flex wrap)
    Tag            (row)
      text
      remove button  only when the group has onRemove (24x24 target)
```

#### Accessibility

- A group is a `grid` with one `row` per tag. Arrow keys move between tags (roving focus); the focused tag is the only one in the tab order.
- **Backspace and Delete remove the focused tag** (or all selected tags) when the group has `onRemove`. Keyboard users are told so by a description that React Aria adds to the focused tag.
- **The remove button is named "Remove {text}"** from the message catalog (pt-BR: "Remover {text}"), not just "Remove". The button is also a tab stop after its tag, and is a 24 by 24 pixel target (WCAG 2.5.8).
- After a removal, focus moves to a neighbouring tag (React Aria); handle the empty state with `renderEmptyState` and move focus to something sensible yourself if the whole group disappears.
- Selection is exposed as `aria-selected`, and shown with the accent border and tint (a permitted use of the accent). Selection is never signalled by color alone: the state is announced.
- A standalone `Tag` is plain text. With `onRemove` it contains a real `<button>` (Enter or Space); Backspace and Delete do nothing there because the tag itself is not focusable. Use a `TagGroup` when keyboard removal matters.
- Text is `--ds-text-2` on the page surface; disabled tags are exempt from contrast and carry `aria-disabled`.

#### Content rules

- Short, lowercase or code-like values are fine (`v2.4.0`, `ORD-1048`); filters use the user's own words.
- Write a `textValue` that reads well after "Remove": "Remove notebook".

#### Examples

```tsx
<Tag>v2.4.0</Tag>

<TagGroup label="Product" onRemove={(keys) => setTags((t) => t.filter((x) => !keys.has(x)))}>
  {tags.map((tag) => <Tag key={tag} id={tag}>{tag}</Tag>)}
</TagGroup>
```

#### Related components

- Instead, see Badge: For a status (Shipped, Failed): use `Badge`.
- Instead, see Button: For a command: use `Button`.
- Instead, see Select: For choosing one option from a list: use `Select` or `RadioGroup`.
- Instead, see RadioGroup: For choosing one option from a list: use `Select` or `RadioGroup`.
- Renders: Icon
- Used by: TagInput

### TagInput

> A text field that turns what you type into removable tags: `Enter` or a comma adds the
tag, pasting `a, b, c` adds three, `Backspace` on the empty input removes the last one.
Duplicates are ignored with a polite message; `maxTags` and `validateTag` reject with an
error that is read aloud.

Built from `TagGroup` / `Tag` and React Aria `TextField`. The tags are a keyboard-navigable
list (one tab stop; `Shift+Tab` from the input reaches it, `Backspace` or `Delete` on a tag
removes it), the input is a normal text box. The value is the list of tags; with `name` each
tag is submitted as a hidden field.

For choosing from known options use `Combobox`; for filters that are always visible use
`ToggleGroup`.

A text field that turns what you type into removable tags: `Enter` or a comma adds a tag, pasting `a, b, c` adds three, `Backspace` on the empty input removes the last one. Built from `TagGroup` / `Tag` and React Aria `TextField`. The value is the list of tags; with `name` each tag is submitted as a hidden form field.

- TODO `GAP-005`.

- Import: `import { TagInput } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/TagInput/TagInput.tsx`
- Stories (Storybook title `Components/TagInput`): Default, AddWithKeyboard, WithTags, BackspaceRemovesLast, RemoveWithKeyboard, Duplicate, MaxTags, Validation, Invalid, Required, Disabled, ReadOnly, Small, Large, ManyTagsWrap, LongTag, SemicolonDelimiter, Controlled, InForm, Portuguese, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | `readonly string[]` |  |  | The tags (controlled). Pair with `onChange`. |
| `defaultValue` | `readonly string[]` |  |  | The initial tags (uncontrolled). |
| `onChange` | `((tags: string[]) => void)` |  |  | Called with the full list of tags whenever a tag is added or removed. |
| `name` | `string` |  |  | Name used to submit the tags with a form. Each tag is submitted as its own hidden field with this name (read them with `formData.getAll(name)`). The text being typed is never submitted. |
| `form` | `string` |  |  | The `id` of the `<form>` the hidden fields belong to, when the field is outside it. |
| `inputValue` | `string` |  |  | The text in the input, not yet a tag (controlled). Pair with `onInputChange`. |
| `defaultInputValue` | `string` |  |  | The initial text in the input (uncontrolled). |
| `onInputChange` | `((text: string) => void)` |  |  | Called with the text of the input as the user types. |
| `delimiters` | `readonly string[]` |  | `[',']` | Characters that end a tag while typing and split pasted text. `Enter` always adds the tag, and line breaks always split pasted text. Default `[',']`. Pass `[]` to use only `Enter`. |
| `maxTags` | `number` |  |  | Maximum number of tags. Trying to add another shows an error and keeps the text. |
| `validateTag` | `((tag: string) => string \| null)` |  |  | Decides whether a tag may be added. Return a message to reject it ("Use letters and digits only."); return nothing to accept it. The message is shown as the field error and read aloud. It receives the trimmed text. |
| `caseSensitive` | `boolean` |  | `false` | Treat "Notebook" and "notebook" as different tags. Default: they are the same, and the second is ignored. |
| `addOnBlur` | `boolean` |  | `true` | Turns the text left in the input into a tag when the input loses focus. Default `true`. |
| `description` | `ReactNode` |  |  | Helper text under the control. Linked with `aria-describedby`. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text from your own validation, shown while the field is invalid (`isInvalid`). The messages of `validateTag` and `maxTags` take its place while they apply. |
| `placeholder` | `string` |  |  | Text shown while the field has no tags and no text. Never a substitute for the label. |
| `size` | `'sm' \| 'md' \| 'lg'` |  | `'md'` | Control height: `sm` 32px, `md` 40px (default), `lg` 48px. The box grows when tags wrap. |
| `className` | `string` |  |  | Class name for the field root. |
| `inputClassName` | `string` |  |  | Class name for the text `<input>`. |
| `inputRef` | `Ref<HTMLInputElement>` |  |  | Ref to the text `<input>`. The `ref` prop points at the field root. |
| `messages` | `Partial<{ tagsLabel: (fieldLabel?: string) => string; added: (tag: string) => string; addedMany: (count: number) => string; removed: (tag: string) => string; duplicate: (tag: string) => string; duplicates: (count: number) => string; maxReached: (max: number) => string; } & { ...; }>` |  |  | Message overrides for this instance: `tagsLabel`, `added`, `addedMany`, `removed`, `duplicate`, `duplicates`, `maxReached`, `requiredMark`. The remove button of a tag uses the `Tag` messages. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaTextFieldProps` (react-aria): `aria-activedescendant`, `aria-autocomplete`, `aria-controls`, `aria-haspopup`, `enterKeyHint`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `DOMProps` (@react-types/shared): `id`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `TextFieldProps` (react-aria-components): `isInvalid`
- From `TextInputDOMEvents` (@react-types/shared): `onBeforeInput`, `onCompositionEnd`, `onCompositionStart`, `onCompositionUpdate`, `onCopy`, `onCut`, `onInput`, `onPaste`, `onSelect`
- From `TextInputDOMProps` (@react-types/shared): `autoComplete`, `autoCorrect`, `spellCheck`
- From `Validation` (@react-types/shared): `isRequired`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `sm`, `md`, `lg`

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ TagInput: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `tagsLabel(fieldLabel?: string)` | `{fieldLabel?}, added tags` | Name of the list of added tags. `fieldLabel` is the text label of the field, when it has one. |
| `added(tag: string)` | `Added “{tag}”.` | Announced (polite) after one tag is added. |
| `addedMany(count: number)` | `Added 2 tags.` | Announced (polite) after several tags are added at once (paste). |
| `removed(tag: string)` | `Removed “{tag}”.` | Announced (polite) after a tag is removed with Backspace on the empty input. |
| `duplicate(tag: string)` | `“{tag}” is already added.` | Shown and announced (polite) when a typed tag is already in the list and was ignored. |
| `duplicates(count: number)` | `2 duplicate tags were skipped.` | Shown and announced (polite) when several pasted tags were ignored as duplicates. |
| `maxReached(max: number)` | `You can add up to 2 tags.` | Error shown when the user tries to add a tag beyond the maximum. |

#### Design tokens used

`--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-fs-label`, `--ds-lh-label`, `--ds-tag-height`, `--ds-tag-input-gap`, `--ds-tag-input-input-min-width`, `--ds-tag-input-padding-block`, `--ds-tag-input-padding-inline`, `--ds-text-2`, `--ds-text-3`

#### When to use

- Free-form lists the user types: keywords, e-mail recipients, labels, SKUs.
- When the list can grow beyond what you want to show as checkboxes.

#### When not to use

- Choosing from known options: use `Combobox` (or `Select`).
- A fixed set of filters that are always visible: use `ToggleGroup`.
- Showing tags the user cannot edit: use `TagGroup`.

#### Anatomy

```
div (field root)
  Label
  div.control                     (the bordered box, wraps over several rows)
    TagGroup[role=grid] aria-label    (only while there are tags; one row per tag)
      Tag > text + remove button (24x24)
    input[type=text]              (the textbox; named by the Label)
  Description
  FieldError                      (role=alert: validation and maximum)
  div[role=status]                (polite: added, removed, duplicate; visible for a duplicate)
  input[type=hidden] x N          (only with `name`)
```

#### Behavior

| Input                                        | Result                                                                                                          |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `Enter` with text                            | Adds the tag (trimmed), clears the input. Does not submit the form. `Enter` on an empty input submits as usual. |
| A delimiter key (`,`)                        | Same as `Enter`; the character is never typed.                                                                  |
| Paste with delimiters or line breaks         | Adds every piece. Duplicates are skipped; a message counts them. A paste without delimiters is a normal paste.  |
| `Backspace` on an empty input                | Removes the last tag (announced: "Removed “headphones”.").                                                      |
| Duplicate                                    | Ignored, input cleared, polite message "“notebook” is already added." Not an error.                             |
| Beyond `maxTags` / rejected by `validateTag` | Error (`role="alert"`, field invalid), nothing is added, the text stays so it can be fixed.                     |
| Blur with text                               | Adds it (`addOnBlur`).                                                                                          |

#### Accessibility

- The input is a normal `textbox` named by the label. The tags are a `grid` named "Products, added tags" with one `row` per tag (React Aria `TagGroup`): `Shift+Tab` from the input reaches the tags; a row, then its remove button, are tab stops; `←` / `→` move between tags; `Backspace` or `Delete` on a focused tag removes it. After the last tag is removed focus returns to the input.
- Remove buttons are 24x24 and named "Remove notebook" (message `Tag.remove`).
- Additions, removals and duplicates are announced in one polite `role="status"` region; errors are in the field's `role="alert"` message, linked with `aria-describedby`. Only duplicates are also shown as text below the box, so the notice is not color-only; the error is text and the box border turns danger.
- The click target of the whole box focuses the input.
- Contrast: the box border is `--ds-line-control` (3:1) in every state, as in the other fields.

#### Content rules

- Label as a noun phrase ("Products", "Recipients"). Placeholder: an example or an action ("Add a product"), never the label.
- `validateTag` messages say how to fix it: "Enter a complete email address."
- Tags are shown as typed (trimmed); sorting is up to you.

#### Messages (`messages` prop, or `DSProvider messages={{ TagInput: … }}`)

`tagsLabel(fieldLabel?)`, `added(tag)`, `addedMany(count)`, `removed(tag)`, `duplicate(tag)`, `duplicates(count)`, `maxReached(max)`, `requiredMark`. English and `pt-BR` ship with the library. The remove button uses the `Tag` messages.

#### Examples

```tsx
<TagInput label="Products" name="products" value={products} onChange={setProducts} maxTags={10} />

<TagInput
  label="Recipients"
  delimiters={[',', ';']}
  validateTag={(tag) => (tag.includes('@') ? undefined : 'Enter a complete email address.')}
/>
```

#### Related components

- Instead, see Combobox: Choosing from known options: use `Combobox` (or `Select`).
- Instead, see Select: Choosing from known options: use `Combobox` (or `Select`).
- Instead, see ToggleGroup: A fixed set of filters that are always visible: use `ToggleGroup`.
- Instead, see TagGroup: Showing tags the user cannot edit: use `TagGroup`.
- Renders: FieldMessages, Label, Tag, TagGroup

### Text

> Body text on the type scale. It sets size, line height, color tone and an optional mono
face; the element (`as`) carries the meaning. Use `Heading` for headings and `Code` for code.

Body text on the type scale, with a tone, an optional mono face and truncation.

- Import: `import { Text } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Text/Text.tsx`
- Stories (Storybook title `Typography/Text`): Default, Small, Label, Meta_, Caption, Secondary, Tertiary, Success, Warning, Danger, Mono, AsParagraph, Truncated, LongText, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `size` | `'body' \| 'caption' \| 'label' \| 'meta' \| 'small'` |  | `'body'` | Type scale step: `body` 15px, `small` 14px, `label` 13px, `meta` 12px, or `caption` 11.5px. `caption` is always Geist Mono, uppercase by CSS, with extra tracking: write the source text in sentence case. Default `body`. |
| `tone` | `'default' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger'` |  | `'default'` | Text color: `default` (`--ds-text`), `secondary` (`--ds-text-2`, supporting text) or `tertiary` (`--ds-text-3`, hints). Tertiary passes 4.5:1 on every surface, but signals the lowest importance: use it for meta and hints, never for primary content. `success`, `warning` and `danger` are signal colours (4.5:1 on the base surfaces): always pair them with words that carry the meaning, never colour alone. Default `default`. |
| `mono` | `boolean` |  | `false` | Geist Mono with tabular figures, for codes, identifiers, amounts and shortcuts. |
| `truncate` | `boolean` |  | `false` | Keeps the text on one line and cuts it with an ellipsis. Put the full text in `title` or nearby for sighted users. |
| `as` | `'span' \| 'dd' \| 'div' \| 'dt' \| 'em' \| 'figcaption' \| 'label' \| 'legend' \| 'li' \| 'p' \| 'small' \| 'strong'` |  | `'span'` | Element to render. Default `span`, which is safe inside any inline context; use `p` for a paragraph. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `size`: `body`, `caption`, `label`, `meta`, `small`
- `tone`: `default`, `secondary`, `tertiary`, `success`, `warning`, `danger`

#### Design tokens used

`--ds-danger`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-body`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-body`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-lh-small`, `--ds-success`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tracking-caption`, `--ds-warning`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- Paragraphs, supporting lines, labels, counts, metadata and small captions.
- Anywhere a size from the type scale or a secondary tone is needed on plain text.

#### When not to use

- Headings: use `Heading`.
- Code: use `Code`.
- Links: use `Link`. Field labels: use the `Label` of the field.

#### Anatomy

```
span (or the element in `as`)
```

#### Accessibility

- `tertiary` passes 4.5:1 on every surface (TOK-004), but it carries the lowest importance: use it for hints and meta, never for primary content.
- `success`, `warning` and `danger` pass 4.5:1 on bg, surface and raised. The colour only reinforces: the words must carry the meaning ("Select at least one color."), never colour alone. For an error tied to a group of controls use `ErrorText`.
- Truncated text hides content visually: show the full value elsewhere (a `title`, a tooltip, a detail view) when it matters.
- The caption's uppercase is CSS only, so screen readers read the sentence-case source.
- Long unbroken values wrap (`overflow-wrap: break-word`).

#### Content rules

- Sentence case. Numbers, codes and amounts go in `mono`, formatted with `Intl` (see `utils`).

#### Examples

```tsx
<Text as="p">Your order has shipped.</Text>
<Text size="small" tone="secondary">Updated 2 minutes ago</Text>
<Text size="caption" tone="secondary">Shipping</Text>
<Text mono>ORD-1048</Text>
<Text truncate>{longFileName}</Text>
```

#### Related components

- Instead, see Heading: Headings: use `Heading`.
- Instead, see Code: Code: use `Code`.
- Instead, see Link: Links: use `Link`. Field labels: use the `Label` of the field.
- Instead, see Label: Links: use `Link`. Field labels: use the `Label` of the field.

### Textarea

> Multi-line text field built on React Aria `TextField` + `TextArea`. Same contract as `Input`.

Multi-line text field. Same contract as [Input](../Input/Input.md) (label, description, error, states, validation timing from [Field](../Field/Field.md)), plus an aside, auto-growing height and a character count. Built on React Aria `TextField` + `TextArea`.

- Import: `import { Textarea } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Textarea/Textarea.tsx`
- Stories (Storybook title `Components/Textarea`): Default, WithDescription, WithAside, Required, Invalid, Disabled, ReadOnly, AutoGrow, WithCharacterCount, NoResize, LongLabel, Focused, FullWidthInRow

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `description` | `ReactNode` |  |  | Helper text under the control. Linked with `aria-describedby`. |
| `descriptionTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  | Tone of the description: `success`, `warning`, `danger` or `accent` for a live check such as "Matches" or "Over by $5". The text carries the meaning; colour only reinforces it. |
| `errorMessage` | `FieldErrorMessage` |  |  | Error text, shown while the field is invalid and the error is displayed. See `Input`. |
| `aside` | `ReactNode` |  |  | Text on the label line, aligned to the end (for example "Optional" or "Markdown supported"). It is part of the field's description for assistive technology, not of its name. |
| `placeholder` | `string` |  |  | Text shown while the field is empty. Never a substitute for the label. |
| `rows` | `number` |  | `3` | Visible lines before the user types. Default 3. |
| `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` |  | `'vertical'` | Whether the user can drag the corner to resize. Default `vertical`. Ignored with `autoGrow`. |
| `autoGrow` | `boolean` |  | `false` | Grows with its content instead of scrolling. |
| `showCount` | `boolean` |  | `false` | Shows "used / max" on the label line and announces the remaining characters politely once typing pauses. Needs `maxLength`. |
| `fullWidth` | `boolean` |  | `false` | Take the free space of a flex row (an `Inline`): the field grows to fill it and can shrink below its content width. Off by default. In a block context the field already spans the width. |
| `className` | `string` |  |  | Class name for the field root. |
| `textareaClassName` | `string` |  |  | Class name for the `<textarea>` element. |
| `textareaRef` | `Ref<HTMLTextAreaElement>` |  |  | Ref to the `<textarea>` element. The `ref` prop points at the field root. |
| `messages` | `Partial<{ count: (used: string, max: string) => string; remaining: (n: number) => string; over: (n: number) => string; } & { requiredMark: string; }>` |  |  | Message overrides for this instance: `count`, `remaining`, `over`, `requiredMark`. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the field root `<div>`. |
| `label` | `ReactNode` |  |  | Visible label. Prefer it: sighted and assistive technology users see the same name. |
| `aria-label` | `string` |  |  | Accessible name when there is no visible label (for example a search box with an icon). |
| `aria-labelledby` | `string` |  |  | Id of the element that names the field. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `AriaTextFieldProps` (react-aria): `aria-activedescendant`, `aria-autocomplete`, `aria-controls`, `aria-haspopup`, `enterKeyHint`
- From `AriaValidationProps` (@react-types/shared): `aria-errormessage`
- From `DOMProps` (@react-types/shared): `id`
- From `DOMRenderProps` (react-aria-components): `render`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `InputBase` (@react-types/shared): `isDisabled`, `isReadOnly`
- From `InputDOMProps` (@react-types/shared): `form`, `name`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `RACValidation` (react-aria-components): `validationBehavior`
- From `SlotProps` (react-aria-components): `slot`
- From `TextFieldProps` (react-aria-components): `isInvalid`
- From `TextInputDOMEvents` (@react-types/shared): `onBeforeInput`, `onCompositionEnd`, `onCompositionStart`, `onCompositionUpdate`, `onCopy`, `onCut`, `onInput`, `onPaste`, `onSelect`
- From `TextInputDOMProps` (@react-types/shared): `autoComplete`, `autoCorrect`, `maxLength`, `minLength`, `pattern`, `spellCheck`
- From `Validation` (@react-types/shared): `isRequired`, `validate`
- From `ValueBase` (@react-types/shared): `defaultValue`, `onChange`, `value`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Textarea: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `count(used: string, max: string)` | `{used} / {max}` | Visible counter next to the label, for example "12 / 200". Arguments are already formatted. |
| `remaining(n: number)` | `2 characters remaining` | Polite announcement, made once typing pauses. |
| `over(n: number)` | `2 characters over the limit` | Announcement when a controlled value exceeds `maxLength`. |

#### Design tokens used

`--ds-danger`, `--ds-font-mono`, `--ds-fs-meta`, `--ds-lh-meta`, `--ds-space-2`, `--ds-text-3`, `--ds-textarea-padding-block`, `--ds-textarea-padding-inline`

#### When to use

- Notes, comments, descriptions, messages longer than a line.

#### When not to use

- One line of text: `Input`.
- Rich text or Markdown editing: a dedicated editor.

#### Props (key ones)

| Prop                                                      | Notes                                                                                                                    |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `label`, `description`, `descriptionTone`, `errorMessage` | As in `Input`.                                                                                                           |
| `aside`                                                   | Text on the label line, aligned to the end ("Optional", "Markdown supported"). Part of the description, not of the name. |
| `rows`                                                    | Visible lines. Default 3.                                                                                                |
| `resize`                                                  | `none`, `vertical` (default), `horizontal`, `both`.                                                                      |
| `autoGrow`                                                | Grows with its content; the manual resize handle is off.                                                                 |
| `fullWidth`                                               | Take the free space of a flex row such as `Inline` (`flex: 1 1 auto`, can shrink). Off by default.                       |
| `maxLength` + `showCount`                                 | Shows "used / max" on the label line and announces the remaining characters politely.                                    |
| `value` / `defaultValue` / `onChange(value)`              | React Aria naming; `onChange` receives the string.                                                                       |
| `textareaRef` / `ref`                                     | `textareaRef` is the `<textarea>`, `ref` the field root.                                                                 |
| `messages`                                                | `count`, `remaining`, `over`, `requiredMark`.                                                                            |

#### Character count

- The visible counter ("12 / 200", formatted for the locale) is `aria-hidden`: announcing it on every keystroke would drown the user.
- A separate visually hidden `role="status"` (polite) region announces "N characters remaining" once typing has paused for one second. It stays silent until the value changes, and says "N characters over the limit" when a controlled value exceeds `maxLength`.
- Plural forms and the pt-BR text come from `Textarea.messages.ts`. Override `count`, `remaining` and `over` per instance or via `DSProvider messages={{ Textarea: { ... } }}`.
- `showCount` has no effect without `maxLength`. The native `maxLength` stops typing at the limit.

#### Accessibility

- Native `<textarea>` named by its label; `aside` and `description` are in `aria-describedby` (description first, then aside).
- Keyboard: standard text editing; `Enter` inserts a newline; `Tab` leaves the field.
- Auto-grow keeps all content visible (no inner scrollbar), which helps zoom and reflow.

#### Example

```tsx
<Textarea label="Notes" aside="Optional" description="Plain text only." maxLength={500} showCount />
<Textarea label="Message" autoGrow rows={2} isRequired errorMessage="Write a message." />
```

#### Related components

- Instead, see Input: One line of text: `Input`.
- Renders: FieldMessages, Label, VisuallyHidden
- Used by: ApprovalCard, ChatPanel

### Timeline

> A chronological list of events. It is an ordered list; each event has a `<time>`, a title, an
optional description, an optional actor and an optional tone marker. The marker and the line
are decorative: a tone is also stated as hidden text before the title.
Newest events come first by default, the order for dated records.

A chronological list of events: when it happened, what happened, who did it, and an optional detail and tone marker. It is a semantic ordered list, newest event first by default.

- Import: `import { Timeline } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Timeline/Timeline.tsx`
- Stories (Storybook title `Components/Timeline`): Default, OldestFirst, Tones, DateOnly, LongText, SingleEvent, Empty, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly TimelineItem[]` | yes |  | The events. |
| `order` | `'newest-first' \| 'oldest-first' \| 'as-given'` |  | `'newest-first'` | Order of the list: `newest-first` (default, for dated records), `oldest-first`, or `as-given` to keep the order of `items`. |
| `timeZone` | `string` |  |  | IANA time zone used to show date-times ("America/Sao_Paulo"). Defaults to the viewer's zone. |
| `empty` | `ReactNode` |  |  | Rendered instead of the list when `items` is empty (for example an `EmptyState`). |
| `messages` | `Partial<{ accent: string; success: string; warning: string; danger: string; actor: (actor: string) => string; }>` |  |  | Message overrides for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Timeline: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `accent` | `Highlighted` | Visually hidden prefix read before the title of an event with a tone; color and icon alone cannot carry it. |
| `success` | `Success` |  |
| `warning` | `Warning` |  |
| `danger` | `Error` |  |
| `actor(actor: string)` | `By {actor}` | Visible label before the person or system that caused the event. |

#### Design tokens used

`--ds-accent`, `--ds-bg`, `--ds-danger`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-fs-small`, `--ds-lh-label`, `--ds-lh-meta`, `--ds-lh-small`, `--ds-line-control`, `--ds-line-strong`, `--ds-radius-pill`, `--ds-space-1`, `--ds-space-3`, `--ds-success`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-timeline-connector-thickness`, `--ds-timeline-dot-size`, `--ds-timeline-item-gap`, `--ds-timeline-marker-gap`, `--ds-timeline-marker-size`, `--ds-warning`, `--ds-weight-medium`

#### When to use

- The history of a record or a process: status changes, comments, deliveries, audit entries.
- Events that have a time and read as a story, a few lines each.

#### When not to use

- Tabular data that people sort and compare: use `DataTable`.
- The steps of a flow someone is going through now: use `Stepper`.
- The state of a record in a fixed flow: use `StatusSteps`.
- Totals and amounts per line: use `LedgerList`.

#### Anatomy

```
ol[aria-label]
  li[data-tone]
    marker (aria-hidden)         dot (neutral) | icon: accent info, success check, warning triangle, danger circle
    div
      title                      VisuallyHidden tone text ("Success") + title
      meta                       "By <actor>" · <time dateTime>
      description                optional
  connector line                 (CSS pseudo-element, decorative)
```

#### Accessibility

- A real ordered list; each time is a `<time dateTime>` with a machine-readable value, and its text comes from `Intl` for the active locale (never hand-built).
- The tone is not only color and icon: a visually hidden prefix ("Success", "Warning", "Error", "Highlighted", from messages) comes before the title. The marker and the line are `aria-hidden`.
- The list is not interactive, so it has no keyboard behavior of its own; put links or buttons in the `title` or `description` when an event needs an action.
- Text uses `text` and `text-2` (4.5:1 on the page surface). Forced colors: markers and line use system colors.
- Reflow: text wraps (long words break) and the layout is a single column, so it works at 320 px.

#### Content rules

- Title: what happened, past tense, sentence case, no exclamation marks ("Order shipped", "Request approved").
- Description: one short sentence of detail, only when it adds something.
- Actor: a person or system name. The component adds "By".
- Do not repeat the time in the title.

#### Examples

```tsx
<Timeline
  aria-label="Request history"
  items={[
    { id: 'a', time: '2026-10-28T09:15:00Z', title: 'Request created', actor: 'Ana Costa' },
    { id: 'b', time: '2026-10-31T16:05:00Z', title: 'Request approved', tone: 'success' },
  ]}
/>

<Timeline aria-label="Audit log" items={events} order="oldest-first" timeZone="UTC" />
```

#### Related components

- Instead, see DataTable: Tabular data that people sort and compare: use `DataTable`.
- Instead, see Stepper: The steps of a flow someone is going through now: use `Stepper`.
- Instead, see StatusSteps: The state of a record in a fixed flow: use `StatusSteps`.
- Instead, see LedgerList: Totals and amounts per line: use `LedgerList`.
- Renders: Icon, VisuallyHidden

### ToastRegion

> Renders the toasts of a queue. Mount **one** near the app root, inside `DSProvider`, and call
`toast()` from anywhere. Built on React Aria's toast region (isolated in `toast.rac.ts`).

The region is a landmark named "Toast notifications" that `F6` moves into; the timer of every toast
pauses while the pointer is over the region or focus is inside it (WCAG 2.2.1). Toasts stack
at the bottom center of the viewport, above dialogs and below tooltips. While a `Sheet` is open
they move into the free space beside it (or to the top, below its header, on narrow screens), so
they never cover its footer.

A short, temporary message about something that just happened, with an optional action (usually Undo). Mount one `ToastRegion` and call `toast()` from anywhere. Built on React Aria's toast region and queue.

- Handoff source: `components/feedback/Toast` (CMP-FBK-02). Undo recipe: GAP-008 groundwork.

- Import: `import { ToastRegion } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Toast/Toast.tsx`
- Stories (Storybook title `Components/Toast`): AllTones, WithAction, LongMessage, UndoPattern, PausesOnHoverAndFocus, KeyboardRegion

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `queue` | `ToastQueue` |  | `createToastQueue()` | The queue to show. Defaults to the one `toast()` writes to. |
| `messages` | `Partial<{ region: string; dismiss: string; info: string; success: string; warning: string; danger: string; undo: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `className` | `string` |  |  | Class name for the region. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the region element. |

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Toast: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `region` | `Toast notifications` | Accessible name of the region that holds the toasts (a landmark reachable with F6). |
| `dismiss` | `Dismiss notification` | Name of the dismiss button of a toast. |
| `info` | `Information` | Visually hidden prefix that tells screen reader users the kind of toast; the dot alone cannot. |
| `success` | `Success` |  |
| `warning` | `Warning` |  |
| `danger` | `Error` |  |
| `undo` | `Undo` | Label of the Undo action added by `toastWithUndo`. A verb. |

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-sans`, `--ds-fs-small`, `--ds-lh-small`, `--ds-line-strong`, `--ds-radius-lg`, `--ds-radius-pill`, `--ds-shadow-overlay`, `--ds-sheet-width-lg`, `--ds-sheet-width-md`, `--ds-sheet-width-sm`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-success`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-toast-dot-size`, `--ds-toast-max-width`, `--ds-toast-min-height`, `--ds-toast-offset`, `--ds-topbar-h`, `--ds-warning`, `--ds-z-toast`

#### When to use

- Feedback for an action that finished: "Order #1051 created", "3 items archived".
- Reversible actions, with **Undo**.

#### When not to use

- A state that stays on the page ("Scheduled maintenance"): use `Alert`.
- A field error: use the field's error message.
- Anything the user must read to proceed: use `Dialog` or `Alert`. A toast disappears.
- The only place an essential result is shown: toasts can be missed.

#### Anatomy

```
ToastRegion          role=region, aria-label "Toast notifications", landmark (F6); fixed, bottom center; z toast
  Toast              role=alertdialog (React Aria), raised surface, strong line, radius lg, overlay shadow
    dot              decorative, colored by tone
    message          "Success: " (visually hidden) + text
    Button           optional action ("Undo")
    IconButton       "Dismiss notification"
```

#### API

```tsx
// once, near the root, inside DSProvider
<ToastRegion />;

// anywhere
import { toast } from 'loui-ds';
toast('Draft saved'); // info
toast.success('Order #1051 created');
toast.warning('Stock is low for 2 items');
toast.danger('Payment failed', { timeout: null }); // stays until dismissed
toast.success('3 items archived', { action: { label: 'Undo', onPress: restore } });
```

| Option    | Type                                   | Default | Notes                                                   |
| --------- | -------------------------------------- | ------- | ------------------------------------------------------- |
| `tone`    | `info \| success \| warning \| danger` | `info`  | Feedback components use `info`, not `neutral`/`accent`. |
| `action`  | `{ label, onPress }`                   |         | One action. The toast closes after `onPress`.           |
| `timeout` | `number \| null`                       | `5000`  | Milliseconds. `null` = until dismissed.                 |
| `onClose` | `() => void`                           |         | Timeout, dismiss or action.                             |

`toastWithUndo(message, { onUndo })` shows a toast with a localized Undo action (see below). `toast(...)` returns a key; `toast.close(key)` and `toast.clear()` remove toasts. `useToast()` returns the same stable object. `createToastQueue()` / `createToastApi(queue)` and `<ToastRegion queue>` give an isolated queue (tests, a second region). `ToastRegion` also takes `messages` and `className`. At most four toasts show at once; the rest wait.

#### Default timeout: 5000 ms

The handoff closed toasts after 3.6 s, which is too short to read a sentence and reach Undo (WCAG 2.2.1 Timing Adjustable). The default is 5 s **and** the timer pauses while the pointer is over the toast region or focus is inside it, so a keyboard or slow reader can always finish. Use `timeout: null` for failures the user has to act on.

#### Accessibility

- The region is a landmark named "Toast notifications". **F6** moves focus into it (and back), so Undo is keyboard reachable. React Aria registers a region as a landmark only if it is mounted with its first toast, so `ToastRegion` renders nothing while the queue is empty and mounts the region when a toast arrives.
- Each toast is announced by React Aria's toast semantics. The tone is spoken as a prefix ("Success: ...", "Error: ...") from messages; the colored dot is decorative and `aria-hidden`.
- Pause on hover and on focus within the region; the timer resumes on leave or blur.
- Dismiss button named from messages ("Dismiss notification"); action is a real `Button`.
- Layer `--ds-z-toast` (58): above dialogs, below tooltips. Bottom center keeps it clear of side panels (Sidebar). While a `Sheet` is open (GAP-052) the region moves into the free space beside it by reading `data-ds-sheet` on the document (`:root:has(...)`, CSS only, SSR-safe), so stacked toasts never cover the sheet footer; below 768px the sheet fills the width and toasts go to the top, under the sheet header. Keyboard (F6), pause on hover/focus and reduced motion are unchanged.
- Reduced motion: the 150 ms fade-in is removed. Forced colors: border and dot use `CanvasText`.
- `UNSTABLE_*` isolation: all React Aria `UNSTABLE_Toast*` imports live in `toast.rac.ts`. Renaming or stabilizing them is a one-file change.

#### Content rules

- Past tense, short, no exclamation marks: "Order #1051 created", "3 items archived".
- Action: a verb ("Undo"). No "Close" button text; the dismiss control is an icon.
- Do not repeat what is already visible on the page.

#### The undo pattern (recipe)

"Reversible actions never ask; they offer Undo" (AGENTS.md section 5). Do the action immediately, then toast with an Undo that reverses it:

```tsx
function archiveOrder(order: Order) {
  const previous = order.status;
  setStatus(order.id, 'archived'); // 1. do it now
  toast.success(`Order #${order.number} archived`, {
    // 2. say so, past tense
    action: {
      label: 'Undo',
      onPress: () => setStatus(order.id, previous), // 3. reverse it from the saved state
    },
  });
}
```

Rules:

1. Save what you need to reverse **before** acting; Undo must not depend on state that has moved on.
2. If the change was already sent to a server, Undo sends the inverse change; do not delay the real action to "wait for Undo".
3. For deletes, soft-delete or keep the record for the Undo window plus a margin, and keep the confirmation dialog (`ConfirmDialog`), then show the toast. For example: confirm, delete, toast "Order #1048 deleted" with Undo.
4. Irreversible actions get a `ConfirmDialog`, not a toast.
5. Inside components, `useUndoable` wraps steps 1 to 3 and adds a deferred commit with failure handling. In plain modules (stores, services, handlers outside React) use `toastWithUndo`, below.

##### Undo outside React: `toastWithUndo`

`toast(..., { action })` has no default label, and a hook cannot run in a plain module. `toastWithUndo` is a non-hook helper that takes the **Undo** label from the message catalogue (`Toast` key `undo`) instead of every call site repeating the word:

```ts
import { toastWithUndo } from 'loui-ds';

export function archiveOrder(order: Order) {
  const previous = order.status;
  orders.setStatus(order.id, 'archived'); // do it now
  toastWithUndo(`Order #${order.number} archived`, {
    onUndo: () => orders.setStatus(order.id, previous),
  });
}
```

| Option               | Type                | Default        | Notes                                             |
| -------------------- | ------------------- | -------------- | ------------------------------------------------- |
| `onUndo`             | `() => void`        | required       | Reverses the change. The toast closes afterwards. |
| `tone`               | `info               | success        | warning`                                          | `success` | Not `danger`: a failure is not undoable. |
| `locale`             | `string`            | see below      | BCP 47 tag for the label.                         |
| `messages`           | `{ undo?: string }` |                | Per-call override; wins over `locale`.            |
| `toast`              | `ToastApi`          | shared `toast` | An isolated queue (tests, a second region).       |
| `groupKey`           | `string`            |                | Replaces the previous undo toast of the same key. |
| `timeout`, `onClose` |                     |                | As in `toast()`.                                  |

`groupKey` (GAP-053) is for quick repeated actions of one kind (four toggles in a grid): a new toast with the same key closes the previous one, so only the latest change offers Undo and earlier ones are final. It does not offer "Undo 4 changes": the changes may be on different records and made in any order, so one Undo could not safely reverse them all. Different keys still stack. `useUndoable` takes the same `groupKey` on the action. It returns the toast key, like `toast()`. Outside React there is no context, so the label is resolved in this order: `messages.undo`, then `locale`, then the label the mounted `ToastRegion` publishes for the same queue (the `DSProvider` locale, a `messages={{ Toast: { undo } }}` provider override or the region's `messages` prop), then English. With a mounted region inside `DSProvider` you normally pass nothing. The helper does not defer anything and has no commit step; use `useUndoable` when you need that.

#### Related components

- Instead, see Alert: A state that stays on the page ("Scheduled maintenance"): use `Alert`.
- Instead, see Dialog: Anything the user must read to proceed: use `Dialog` or `Alert`. A toast disappears.
- Renders: Button, IconButton, VisuallyHidden

### Toggle

> A button that stays pressed: it switches one setting on or off (bold text, a filter, "show
archived"). Built on React Aria `ToggleButton`: a native `<button>` with `aria-pressed`,
toggled by `Enter` and `Space`.

Use it for an independent on/off choice that applies at once. For a setting inside a form
use `Switch` or `Checkbox`; for several related toggles use `ToggleGroup`; for one value out
of a few use `SegmentedControl`.

A button that stays pressed: it switches one setting on or off (bold text, a filter, "show archived") and applies it at once. A native `<button>` with `aria-pressed`, built on React Aria `ToggleButton`. Looks like `Button` (`secondary` and `ghost`), with a clear pressed state.

- TODO `GAP-005`.

- Import: `import { Toggle } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Toggle/Toggle.tsx`
- Stories (Storybook title `Components/Toggle`): Default, Pressed, Ghost, GhostPressed, Small, Large, WithLeadingIcon, IconOnly, IconOnlyWithTooltip, Disabled, DisabledPressed, KeyboardToggle, Controlled, LongLabel, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` |  |  | Label: a short noun or verb in sentence case ("Bold", "Show archived"). |
| `leading` | `ReactNode` |  |  | Node before the label, usually `<Icon size="sm" />`. Decorative; the label names the toggle. |
| `aria-label` | `string` |  |  | Replaces the accessible name when the visible label is not enough. Rarely needed. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the toggle. |
| `icon` | `LucideIcon` |  |  | The icon to draw: one of the curated set (for example `StarIcon`). Decorative inside the button. |
| `label` | `string` |  |  | Accessible name of an icon-only toggle, required. Name what the toggle controls, not what it looks like and not its state ("Bold", "Show archived"): the pressed state is announced separately. |
| `tooltip` | `boolean \| ToggleTooltipOptions` |  |  | Shows `label` in a `Tooltip` on hover and keyboard focus. Pass `true`, or an object to add a shortcut or change the side. The `label` stays the accessible name. |
| `id` | `string` |  |  | Inside a `ToggleGroup`: the value of this toggle in the group's `value` (required there, unique in the group). Standalone: the DOM id. |
| `variant` | `'secondary' \| 'ghost'` |  |  | Visual style, as for `Button`. `secondary` (default) has a border; `ghost` has none at rest. Inside a `ToggleGroup` it defaults to the group's `variant`. |
| `size` | `'sm' \| 'md' \| 'lg'` |  |  | Height token: `sm` 32px, `md` 40px (default), `lg` 48px. Inside a `ToggleGroup` it defaults to the group's `size`. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLButtonElement>` |  |  | Ref to the underlying `<button>` element. |

##### Inherited props

- From `AriaBaseButtonProps` (react-aria): `aria-controls`, `aria-disabled`, `aria-expanded`, `aria-haspopup`, `aria-pressed`, `preventFocusOnPress`
- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `ButtonProps` (react-aria): `isDisabled`
- From `FocusableDOMProps` (@react-types/shared): `excludeFromTabOrder`
- From `FocusableProps` (@react-types/shared): `autoFocus`
- From `FocusEvents` (@react-types/shared): `onBlur`, `onFocus`, `onFocusChange`
- From `HoverEvents` (@react-types/shared): `onHoverChange`, `onHoverEnd`, `onHoverStart`
- From `KeyboardEvents` (@react-types/shared): `onKeyDown`, `onKeyUp`
- From `PressEvents` (@react-types/shared): `onClick`, `onPress`, `onPressChange`, `onPressEnd`, `onPressStart`, `onPressUp`
- From `SlotProps` (react-aria-components): `slot`
- From `ToggleButtonProps` (react-aria): `defaultSelected`, `isSelected`, `onChange`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `secondary`, `ghost`
- `size`: `sm`, `md`, `lg`

#### Design tokens used

`--ds-accent`, `--ds-control-h-lg`, `--ds-control-h-md`, `--ds-control-h-sm`, `--ds-duration`, `--ds-ease`, `--ds-focus-ring`, `--ds-font-sans`, `--ds-fs-body`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-body`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-strong`, `--ds-opacity-disabled`, `--ds-radius-md`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-space-5`, `--ds-surface-hover`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-weight-medium`

#### When to use

- One independent on/off choice in a toolbar or filter bar: Bold, Show archived, Only mine.
- An icon-only on/off control (Favorite, Pin) with a required `label`.

#### When not to use

- A setting that is saved with a form: use `Switch` or `Checkbox`.
- Several related toggles that share a value: use `ToggleGroup`.
- One value out of a few options (View: List, Board): use `SegmentedControl`.
- An action that does something once: use `Button`.

#### Anatomy

```
button[aria-pressed]
  leading   (optional, decorative)
  label     (or a single icon when icon-only)
```

#### Accessibility

- Semantics: `<button aria-pressed="true|false">`. Inside a single-selection `ToggleGroup` it is a `radio` with `aria-checked`.
- Keyboard: `Tab` focuses; `Space` and `Enter` toggle.
- The pressed state is shown by a brighter border, a raised fill and ink text, never by color alone. Focus is the accent border and ring.
- Icon-only toggles need a `label` that names what the toggle controls, not its state: the pressed state is announced by the browser. The icon is decorative.
- Targets are at least 32px (`sm`). Forced colors: the pressed toggle gets a `Highlight` border and an underline.

#### Content rules

- Label with a short noun or verb phrase in sentence case: "Bold", "Show archived". Do not change the label when the state changes ("Hide archived" would be read as the opposite of the state).

#### Examples

```tsx
<Toggle isSelected={showArchived} onChange={setShowArchived}>
  Show archived
</Toggle>

<Toggle icon={StarIcon} label="Favorite" tooltip variant="ghost" />
```

#### Related components

- Instead, see Switch: A setting that is saved with a form: use `Switch` or `Checkbox`.
- Instead, see Checkbox: A setting that is saved with a form: use `Switch` or `Checkbox`.
- Instead, see ToggleGroup: Several related toggles that share a value: use `ToggleGroup`.
- Instead, see SegmentedControl: One value out of a few options (View: List, Board): use `SegmentedControl`.
- Instead, see Button: An action that does something once: use `Button`.
- Renders: Icon, Tooltip
- Used by: ResponseFeedback

### ToggleGroup

> A row (or column) of related `Toggle`s that share one value: the list of pressed `id`s.

With the default `multiple` selection the toggles are independent (bold, italic, underline;
or a set of filters) and the group is a `toolbar`. With `single` selection it behaves like
a radio group that can also be empty.

`ToggleGroup` vs `SegmentedControl`: a `SegmentedControl` is one value of one setting (View:
List, Board), exactly one option is always selected. A `ToggleGroup` is a set of on/off
choices where none, one or several are on.

Built on React Aria `ToggleButtonGroup`: one tab stop, arrow keys move between toggles (they
stop at the ends), `Space` and `Enter` toggle the focused one.

A row (or column) of related `Toggle`s that share one value: the list of pressed `id`s. With the default `multiple` selection the toggles are independent (bold, italic, underline; a set of filters). With `single` selection at most one is pressed. Built on React Aria `ToggleButtonGroup`.

- TODO `GAP-005`.

- Import: `import { ToggleGroup } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/ToggleGroup/ToggleGroup.tsx`
- Stories (Storybook title `Components/ToggleGroup`): Default, Preselected, Ghost, Small, Large, Vertical, IconOnly, SingleSelection, DisabledToggle, DisabledGroup, KeyboardSelection, Controlled, Wrapping, RightToLeft, Focused

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | yes |  | The `Toggle` children. Each needs an `id` that is unique in the group. |
| `aria-label` | `string` |  |  | Accessible name of the group ("Text formatting"). Required: name this or use `aria-labelledby`. |
| `aria-labelledby` | `string` |  |  | Id of the element that names the group. |
| `selectionMode` | `'single' \| 'multiple'` |  | `'multiple'` | `multiple` (default): any number of toggles can be pressed, independently (text formatting, filters); the group is a toolbar. `single`: at most one is pressed; the group is a radio group. To pick exactly one value of a setting prefer `SegmentedControl`. |
| `value` | `readonly string[]` |  |  | The `id`s of the pressed toggles (controlled). Pair with `onChange`. |
| `defaultValue` | `readonly string[]` |  |  | The `id`s of the toggles that start pressed (uncontrolled). |
| `onChange` | `(value: string[]) => void` |  |  | Called with the `id`s of all pressed toggles after the user presses or releases one. |
| `disallowEmptySelection` | `boolean` |  |  | Keeps at least one toggle pressed. Pointless in `multiple` mode unless you want that rule. |
| `orientation` | `'horizontal' \| 'vertical'` |  | `'horizontal'` | Layout and arrow keys: `horizontal` (default, `←` `→`) or `vertical` (`↑` `↓`). |
| `variant` | `'secondary' \| 'ghost'` |  |  | Visual style handed down to every `Toggle` that does not set its own. |
| `size` | `'sm' \| 'md' \| 'lg'` |  |  | Size handed down to every `Toggle` that does not set its own. |
| `className` | `string` |  |  |  |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the group element. |

##### Inherited props

- From `AriaLabelingProps` (@react-types/shared): `aria-describedby`, `aria-details`
- From `ToggleGroupProps` (react-stately): `isDisabled`
- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Variants, sizes and tones

- `variant`: `secondary`, `ghost`
- `size`: `sm`, `md`, `lg`

#### Design tokens used

`--ds-space-2`

#### ToggleGroup or SegmentedControl

|           | `SegmentedControl`                           | `ToggleGroup`                                                    |
| --------- | -------------------------------------------- | ---------------------------------------------------------------- |
| Meaning   | One value of one setting (View: List, Board) | Independent on/off choices (Bold, Italic; filters)               |
| Selection | Exactly one option, always                   | None, one or several (`multiple`), or none/one                   |
| Role      | `radiogroup` of `radio`                      | `toolbar` of `button[aria-pressed]` (`radiogroup` when `single`) |
| Value     | `string`                                     | `string[]`                                                       |
| Content   | `options` array with optional counts         | `Toggle` children, text or icon-only                             |

Rule of thumb: if choosing one option makes the others "not selected" and one must always be on, use `SegmentedControl`. If each choice can stand alone, use `ToggleGroup`. Use `single` here only when "nothing selected" is meaningful (for example an optional filter).

#### When to use

- Text formatting (Bold, Italic), list markers, or a small set of filters that combine.

#### When not to use

- A single on/off choice: use `Toggle`.
- Choosing one value of a setting: use `SegmentedControl`.
- A long list of filters: use `CheckboxGroup` or a `Select`/`Combobox` with multiple selection.

#### Anatomy

```
div[role=toolbar] aria-label       (or role=radiogroup when single)
  button[aria-pressed]             (one `Toggle` per choice, each with an id)
```

#### Accessibility

- Semantics: `multiple` is a `toolbar` (a group of buttons with `aria-pressed`); `single` is a `radiogroup` of `radio` buttons. The group needs an accessible name (enforced by the types).
- Keyboard: one tab stop; `←` / `→` (`↑` / `↓` when vertical) move focus and stop at the ends (React Aria does not wrap); `Space` and `Enter` press the focused toggle. Disabled toggles are skipped.
- Pressed state is shown by border, fill and ink text, not by color alone.
- Icon-only toggles need a `label`.

#### Content rules

- Group name: a noun phrase ("Text formatting", "Filters"). Toggle labels: one word or a short phrase in sentence case.

#### Examples

```tsx
<ToggleGroup aria-label="Text formatting" value={marks} onChange={setMarks}>
  <Toggle id="fav" icon={StarIcon} label="Favorite" />
  <Toggle id="pin" icon={StarIcon} label="Pinned" />
</ToggleGroup>

<ToggleGroup aria-label="Order filters" defaultValue={['mine']}>
  <Toggle id="mine">Only mine</Toggle>
  <Toggle id="late">Late</Toggle>
</ToggleGroup>
```

#### Related components

- Instead, see Toggle: A single on/off choice: use `Toggle`.
- Instead, see SegmentedControl: Choosing one value of a setting: use `SegmentedControl`.
- Instead, see CheckboxGroup: A long list of filters: use `CheckboxGroup` or a `Select`/`Combobox` with multiple selection.
- Instead, see Select: A long list of filters: use `CheckboxGroup` or a `Select`/`Combobox` with multiple selection.
- Instead, see Combobox: A long list of filters: use `CheckboxGroup` or a `Select`/`Combobox` with multiple selection.

### ToolCallList

> The steps of a multi-step agent run as an ordered list of `ToolCallStep`. Use it under the
message the run belongs to; each step opens its own details.

One step of an agent run: the tool it called, whether it is running, succeeded or failed, how long it took and, on request, what went in and out. `ToolCallList` shows a multi-step run. Import both from `loui-ds/patterns`.

- Import: `import { ToolCallList } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/ToolCallStep/ToolCallList.tsx`
- Stories (Storybook title `Patterns/ToolCallStep`): Default, Running, Failed, Expanded, WithoutDetails, LongName, RightToLeft, MultiStepRun

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `steps` | `readonly ToolCallListStep[]` | yes |  | The steps of the run, in the order they happened. |
| `aria-label` | `string` |  |  | Accessible name of the list. Defaults to "Steps"; say which run it is ("Steps of the order check"). |
| `messages` | `Partial<{ running: string; succeeded: string; failed: string; input: string; output: string; error: string; finishedSucceeded: (name: string) => string; finishedFailed: (name: string) => string; listLabel: string; }>` |  |  | Override the built-in messages for this instance (also applied to every step). |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ ToolCallStep: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `running` | `Running` | Visible status text of a step. |
| `succeeded` | `Succeeded` |  |
| `failed` | `Failed` |  |
| `input` | `Input` | Labels of the detail blocks, and the accessible names of their code blocks. |
| `output` | `Output` |  |
| `error` | `Error` | Label of the output block when the step failed. |
| `finishedSucceeded(name: string)` | `{name} succeeded` | Polite announcement when a running step finishes. |
| `finishedFailed(name: string)` | `{name} failed` |  |
| `listLabel` | `Steps` | Accessible name of a ToolCallList. |

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-danger-line`, `--ds-duration`, `--ds-ease`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-line`, `--ds-radius-lg`, `--ds-space-1`, `--ds-success`, `--ds-surface`, `--ds-surface-row-hover`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tool-call-step-gap`, `--ds-tool-call-step-list-gap`, `--ds-tool-call-step-padding-block`, `--ds-tool-call-step-padding-inline`, `--ds-tracking-caption`

#### When to use

- Under an assistant message, to show what the agent did before it answered ("search_orders", "draft_reply").
- A run log where the owner wants to check why the agent answered as it did.

#### When not to use

- Progress of a long job with a known number of steps: use `StatusSteps` or `Progress`.
- Something the owner has to approve: use `ApprovalCard`.

#### Anatomy

```
div (ToolCallStep)
  h{headingLevel} > button   chevron · status icon + text · name (mono) · duration (mono)
  details (when open)        "Input" label + code block · "Output" or "Error" label + code block
  status                     visually hidden live region
ol (ToolCallList)            one li per step
```

Without `input` and `output` the header is plain text and there is nothing to open.

#### Accessibility

- The header is a button inside a heading (`aria-expanded`, `aria-controls`); `Enter` and `Space` toggle it.
- Color never carries the status: the text "Running", "Succeeded" or "Failed" is always visible, with an icon.
- When a running step finishes, a polite live region says "search_orders succeeded" or "search_orders failed" once. A step that is already finished on first render is silent.
- Code blocks that overflow become labelled, keyboard-scrollable regions ("Input", "Output", "Error").
- Reduced motion and forced colors are handled.

#### Content rules

- Tool names are identifiers: show them as the agent calls them, in mono.
- Put the error text in `output` when a step fails, and say how to fix it when you can.
- Do not put secrets, tokens or customer data in `input` or `output`.

#### Example

```tsx
<ToolCallList
  aria-label="Steps of the order check"
  steps={[
    {
      stepId: 's1',
      name: 'search_orders',
      status: 'succeeded',
      durationMs: 1240,
      input: '{ "customer": "C-204" }',
      output: '{ "count": 3 }',
    },
    { stepId: 's2', name: 'draft_reply', status: 'running' },
  ]}
/>
```

#### Related components

- Instead, see StatusSteps: Progress of a long job with a known number of steps: use `StatusSteps` or `Progress`.
- Instead, see Progress: Progress of a long job with a known number of steps: use `StatusSteps` or `Progress`.
- Instead, see ApprovalCard: Something the owner has to approve: use `ApprovalCard`.

### ToolCallStep

> One step of an agent run: the tool it called, whether it is running, succeeded or failed, how
long it took and, on request, what went in and out.

With `input` or `output` the header is a button that opens the details (`aria-expanded`,
`aria-controls`), inside a heading so the steps appear in the outline. Without them it is
plain text. The status is text plus an icon, never color alone. When a running step finishes,
a polite live region says so once; a step that is already finished on first render is silent.

One step of an agent run: the tool it called, whether it is running, succeeded or failed, how long it took and, on request, what went in and out. `ToolCallList` shows a multi-step run. Import both from `loui-ds/patterns`.

- Import: `import { ToolCallStep } from 'loui-ds/patterns';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/patterns/ToolCallStep/ToolCallStep.tsx`
- Stories (Storybook title `Patterns/ToolCallStep`): Default, Running, Failed, Expanded, WithoutDetails, LongName, RightToLeft, MultiStepRun

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` | yes |  | Name of the tool or step ("search_orders"). Shown in mono; it is the name of the details button. |
| `status` | `'running' \| 'succeeded' \| 'failed'` | yes |  | `running` (spinner), `succeeded` or `failed`. The status is always shown as text next to its icon. |
| `durationMs` | `number` |  |  | How long the step took, in milliseconds. Omit while it is running. |
| `input` | `ReactNode` |  |  | What the tool was called with. A string is shown in a code block; pass nodes for anything richer. With `input` or `output` the step gets a details button. |
| `output` | `ReactNode` |  |  | What the tool returned, or the error text when `status` is `failed`. Same rules as `input`. |
| `isExpanded` | `boolean` |  |  | Controlled state of the details. |
| `defaultExpanded` | `boolean` |  | `false` | Initial state of the details when uncontrolled. Default closed. |
| `onExpandedChange` | `(isExpanded: boolean) => void` |  |  | Called when the details open or close. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `4` | Heading level of the step header (`h1` to `h6`). Default `4`. |
| `messages` | `Partial<{ running: string; succeeded: string; failed: string; input: string; output: string; error: string; finishedSucceeded: (name: string) => string; finishedFailed: (name: string) => string; listLabel: string; }>` |  |  | Override the built-in messages for this instance. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ ToolCallStep: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `running` | `Running` | Visible status text of a step. |
| `succeeded` | `Succeeded` |  |
| `failed` | `Failed` |  |
| `input` | `Input` | Labels of the detail blocks, and the accessible names of their code blocks. |
| `output` | `Output` |  |
| `error` | `Error` | Label of the output block when the step failed. |
| `finishedSucceeded(name: string)` | `{name} succeeded` | Polite announcement when a running step finishes. |
| `finishedFailed(name: string)` | `{name} failed` |  |
| `listLabel` | `Steps` | Accessible name of a ToolCallList. |

#### Design tokens used

`--ds-accent`, `--ds-danger`, `--ds-danger-line`, `--ds-duration`, `--ds-ease`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-fs-meta`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-line`, `--ds-radius-lg`, `--ds-space-1`, `--ds-success`, `--ds-surface`, `--ds-surface-row-hover`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tool-call-step-gap`, `--ds-tool-call-step-list-gap`, `--ds-tool-call-step-padding-block`, `--ds-tool-call-step-padding-inline`, `--ds-tracking-caption`

#### When to use

- Under an assistant message, to show what the agent did before it answered ("search_orders", "draft_reply").
- A run log where the owner wants to check why the agent answered as it did.

#### When not to use

- Progress of a long job with a known number of steps: use `StatusSteps` or `Progress`.
- Something the owner has to approve: use `ApprovalCard`.

#### Anatomy

```
div (ToolCallStep)
  h{headingLevel} > button   chevron · status icon + text · name (mono) · duration (mono)
  details (when open)        "Input" label + code block · "Output" or "Error" label + code block
  status                     visually hidden live region
ol (ToolCallList)            one li per step
```

Without `input` and `output` the header is plain text and there is nothing to open.

#### Accessibility

- The header is a button inside a heading (`aria-expanded`, `aria-controls`); `Enter` and `Space` toggle it.
- Color never carries the status: the text "Running", "Succeeded" or "Failed" is always visible, with an icon.
- When a running step finishes, a polite live region says "search_orders succeeded" or "search_orders failed" once. A step that is already finished on first render is silent.
- Code blocks that overflow become labelled, keyboard-scrollable regions ("Input", "Output", "Error").
- Reduced motion and forced colors are handled.

#### Content rules

- Tool names are identifiers: show them as the agent calls them, in mono.
- Put the error text in `output` when a step fails, and say how to fix it when you can.
- Do not put secrets, tokens or customer data in `input` or `output`.

#### Example

```tsx
<ToolCallList
  aria-label="Steps of the order check"
  steps={[
    {
      stepId: 's1',
      name: 'search_orders',
      status: 'succeeded',
      durationMs: 1240,
      input: '{ "customer": "C-204" }',
      output: '{ "count": 3 }',
    },
    { stepId: 's2', name: 'draft_reply', status: 'running' },
  ]}
/>
```

#### Related components

- Instead, see StatusSteps: Progress of a long job with a known number of steps: use `StatusSteps` or `Progress`.
- Instead, see Progress: Progress of a long job with a known number of steps: use `StatusSteps` or `Progress`.
- Instead, see ApprovalCard: Something the owner has to approve: use `ApprovalCard`.
- Renders: Code, Icon, Spinner, VisuallyHidden

### Tooltip

> An ink-style hint for a control, built on React Aria `TooltipTrigger` and `Tooltip`.

It opens on hover (after a delay) and on keyboard focus, closes with `Escape` (WCAG 1.4.13),
stays open while the pointer is over it, and describes the trigger through `aria-describedby`.
A tooltip is a supplement: the trigger must already have its own accessible name.

A short, ink-style hint for a control. Built on React Aria `TooltipTrigger` and `Tooltip`.

- Handoff source: `components/feedback/Tooltip` (CMP-FBK-04).

- Import: `import { Tooltip } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Tooltip/Tooltip.tsx`
- Stories (Storybook title `Components/Tooltip`): Default, Open, WithShortcut, Bottom, Start, End, LongText, OnIconButton, Disabled

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes |  | The element the tooltip describes. It must be focusable and built on React Aria, such as `Button`, `IconButton` or `Link`, so the tooltip opens on keyboard focus as well as hover. |
| `content` | `ReactNode` | yes |  | Short text, a few words. It is linked to the trigger with `aria-describedby`, so it must add detail only: never put the only copy of essential information in a tooltip, because touch users cannot hover and the text is not shown until the trigger is focused. |
| `shortcut` | `string` |  |  | Keyboard shortcut shown after the text in mono type ("⌘K"). Pair it with `aria-keyshortcuts` on the trigger. |
| `placement` | `'top' \| 'bottom' \| 'start' \| 'end'` |  | `'top'` | Side of the trigger, `top` by default. `start` and `end` follow the writing direction. |
| `delay` | `number` |  | `500` | Milliseconds before opening on hover. Default 500. Focus opens it immediately. |
| `closeDelay` | `number` |  | `0` | Milliseconds before closing after the pointer leaves. Default 0. |
| `isDisabled` | `boolean` |  |  | Never opens when `true`, for example while the trigger is disabled. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  |  | Initial open state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called when the tooltip opens or closes. |
| `className` | `string` |  |  | Class name for the tooltip bubble. |
| `ref` | `Ref<HTMLDivElement>` |  |  | Ref to the tooltip bubble. |

#### Design tokens used

`--ds-duration`, `--ds-ease`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-caption`, `--ds-fs-label`, `--ds-lh-caption`, `--ds-lh-label`, `--ds-primary-bg`, `--ds-primary-fg`, `--ds-primary-fg-muted`, `--ds-radius-sm`, `--ds-space-1`, `--ds-space-2`, `--ds-tooltip-max-width`, `--ds-weight-medium`, `--ds-weight-regular`

#### When to use

- Name or add a shortcut to an icon-only control ("Add order", with `N`).
- Explain a truncated label, in a few words.

#### When not to use

- Essential information (an error, a requirement, a price). **A tooltip is never the only source of essential information**: touch users cannot hover, and the text is not shown until the trigger is focused or hovered.
- Interactive content (links, buttons, forms): use `Popover`.
- A long explanation: put it in the page, or use a `Popover`.

#### Anatomy

```
TooltipTrigger
  trigger            Button | IconButton | Link   (focusable, React Aria based)
  Tooltip            role=tooltip, primary background, label type, radius sm
    content          text
    shortcut         optional, mono caption, --ds-primary-fg-muted
```

#### Accessibility

- Role `tooltip`, linked to the trigger with `aria-describedby` while open. The trigger keeps its own accessible name.
- Opens on **keyboard focus and hover**, closes on blur, pointer leave or `Escape` (WCAG 1.4.13: dismissible). The pointer can move onto the tooltip without closing it (hoverable), and it stays until dismissed (persistent).
- Placement is collision-aware.
- Contrast: `--ds-primary-fg` on `--ds-primary-bg`; the shortcut uses `--ds-primary-fg-muted` (at least 4.5:1 on the ink surface).
- Reduced motion: the 150 ms fade is disabled. Forced colors: a `CanvasText` border is drawn.
- Layer: `--ds-z-tooltip`, the top of the stack.

#### Content rules

- Sentence case, no final period for a fragment, no exclamation marks.
- Do not repeat a visible label; add the shortcut or the missing detail.

#### Examples

```tsx
<Tooltip content="Add order" shortcut="N">
  <IconButton label="Add order" icon={PlusIcon} />
</Tooltip>
```

`IconButton` also takes a `tooltip` prop that does this for you.

#### Related components

- Instead, see Popover: Interactive content (links, buttons, forms): use `Popover`.
- Used by: IconButton, Toggle

### TopBar

> The page header: a title with an optional subtitle, or a breadcrumb trail, and an actions
slot. It is a `header` element, `--ds-topbar-h` (64px) high, with a bottom divider. It does
not stick by itself; position it in your layout.

The page header: a title with an optional subtitle, or a breadcrumb trail, and a slot for actions. A `header` element, 64px high (`--ds-topbar-h`), with a bottom divider.

- Handoff source: `components/layout/TopBar.jsx` (TODO `CMP-LAY-02`).

- Import: `import { TopBar } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/TopBar/TopBar.tsx`
- Stories (Storybook title `Components/TopBar`): Default, WithSubtitle, WithPrimaryAction, WithContent, WithBreadcrumb, HeadingLevel2, LongTitle, RightToLeft

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` |  |  | The title of the page or section. Rendered as a heading (see `headingLevel`). Ignored when `breadcrumb` is set: the trail then names the page and the page supplies its own `h1`. |
| `subtitle` | `ReactNode` |  |  | One short line under the title (a count, a date, an environment). Not used with `breadcrumb`. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | `1` | Heading level of the title, `1` by default (one `h1` per page). |
| `breadcrumb` | `readonly BreadcrumbItem[]` |  |  | A breadcrumb trail shown instead of the title. |
| `children` | `ReactNode` |  |  | Free content next to the title, for example a `Badge` or a `SegmentedControl`. |
| `actions` | `ReactNode` |  |  | Actions at the end of the bar. Put the single primary action of the screen last, as a `Button variant="primary"` with its shortcut as a `Kbd` in `trailing`. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### Design tokens used

`--ds-bg`, `--ds-font-sans`, `--ds-fs-heading`, `--ds-fs-meta`, `--ds-lh-heading`, `--ds-lh-meta`, `--ds-line-subtle`, `--ds-space-1`, `--ds-space-2`, `--ds-space-4`, `--ds-text`, `--ds-text-2`, `--ds-top-bar-padding-inline`, `--ds-topbar-h`, `--ds-weight-semibold`

#### When to use

- At the top of the content area of an app shell, next to the `Sidebar`.
- To hold the single primary action of the screen, at the top right, with its keyboard shortcut.

#### When not to use

- For the heading of a card or section: use `Card` or a heading.
- For a floating or sticky toolbar: position this component in your layout instead.

#### Accessibility

- A `header` that is not inside `main`, `section` or `article` is the page's banner landmark. Use at most one banner per page; inside a section it is a plain group.
- The title is a real heading. A breadcrumb replaces it, so keep a page-level `h1` elsewhere in that case.
- The title wins the space: content next to it (`children`, such as badges) wraps to a second line before the title truncates, and the bar grows taller. A title truncates with an ellipsis only when it alone is wider than the bar. The actions never shrink or move out of the bar; on narrow screens keep the primary action and put the others in a `Menu`.
- The primary action is a `Button variant="primary"` with its shortcut as a `Kbd` in `trailing`. Register the shortcut with `useHotkey`; `Kbd` only displays it.
- Height is a minimum, so a 200% text zoom grows the bar instead of clipping it.

#### Content rules

- Titles are nouns in sentence case ("Orders"). Subtitles give context: a count, a date, an environment.
- One primary action per screen, a verb plus object: "Create order".

#### Examples

```tsx
<TopBar
  title="Orders"
  subtitle="1,248 orders"
  actions={
    <Button variant="primary" trailing={<Kbd keys={['N']} />}>
      Create order
    </Button>
  }
/>

<TopBar breadcrumb={[{ label: 'Orders', href: '/orders' }, { label: 'ORD-1048' }]} />
```

#### Related components

- Instead, see Card: For the heading of a card or section: use `Card` or a heading.
- Renders: Breadcrumb

### Tour

> A step-by-step onboarding tour. Each step is a non-modal popover (React Aria `Popover` with
`isNonModal`) anchored to an element, with a title, a short text, a "Step 2 of 5" counter and
Skip, Back and Next or Done buttons. The page stays interactive; there is no scrim.

Focus moves into each step as it appears (the step is a named dialog, so a screen reader
announces its title). `Escape` skips the tour. When the tour ends, focus returns to the element
that had it before the tour opened, normally the button that started it.

Use a `Tooltip` for a hint on one control, and a `Popover` for interactive content. A tour is
for a few steps shown once; do not use it to hold documentation.

Step-by-step onboarding hints anchored to elements of the page. Each step is a non-modal popover (React Aria `Popover` with `isNonModal`) with a title, a short text, a "Step 2 of 5" counter and Skip, Back and Next or Done buttons. Generic: it lives in the core entry point.

- Import: `import { Tour } from 'loui-ds';`
- Status: experimental (do not use in recipes until stable)
- Source: `src/components/Tour/Tour.tsx`
- Stories (Storybook title `Components/Tour`): Default, FirstStep, MiddleStep, LastStep, AboveTarget, KeyboardOnly

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `steps` | `readonly TourStep[]` | yes |  | The steps, in order. Each points at one element through `target`. |
| `step` | `number` |  |  | Zero-based index of the current step (controlled). Pair with `onStepChange`. |
| `defaultStep` | `number` |  | `0` | Initial step when uncontrolled. Default `0`. |
| `onStepChange` | `(step: number) => void` |  |  | Called when the user moves to another step. |
| `isOpen` | `boolean` |  |  | Controlled open state. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` |  | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(isOpen: boolean) => void` |  |  | Called with `false` when the tour is finished or skipped. |
| `onComplete` | `() => void` |  |  | Called when the user presses Done on the last step. `onOpenChange(false)` follows. |
| `onSkip` | `() => void` |  |  | Called when the user skips the tour, with `Skip tour` or `Escape`. `onOpenChange(false)` follows. |
| `placement` | `'bottom' \| 'bottom left' \| 'bottom right' \| 'bottom start' \| 'bottom end' \| 'top' \| 'top left' \| 'top right' \| 'top start' \| 'top end' \| 'left' \| 'left top' \| 'left bottom' \| 'start' \| 'start top' \| 'start bottom' \| 'right' \| 'right top' \| 'right bottom' \| 'end' \| 'end top' \| 'end bottom'` |  | `'bottom start'` | Side and alignment relative to the target. Default `bottom start`. Flips on collision. |
| `messages` | `Partial<{ progress: (current: number, total: number) => string; back: string; next: string; done: string; skip: string; }>` |  |  | Per-instance overrides of the built-in messages. |
| `className` | `string` |  |  | Class name for the step surface. |
| `ref` | `Ref<HTMLElement>` |  |  | Ref to the step surface. |

#### Messages (i18n)

Locales shipped: en, pt-BR. Override per instance with the `messages` prop or globally with `<DSProvider messages={{ Tour: { ... } }}>`.

| Key | English default | Notes |
| --- | --- | --- |
| `progress(current: number, total: number)` | `Step 2 of 2` | Progress text of a step, such as "Step 2 of 5". |
| `back` | `Back` | Goes to the previous step. |
| `next` | `Next` | Goes to the next step. |
| `done` | `Done` | Finishes the tour on the last step. |
| `skip` | `Skip tour` | Ends the tour before the last step. |

#### Design tokens used

`--ds-duration`, `--ds-ease`, `--ds-font-mono`, `--ds-font-sans`, `--ds-fs-heading`, `--ds-fs-label`, `--ds-fs-small`, `--ds-lh-heading`, `--ds-lh-label`, `--ds-lh-small`, `--ds-line-strong`, `--ds-radius-lg`, `--ds-shadow-overlay`, `--ds-space-1`, `--ds-space-2`, `--ds-space-3`, `--ds-space-4`, `--ds-surface-raised`, `--ds-text`, `--ds-text-2`, `--ds-text-3`, `--ds-tour-arrow-size`, `--ds-tour-padding`, `--ds-tour-width`, `--ds-weight-semibold`

#### When to use

- Guiding new users through the interface with a few onboarding hints (three to six steps) that introduce a screen.
- Pointing at controls that are not obvious from their label.

#### When not to use

- A hint on one control: `Tooltip`.
- Interactive content anchored to a button (filters, a small form): `Popover`.
- Documentation or long explanations: link to help instead.
- A task the user must finish before going on: `Dialog` or `Sheet`.

#### Anatomy

```
Popover (non-modal, anchored to step.target, z popover, overlay shadow)
  OverlayArrow
  Dialog (role=dialog, named by the title)
    Heading        step title
    content        step text (--ds-text-2)
    footer         "Step 2 of 5" (mono) ... Skip tour (ghost) · Back · Next | Done (primary)
```

The primary button is Next, or Done on the last step. Skip is hidden on the last step, Back on the first.

#### Accessibility

- Each step is a `dialog` named by its title. It is non-modal: the page is not inert, there is no scrim, nothing is hidden from assistive technology.
- Focus moves into each step as it appears (the dialog itself, so a screen reader reads its title; the next `Tab` reaches Skip, Back and Next). Pressing Next or Back mounts the next step and moves focus to it, so focus never lands on a removed button.
- While a step is open, `Tab` and `Shift+Tab` cycle through the step's buttons (React Aria contains focus in the dialog); `Escape` skips the tour and is the keyboard way out. A pointer press elsewhere on the page does not end it, and the page stays visible and readable (no scrim, not inert).
- When the tour ends, focus returns to the element that had focus when the tour opened (normally the button that started it); for a tour that is open on first render, to the target of the current step if it is focusable. If the consumer closes a controlled tour from outside, focus is left where the user put it.
- The target is scrolled into view (`block: nearest`) when its step appears. The step is positioned against the target and flips when it does not fit; the arrow points at the target.
- The fade-in is removed under `prefers-reduced-motion`. Visuals are calm: raised surface, strong line and the overlay shadow only; accent is used only for focus rings.
- Because the step is rendered in a portal, it comes last in the Tab order of the page: the user reaches it by the focus that moves into it, not by tabbing from the target.

#### Content rules

- Title: the name of the thing, in sentence case ("Filters"). Text: one or two sentences saying what it does, with no exclamation marks or emoji.
- Button labels come from the message catalog: Back, Next, Done, Skip tour.

#### Examples

```tsx
const search = useRef<HTMLButtonElement>(null);
const filters = useRef<HTMLButtonElement>(null);
const [open, setOpen] = useState(false);

<>
  <Button onPress={() => setOpen(true)}>Start tour</Button>
  <Button ref={search}>Search</Button>
  <Button ref={filters}>Filters</Button>
  <Tour
    isOpen={open}
    onOpenChange={setOpen}
    steps={[
      { target: search, title: 'Search', content: 'Find any item by name or code.' },
      { target: filters, title: 'Filters', content: 'Narrow the list by status or date.' },
    ]}
  />
</>;
```

#### Related components

- Instead, see Tooltip: A hint on one control: `Tooltip`.
- Instead, see Popover: Interactive content anchored to a button (filters, a small form): `Popover`.
- Instead, see Dialog: A task the user must finish before going on: `Dialog` or `Sheet`.
- Instead, see Sheet: A task the user must finish before going on: `Dialog` or `Sheet`.
- Renders: Button

### VisuallyHidden

> Hides content visually while keeping it available to assistive technology.
Use it for text alternatives that sighted users do not need.

Hides content visually while keeping it in the accessibility tree. It renders a `span` (or the element given by `as`) with the standard "screen reader only" clipping, so the text is read aloud and found by assistive technology but takes no space on screen.

- Import: `import { VisuallyHidden } from 'loui-ds';`
- Status: stable
- Source: `src/components/VisuallyHidden/VisuallyHidden.tsx`
- Stories (Storybook title `Primitives/VisuallyHidden`): Default, AsHeading

#### Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `as` | `ElementType` |  | `span` | Element to render. Defaults to `span`. |

##### Inherited props

- Standard DOM attributes, ARIA attributes and event handlers; other attributes and `ref` go to the root element.

#### When to use

- A text alternative for an icon-only control when a `label` prop is not available (for example the name of a custom control).
- A heading or landmark label that sighted users do not need because the layout already implies it.
- Extra context for a repeated link or button ("Edit" followed by a hidden "order ORD-1048").

#### When not to use

- To hide content from everyone: use the `hidden` attribute or conditional rendering.
- To hide content from assistive technology only: use `aria-hidden="true"`.
- For a skip link that appears on focus: use `SkipLink`.
- For text that sighted keyboard users need to see: render it visibly.

#### Anatomy

```
span.root   (or as="h2", "div", ...)
  clip: rect(0 0 0 0); position: absolute; 1px box; overflow: hidden
```

#### Accessibility

- The content stays in the accessibility tree and in the reading order; place it where it should be read.
- Do not put interactive elements inside: a focusable element that cannot be seen is a focus-visibility failure (WCAG 2.4.7).
- Write the text as you would write visible copy: sentence case, no emoji, no decorative punctuation.

#### Content rules

- Keep it short and specific ("Close dialog", not "Click here to close the dialog window").
- Do not repeat what the visible label already says.

#### Examples

```tsx
<button type="button">
  <span aria-hidden="true">x</span>
  <VisuallyHidden>Close dialog</VisuallyHidden>
</button>

<VisuallyHidden as="h2">Order summary</VisuallyHidden>
```

#### Related components

- Instead, see SkipLink: For a skip link that appears on focus: use `SkipLink`.
- Used by: ActionList, AddCard, Alert, ApprovalCard, Banner, CardLink, Chart, ChatPanel, CommandPalette, DataTable, FileUpload, Kbd, Legend, Link, MatrixGrid, NavItem, ResponseFeedback, SegmentedControl, ShortcutsHelp, StackedBar, StatusSteps, Stepper, Tab, TabList, TabPanel, Tabs, Textarea, Timeline, ToastRegion, ToolCallStep

---

## Hooks and utilities

> Hooks, locale-aware utilities and message helpers exported from `loui-ds`. Money is an integer in minor units with an ISO 4217 code (ADR-0006).

### Hooks

#### useControllableState

Controlled/uncontrolled state for the `value` / `defaultValue` / `onValueChange`
convention (AGENTS.md section 9). Thin wrapper over react-stately's `useControlledState`,
which also warns in development when a component switches between modes.

```tsx
const [value, setValue] = useControllableState({ value: props.value, defaultValue: props.defaultValue ?? '', onChange: props.onValueChange });
```

```ts
useControllableState<T>({ value, defaultValue, onChange, }: UseControllableStateOptions<T>): [T, (value: T) => void]
```

#### useDSLocale

Returns the active locale (BCP 47 tag) set by `DSProvider`; `en-US` without a provider.

```ts
useDSLocale(): string
```

#### useHotkey

Runs `handler` when a single key combo is pressed.

- `combo`: modifiers joined with `+` and one key, e.g. `Mod+K`, `Shift+/`, `Alt+N`, `Escape`.
  `Mod` is Command on macOS and Control elsewhere.
- Ignores events from editable fields (unless `allowInEditable`), IME composition,
  key auto-repeat (unless `allowRepeat`) and events another handler already prevented.

This is deliberately small. A shortcut registry with conflict detection and a help
overlay is a separate task (GAP-004).

```ts
useHotkey(combo: string, handler: (event: KeyboardEvent) => void, { enabled, scope, allowInEditable, allowRepeat, preventDefault, platform, }?: UseHotkeyOptions): void
```

#### useHotkeys

Registers keyboard shortcuts in the registry (see `HotkeyProvider`) for as long as the
component is mounted.

- `keys`: `Mod+K`, `F2`, `N`, `1`, `Shift+/`, `Escape`. `Mod` is Command on macOS and Control
  elsewhere.
- Ignores editable fields (`allowInEditable`), IME composition, auto-repeat (`allowRepeat`),
  events another handler already prevented and, for page-level shortcuts, focus inside an open
  dialog or menu (`allowInOverlay`).
- Only one named scope is active at a time (`useHotkeyScope`); shortcuts of other scopes wait.
- In development, registering the same combo twice in one scope logs a warning; the most
  recent registration wins.
- `description` and `group` make a shortcut appear in `useRegisteredHotkeys`, the
  command palette and `ShortcutsHelp`.

Handlers may close over props and state: the latest handler always runs. The array can be
created inline on each render.

```ts
useHotkeys(definitions: readonly HotkeyDefinition[]): void
```

#### useHotkeyScope

Makes `name` the active scope while the component is mounted (and `isActive`): shortcuts
registered with `scope: name` fire and `global` ones stop, until the component unmounts.
Scopes stack: the most recently mounted one wins. Use it in the body of a panel, a wizard or
an editor that has its own shortcuts. Dialogs do not need it for page shortcuts: those are
already ignored while focus is inside an open dialog.

```ts
useHotkeyScope(name: string, { isActive }?: UseHotkeyScopeOptions): void
```

#### useMediaQuery

Subscribes to a CSS media query. SSR-safe: on the server (and during hydration)
it returns `defaultValue` (`false` unless given), then the real value after hydration.

Prefer CSS media queries for styling; use this only when behavior (not appearance) depends on the query.

```ts
useMediaQuery(query: string, defaultValue?: boolean): boolean
```

#### useMessages

Returns a component's messages for the active locale.

```ts
useMessages<M extends MessageSet>(componentKey: string, catalog: MessageCatalog<M>, overrides?: MessageOverrides): M
```

#### usePrefersReducedMotion

True when the user asks the OS for reduced motion (`prefers-reduced-motion: reduce`).

```ts
usePrefersReducedMotion(): boolean
```

#### useRegisteredHotkeys

The shortcuts that have a `description`, in registration order, for a help dialog or a
command list. By default only those that can fire now (active scope). Updates when
shortcuts mount, unmount or the active scope changes. Empty during server rendering.

```ts
useRegisteredHotkeys({ includeInactive, }?: UseRegisteredHotkeysOptions): readonly RegisteredHotkey[]
```

#### useToast

Hook form of `toast`, for components that prefer a hook. It returns the same stable object,
so it is safe in dependency arrays.

```ts
useToast(): ToastApi
```

#### useUndoable

Undo, don't confirm (AGENTS.md section 5): applies a reversible action immediately, shows a
toast with an **Undo** button, then either reverts it (Undo) or commits it (the toast times
out or is dismissed).

- `apply` runs now; the screen updates at once.
- Undo calls `revert`. Closing or timing out calls the optional async `commit`; if that
  fails, the change is reverted and an error toast stays until dismissed.
- The timer lives in the toast, so it pauses on hover and focus (WCAG 2.2.1) and the commit
  waits for it. A pending commit still runs if the component that started it unmounts.
- Mount one `ToastRegion` near the app root.

Use it for reversible actions (archive, mark as done, change status). Deleting still asks
for a confirmation first (`ConfirmDialog`); the Undo toast follows it.

Deferring the commit means a closed tab loses a pending change. When that matters, persist in
`apply` and make `revert` send the inverse change instead (omit `commit`).

```ts
useUndoable({ toast, messages: overrides, }?: UseUndoableOptions): UseUndoableResult
```

### Utilities and constants

#### chartAverage

The arithmetic mean of chart values, for an `average` reference line:
`referenceLines={[{ kind: 'average', label: 'Average', value: chartAverage(data) }]}`.

Accepts numbers or chart data (`{ value }`). Non-finite entries are ignored; with nothing
left to average (or the sum overflows) the result is `0`. The result is never `NaN`.

```ts
chartAverage(values: readonly (number | { readonly value: number; })[]): number
```

#### compareText

Compares two strings alphabetically for `locale`; usable as an `Array.prototype.sort` comparator.

```ts
compareText(a: string, b: string, locale: string): number
```

#### contrastRatio

WCAG contrast ratio between two hex colors, from `1` (identical) to `21` (black on white). Order does not matter.

```ts
contrastRatio(a: string, b: string): number
```

#### createTextCollator

Collator for alphabetical order as the product requires (AGENTS.md section 5, rule 5b):
accent- and case-insensitive (`sensitivity: 'base'`) with natural number order
(`numeric: true`, so `Item 2` sorts before `Item 10`). The instance is shared
and cached per locale; do not mutate it.

```ts
createTextCollator(locale: string): Intl.Collator
```

#### createToastApi

Builds the `toast()` function for a queue.

```ts
createToastApi(queue: ToastQueue): ToastApi
```

#### createToastQueue

Creates an independent queue, for tests or for a second region. Most apps use `toast`.

```ts
createToastQueue(): ToastQueue
```

#### daysBetween

Whole days from `isoA` to `isoB` (positive when `isoB` is later). Uses UTC
date math, so daylight-saving changes cannot produce 23- or 25-hour "days".
Invalid input throws in development and returns `NaN` in production.

```ts
daysBetween(isoA: ISODate, isoB: ISODate): number
```

#### DEFAULT_LOCALE

Default locale.

```ts
"en-US" | "pt-BR"
```

#### DEFAULT_TOAST_TIMEOUT

Default time a toast stays on screen, in milliseconds. The handoff used 3.6 s, which is too
short to read a sentence and press Undo (WCAG 2.2.1 Timing Adjustable); 5 s plus pause on
hover and focus lets keyboard and slow readers finish.

```ts
5000
```

#### defineMessages

Declares a component's catalog. Identity function that type-checks that
`pt-BR` has exactly the same keys and signatures as `en`.

```ts
defineMessages<M extends MessageSet>(catalog: { readonly en: M; readonly "pt-BR": NoInfer<M>; readonly [locale: string]: NoInfer<M> | undefined; }): MessageCatalog<M>
```

#### dueStatus

Urgency of a due date: overdue (`< 0` days) is `danger`, due within a week
(`0` to `7`) is `warning`, later is `neutral`. The visible text always comes
from messages (color is never the only signal, AGENTS.md section 5).

```ts
dueStatus(dueISO: ISODate, todayISO: ISODate): DueStatus
```

#### formatCurrency

Formats money held as an integer in minor units (ADR-0006):
`formatCurrency(123456, 'USD', 'en-US')` is `$1,234.56`.

The amount is passed to `Intl` as an exact decimal string, so there is no
floating-point drift. Non-integer or unsafe amounts throw in development
(a sign of a unit bug at the call site) and are rounded in production.

```ts
formatCurrency(minorUnits: number, currency: string, locale: string, options?: FormatCurrencyOptions): string
```

#### formatDate

Formats an ISO date for `locale`. Formatting happens in UTC, so the day never
shifts with the viewer's time zone. Invalid input throws in development and
is returned unchanged in production.

`formatDate('2026-10-31', 'en-US', 'medium')` is `Oct 31, 2026`.

```ts
formatDate(iso: ISODate, locale: string, style?: DateStyle): string
```

#### formatNumber

Formats a decimal number for `locale` (`1234.5` becomes `1,234.5` in `en-US`).

```ts
formatNumber(value: number, locale: string, options?: FormatNumberOptions): string
```

#### formatPercent

Formats a ratio as a percentage: `0.256` becomes `26%` in `en-US`.
Pass `maximumFractionDigits` for more precision.

```ts
formatPercent(ratio: number, locale: string, options?: Omit<FormatNumberOptions, "unit" | "unitDisplay">): string
```

#### formatRelativeDays

Relative day label from `Intl.RelativeTimeFormat` with `numeric: 'auto'`:
`-1` is `yesterday`, `0` is `today`, `1` is `tomorrow`, `3` is `in 3 days`.
`days` must be an integer (throws in development, rounded in production).

```ts
formatRelativeDays(days: number, locale: string): string
```

#### getCurrencyDigits

Number of minor-unit digits of a currency (2 for USD/BRL, 0 for JPY, 3 for KWD),
read from `Intl` so we never keep our own table.

```ts
getCurrencyDigits(currency: string, locale: string): number
```

#### getInitials

Initials of a person's name: the first letter of the first and of the last word
(`Ana Maria da Silva` gives `AS`), or one letter for a single word. Uses `Intl.Segmenter`,
so combined characters stay whole, and upper-cases with the locale rules (`i` in `tr`).

```ts
getInitials(name: string, locale: string): string
```

#### getItemRange

The 1-based range of items on `page`, or `null` when there are no items.

```ts
getItemRange(page: number, pageSize: number, total: number): { from: number; to: number; } | null
```

#### getPageCount

Number of pages for `total` items shown `pageSize` at a time (at least 1).

```ts
getPageCount(total: number, pageSize: number): number
```

#### getPageItems

Which page buttons to show, with ellipses for the pages that are left out.

Up to 7 pages all of them are listed. Beyond that the first page, the last page, the current
page and its two neighbours are listed, and a gap between two of them becomes an ellipsis.
A gap that hides exactly one page shows that page instead (an ellipsis for a single page
would be wider than the page it hides). `current` is clamped into `1..pageCount`; a
`pageCount` below 1 is treated as 1.

```
getPageItems(1, 10)  // 1 2 3 4 5 6 7 8 9 10 collapses to: 1 2 … 10
getPageItems(5, 10)  // 1 … 4 5 6 … 10
```

```ts
getPageItems(current: number, pageCount: number): PageItem[]
```

#### getSourceElementId

The DOM id of one source of a list. `Citation` builds the same id from `listId` and `sourceId`.

```ts
getSourceElementId(listId: string, sourceId: string): string
```

#### highlightMatch

Splits `text` into matched and unmatched segments for highlighting, ignoring case
and accents. The segments always concatenate back to `text` exactly, and a match
keeps any combining marks attached to its last letter. All occurrences are returned.

`highlightMatch('Crème brûlée', 'creme')` gives `[{ text: 'Crème', match: true }, { text: ' brûlée', match: false }]`.

```ts
highlightMatch(text: string, query: string): HighlightSegment[]
```

#### hotkeyKeys

The parts of a combo in display order, ready for `Kbd`'s `keys`: `'Mod+K'` gives
`['Mod', 'K']`, `'Shift+/'` gives `['Shift', '/']`. Returns `[]` for a malformed combo (never throws).

```ts
hotkeyKeys(combo: string): string[]
```

#### HotkeyProvider

Optional root provider for the shortcut registry. Without it `useHotkeys` uses one shared
registry for the whole page, which is enough for most apps; add the provider to isolate the
shortcuts of a subtree (micro frontends, tests, Storybook) or to pin the platform.

Place it inside `DSProvider` and above the `CommandPalette` and `ShortcutsHelp` it feeds.

```ts
HotkeyProvider({ children, platform }: HotkeyProviderProps): React.JSX.Element
```

#### HotkeyRegistry

The store behind `HotkeyProvider`, `useHotkeys` and `useRegisteredHotkeys`. One `keydown`
listener on `document` is attached while at least one shortcut is registered. Framework
independent so it can be tested without React.

```ts
typeof HotkeyRegistry
```

#### iconNames

Kebab-case names of the curated set with the use each icon is meant for. Source of the
allow-list in the component manifest; keep it in sync with the exports above (tested).

```ts
{ readonly 'arrow-down': "Descending sort, move down"; readonly 'arrow-left': "Back, previous page"; readonly 'arrow-right': "Forward, next step"; readonly 'arrow-up': "Ascending sort, move up"; readonly archive: "Archive an item (reversible, with Undo); not for delete"; readonly bell: "Notifications and alerts entry point"; readonly bot: "An AI agent as an actor, for example an agent avatar or a bot-authored message"; readonly calendar: "Date fields and date pickers"; readonly check: "Done, selected, checkbox mark"; readonly 'chevron-down': "Collapsed disclosure, select trigger, menu button"; readonly 'chevron-left': "Previous month or page (use the directional prop so it mirrors in RTL)"; readonly 'chevron-right': "Next month or page, submenu, breadcrumb separator (directional)"; readonly 'chevron-up': "Expanded disclosure"; readonly 'chevrons-up-down': "Sortable column, select trigger with many options"; readonly 'circle-alert': "Error and danger status"; readonly 'circle-check': "Success status"; readonly 'circle-x': "Failed status, clear input"; readonly ellipsis: "More actions (overflow menu)"; readonly 'external-link': "Link that opens in a new tab"; readonly filter: "Filter a list or table (opens filter controls)"; readonly info: "Neutral information status"; readonly link: "Copy or insert a link, linked records"; readonly loader: "Loading glyph (static); animated loading uses Spinner"; readonly message: "Messages, chat and comments, for example a conversational agent"; readonly menu: "Opens the navigation menu (hamburger), for example the app shell nav toggle"; readonly minus: "Remove one, indeterminate checkbox"; readonly pencil: "Edit an item or a field in place"; readonly plus: "Add, create"; readonly printer: "Print a document or a receipt"; readonly search: "Search fields"; readonly sparkles: "AI-generated content or an AI-assisted action (suggest, generate)"; readonly star: "Rating, favorite"; readonly 'triangle-alert': "Warning status"; readonly copy: "Copy to the clipboard"; readonly refresh: "Regenerate, reload, sync again"; readonly 'thumbs-down': "Negative feedback on a response"; readonly 'thumbs-up': "Positive feedback on a response"; readonly trash: "Delete an item; always paired with a confirmation dialog"; readonly users: "A group of people, for example team, members or assignees"; readonly x: "Close, dismiss, remove"; }
```

#### iconSet

The curated set by kebab-case name, for tooling and name-driven rendering.

```ts
{ readonly 'arrow-down': LucideIcon; readonly 'arrow-left': LucideIcon; readonly 'arrow-right': LucideIcon; readonly 'arrow-up': LucideIcon; readonly archive: LucideIcon; readonly bell: LucideIcon; readonly bot: LucideIcon; readonly calendar: LucideIcon; readonly check: LucideIcon; readonly 'chevron-down': LucideIcon; readonly 'chevron-left': LucideIcon; readonly 'chevron-right': LucideIcon; readonly 'chevron-up': LucideIcon; readonly 'chevrons-up-down': LucideIcon; readonly 'circle-alert': LucideIcon; readonly 'circle-check': LucideIcon; readonly 'circle-x': LucideIcon; readonly ellipsis: LucideIcon; readonly 'external-link': LucideIcon; readonly filter: LucideIcon; readonly info: LucideIcon; readonly link: LucideIcon; readonly loader: LucideIcon; readonly menu: LucideIcon; readonly message: LucideIcon; readonly minus: LucideIcon; readonly pencil: LucideIcon; readonly plus: LucideIcon; readonly printer: LucideIcon; readonly search: LucideIcon; readonly sparkles: LucideIcon; readonly star: LucideIcon; readonly 'triangle-alert': LucideIcon; readonly copy: LucideIcon; readonly refresh: LucideIcon; readonly 'thumbs-down': LucideIcon; readonly 'thumbs-up': LucideIcon; readonly trash: LucideIcon; readonly users: LucideIcon; readonly x: LucideIcon; }
```

#### isHexColor

True for `#rgb` and `#rrggbb` (the `#` is required). Accepts model data typed
`string | null | undefined`; `null`, `undefined`, `transparent`, a CSS name and an empty string are
false. Deliberately a plain boolean, not a type predicate: a string that fails the check is still a
string.

```ts
isHexColor(value: string | null | undefined): boolean
```

#### isISODate

True if `value` is a real calendar date written as `YYYY-MM-DD`.

```ts
isISODate(value: string): value is ISODate
```

#### matchesSearch

True when `text` contains `query`, ignoring case and accents. An empty query matches everything.

```ts
matchesSearch(text: string, query: string): boolean
```

#### niceScale

Computes a "nice" value axis for data between `minValue` and `maxValue`.

The axis always includes zero (bars grow from it), so an all-positive data set starts at 0,
an all-negative one ends at 0, and mixed data spans both sides. The step is a round number
(1, 2, 2.5, 5 or 10 times a power of ten) and the ends are multiples of it, aiming for about
`tickCount` ticks. It handles zero data (axis 0 to 1), tiny values (`0.00003`), huge values
and non-finite input (treated as 0).

```ts
niceScale(0, 42).ticks; // [0, 10, 20, 30, 40, 50]
niceScale(-3, 8).ticks; // [-5, -2.5, 0, 2.5, 5, 7.5, 10]
```

```ts
niceScale(minValue: number, maxValue: number, tickCount?: number): NiceScale
```

#### normalizeSearch

Normalizes text for accent- and case-insensitive search: `Café` and `cafe` both
become `cafe`. Works per code point so it stays index-aligned with `highlightMatch`.

```ts
normalizeSearch(text: string): string
```

#### parseCurrencyAmount

Parses what the user typed in **whole units** into integer minor units (the `amount` typing
mode of `CurrencyInput`): `200` is 200.00, so `20000` in BRL; `12,5` is `1250`.

Rules, applied with string manipulation only (no floats):
- Digits are whole units until a decimal mark; the locale's own digits and full-width digits
  count. Other characters (symbols, spaces, signs, letters) are ignored.
- The **last** `.` or `,` (or the locale's decimal mark) starts the fraction when it is the
  only one of its kind and either it is the locale's decimal mark, or it is followed by at
  most as many digits as the currency has minor digits (and is not the locale's grouping
  mark followed by exactly three digits, as in `1.234` for KWD in pt-BR). Otherwise it is
  grouping and ignored: `1.234,56` and `1,234.56` are both 1234.56; `1,234` is 1234 in USD.
- Fraction digits beyond the currency's minor digits are cut (not rounded). Currencies with
  0 minor digits (JPY) have no fraction: every mark is ignored.
- A missing fraction is padded with zeros. Text without digits is `0`. More than 15 digits
  (leading zeros excluded) returns `NaN`, never a shortened number; any other result is a safe
  integer. The sign is not handled here.

```ts
parseCurrencyAmount(text: string, currency: string, locale: string): number
```

#### parseCurrencyInput

Parses what the user typed in a currency field into integer minor units, using
the digits-only typing model: every digit shifts in from the right, and any
other character (separators, symbols, spaces, a sign) is ignored. Typing
`1`, `2`, `3` into a USD field yields `1`, `12`, `123`, shown as `$0.01`,
`$0.12`, `$1.23`. Digits of the locale's numbering system (e.g. Arabic-Indic)
and full-width digits count as digits. Empty input is `0`. Input longer than
15 digits (leading zeros do not count) returns `NaN` rather than a silently shorter number,
so a result that is not `NaN` is always a safe integer.

`currency` is validated through `Intl` (throws `RangeError` for an invalid code).
Pasting `12` into a USD field means `$0.12` by this model; callers that want
to accept pasted decimals must handle paste before calling this function.

```ts
parseCurrencyInput(text: string, currency: string, locale: string): number
```

#### plural

Picks a plural form for `count` using `Intl.PluralRules`.
Call it from catalog functions, passing that catalog's own locale:
`selected: (n: number) => plural('en', n, { one: '1 selected', other: `${n} selected` })`.

```ts
plural(locale: string, count: number, forms: PluralForms): string
```

#### readableTextOn

Which text color is more readable on a background color: `'light'` (white-ish
text, for dark backgrounds) or `'dark'`. Picks whichever of white or black has
the higher WCAG contrast, replacing the handoff's 0.299/0.587/0.114 shortcut.

```ts
readableTextOn(backgroundHex: string): "light" | "dark"
```

#### relativeLuminance

WCAG 2.x relative luminance of a hex color: `0` (black) to `1` (white).
Accepts `#rgb` and `#rrggbb`. Invalid colors throw in development and count as black in production.

```ts
relativeLuminance(hex: string): number
```

#### sortByText

Returns a new array sorted alphabetically by `getText(item)`. Stable: items whose
text compares equal (for example `Ana` and `ana`, or `é` and `e`) keep their input order.

```ts
sortByText<T>(items: readonly T[], getText: (item: T) => string, locale: string): T[]
```

#### SUPPORTED_LOCALES

Locales that ship with built-in message catalogs (ADR-0005).

```ts
readonly ["en-US", "pt-BR"]
```

#### toast

Shows a toast in the default queue. Mount one `ToastRegion` near the app root.

```ts
toast(message: ReactNode, options?: ToastOptions): string
```

#### toastWithUndo

Non-hook form of the undo toast, for plain modules (stores, services, event handlers outside
React). Shows `message` with an **Undo** action whose label comes from the message catalogue
and the active locale, so callers never repeat the word by hand. Returns the toast key, like
`toast()`.

Unlike `useUndoable` it does not defer anything: do the change first, then call this with a
function that reverses it. Use `useUndoable` inside components when you also need a deferred
`commit` or failure handling.

Outside React there is no context, so the locale is the one of the mounted `ToastRegion`
(inside `DSProvider`); pass `locale` or `messages` to decide it yourself.

```ts
toastWithUndo(message: ReactNode, options: ToastWithUndoOptions): string
```

#### toCalendarDay

Normalizes a calendar-day input to `YYYY-MM-DD`. Accepts an `ISODate` (returned unchanged, so a
plain date is never shifted by a time zone), a `Date` (its **local** day) or an ISO date-time
string such as `2026-10-31T23:30:00-03:00` (parsed with `new Date()`, then its **local** day).
Any other string is returned unchanged for the caller's own validation. An unparsable `Date`
or date-time throws in development and gives `''` in production.

```ts
toCalendarDay(value: Date | string): ISODate
```

#### toISODate

Converts a `Date` to `YYYY-MM-DD` using its **local** calendar day (what the
user sees on their clock). Pass `{ utc: true }` to use the UTC day instead.
Invalid dates and years outside 0000-9999 throw in development and give `''` in production.

```ts
toISODate(date: Date, options?: { utc?: boolean; }): ISODate
```

#### TOOLTIP_DELAY

Default time in milliseconds the pointer must rest on the trigger before the tooltip opens.

```ts
500
```

#### warnDeprecated

Logs a deprecation warning once per `name`. Development only: a no-op in
production builds and on the server-side of production. Call it from the
deprecated component's body or module, passing what to use instead.

`warnDeprecated('OldButton', 'Use Button with variant="ghost" instead.')`

```ts
warnDeprecated(name: string, message: string): void
```

### Icons

Bundled Lucide icons, exported with an `Icon` suffix. Pass one to `Icon`, `IconButton` or a `leading`/`trailing` slot. Decorative unless labelled.

`ArchiveIcon`, `ArrowDownIcon`, `ArrowLeftIcon`, `ArrowRightIcon`, `ArrowUpIcon`, `BellIcon`, `BotIcon`, `CalendarIcon`, `CheckIcon`, `ChevronDownIcon`, `ChevronLeftIcon`, `ChevronRightIcon`, `ChevronsUpDownIcon`, `ChevronUpIcon`, `CircleAlertIcon`, `CircleCheckIcon`, `CircleXIcon`, `CopyIcon`, `EllipsisIcon`, `ExternalLinkIcon`, `FilterIcon`, `InfoIcon`, `LinkIcon`, `LoaderIcon`, `MenuIcon`, `MessageIcon`, `MinusIcon`, `PencilIcon`, `PlusIcon`, `PrinterIcon`, `RefreshIcon`, `SearchIcon`, `SparklesIcon`, `StarIcon`, `ThumbsDownIcon`, `ThumbsUpIcon`, `TrashIcon`, `TriangleAlertIcon`, `UsersIcon`, `XIcon`

---

## Recipes

### ApprovalQueue

Status: experimental

A queue of replies written by an agent that wait for a person to approve them before anything reaches a customer. Tabs split "To approve" from "Sent"; Send and Discard act at once and offer Undo.

Components: `ApprovalCard` (from `loui-ds/patterns`), `Tabs`, `EmptyState`, `Badge`, `Toast` (through `useUndoable`).

#### When to use

- Anything that goes to a customer or touches money: replies, messages, refunds. "Approve before sending" is the default (AGENTS.md section 5, agent principle 1).
- Reviews of 1 to 3 stars always get a warning (agent principle 2).

#### When not to use

- Talking to the agent: use `ChatPanel`. The chat is for the owner, not for customers.
- A single yes/no with a consequence you cannot take back: use a `ConfirmDialog`.

#### What it does

- **Cards** show the original message, the editable draft ("You can edit before sending") and, for low-star reviews, a warning: "2-star review: read it carefully before sending."
- **Undo, don't confirm.** Send and Discard happen immediately: the card leaves the queue and a toast says "Reply to buyer_sp sent" with **Undo**. Discard works the same way.
- **The real send waits.** `sendReply` runs only when the Undo window closes, with the edited draft. Undo or Discard means it never runs. If sending fails, the card returns to the queue and an error toast stays.
- **Tabs:** "To approve" and "Sent" with counts and sentence-length labels for screen readers ("2 waiting"). Arrow keys move between tabs.
- **Empty states:** "Nothing to review. New approvals appear here as they arrive."
- After an action, focus moves to the "Replies" heading, so keyboard users do not land on the page body.

#### Things to keep when you adapt it

- Customer-facing text stays short, factual and free of promises about delivery times or discounts, and has no emoji. That is the agent's job; the queue only makes it reviewable.
- Do not add a confirmation dialog per card. It trains people to click through.
- Keep drafts in state above the cards (`draft` and `onDraftChange`), so an edit survives a tab change.

#### Code

<!-- recipe-source:start -->

```tsx
import { useRef, useState } from 'react';
import {
  Badge,
  EmptyState,
  Heading,
  Inline,
  Stack,
  Tab,
  TabList,
  TabPanel,
  Tabs,
  Text,
  useUndoable,
} from 'loui-ds';
import { ApprovalCard } from 'loui-ds/patterns';

type State = 'pending' | 'sent' | 'discarded';

export interface Reply {
  id: string;
  kind: 'question' | 'review';
  author: string;
  message: string;
  draft: string;
  rating?: number;
  state: State;
}

const REPLIES: Reply[] = [
  {
    id: 'r-1',
    kind: 'question',
    author: 'buyer_sp',
    message: 'Do you have this in mustard yellow?',
    draft: 'Hello. We have this in black, navy and grey. Mustard is not available.',
    state: 'pending',
  },
  {
    id: 'r-2',
    kind: 'review',
    author: 'mara_k',
    rating: 2,
    message: 'The color is different from the photos.',
    draft:
      'Thank you for the feedback. Screens can change colors slightly. We can arrange a return.',
    state: 'pending',
  },
];

export interface ApprovalQueueProps {
  initialReplies?: Reply[];
  /** Sends the approved reply to the customer. Runs after the Undo window closes. */
  sendReply?: (reply: Reply) => Promise<void>;
}

/**
 * Anything that goes to a customer waits for approval. Send and Discard act at once and offer
 * Undo instead of asking to confirm; the message really leaves only when the Undo window
 * closes. Tabs split what is waiting from what was sent.
 */
export function ApprovalQueue({ initialReplies = REPLIES, sendReply }: ApprovalQueueProps) {
  const [replies, setReplies] = useState(initialReplies);
  const headingRef = useRef<HTMLHeadingElement>(null);
  const undoable = useUndoable();

  const pending = replies.filter((reply) => reply.state === 'pending');
  const sent = replies.filter((reply) => reply.state === 'sent');

  function setState(id: string, state: State) {
    setReplies((list) => list.map((reply) => (reply.id === id ? { ...reply, state } : reply)));
  }

  function resolve(reply: Reply, state: 'sent' | 'discarded') {
    undoable.run({
      message: `Reply to ${reply.author} ${state}`,
      apply: () => {
        setState(reply.id, state);
      },
      revert: () => {
        setState(reply.id, 'pending');
      },
      commit: state === 'sent' ? () => sendReply?.(reply) : undefined,
    });
    // The card that had focus is gone: send focus to the queue heading.
    headingRef.current?.focus();
  }

  return (
    <Stack gap={4}>
      <Heading level={2} ref={headingRef} tabIndex={-1}>
        Replies
      </Heading>
      <Tabs>
        <TabList aria-label="Replies">
          <Tab id="pending" count={pending.length} countLabel={`${String(pending.length)} waiting`}>
            To approve
          </Tab>
          <Tab id="sent" count={sent.length} countLabel={`${String(sent.length)} sent`}>
            Sent
          </Tab>
        </TabList>
        <TabPanel id="pending">
          {pending.length === 0 ? (
            <EmptyState
              compact
              headingLevel={3}
              title="Nothing to review"
              description="New approvals appear here as they arrive."
            />
          ) : (
            <Stack gap={4}>
              {pending.map((reply) => (
                <ApprovalCard
                  key={reply.id}
                  kind={reply.kind}
                  author={reply.author}
                  message={reply.message}
                  {...(reply.rating === undefined ? {} : { rating: reply.rating })}
                  {...(reply.rating !== undefined && reply.rating <= 3
                    ? {
                        flag: `${String(reply.rating)}-star review: read it carefully before sending.`,
                      }
                    : {})}
                  draft={reply.draft}
                  onDraftChange={(draft) => {
                    setReplies((list) =>
                      list.map((item) => (item.id === reply.id ? { ...item, draft } : item)),
                    );
                  }}
                  onSend={() => {
                    resolve(reply, 'sent');
                  }}
                  onDiscard={() => {
                    resolve(reply, 'discarded');
                  }}
                />
              ))}
            </Stack>
          )}
        </TabPanel>
        <TabPanel id="sent">
          {sent.length === 0 ? (
            <EmptyState
              compact
              headingLevel={3}
              title="Nothing sent yet"
              description="Approved replies appear here."
            />
          ) : (
            <Stack as="ul" gap={2}>
              {sent.map((reply) => (
                <Inline as="li" key={reply.id} gap={3}>
                  <Badge tone="success">Sent</Badge>
                  <Text>{`Reply to ${reply.author}`}</Text>
                </Inline>
              ))}
            </Stack>
          )}
        </TabPanel>
      </Tabs>
    </Stack>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/ApprovalQueue/ApprovalQueue.test.tsx` (warning on the low-star review, send and Undo without a dialog, discard, the edited draft reaching `sendReply` only after the window, a discarded reply never sent, empty state, keyboard and focus, tabs, axe) and the `Recipes/ApprovalQueue` stories.

### CommandPaletteSetup

Status: experimental

Keyboard first, wired end to end: one list of destinations and actions feeds the bare-key shortcuts, the command palette (`Mod+K`) and the shortcuts help (`?`).

Components: `HotkeyProvider`, `useHotkeys`, `CommandPalette`, `ShortcutsHelp`, `SegmentedControl`, `Kbd`, `Toast`.

#### When to use

- Any app with more than a few destinations or actions. "`⌘K` for everything" (AGENTS.md section 5, rule 8).
- Together with a primary action that has a shortcut (see `settings-page`).

#### When not to use

- Searching data (orders, customers): use `SearchInput` with suggestions or a results page. A command can open that search.
- A short list of actions on one object: use a `Menu`.

#### What it does

- `HotkeyProvider` owns the shortcut registry for the subtree. `useHotkeys` registers `1`, `2`, `3` (go to a section) and `F2` (create an order), each with a description and a group.
- `CommandPalette` lists the same destinations and actions with their shortcuts, searchable by label, group and keywords (typing "add" finds "Create order"). Enter runs the highlighted command; Esc closes and focus returns to where it was. Recent commands come first the next time it opens (`recentIds`, `onRun`).
- `ShortcutsHelp` opens with `?` and lists every described shortcut by group.
- A visible "Open commands" button, with the shortcut hint, opens the palette for people who do not know the key.
- Commands are a verb plus an object in sentence case ("Go to customers", "Create order").

#### Things to keep when you adapt it

- Bare-key shortcuts never fire while the user types in a field, or while a dialog or menu is open; `Mod+K` is the exception, so it works from inputs.
- Keep one definition per action. Build `commands` and `useHotkeys` from the same array in a real app so labels cannot drift.
- Shortcuts shown in the palette are display only; the hotkey registration is what binds them.
- `platform` pins what `Mod` means for tests and docs; leave it out in an app.

#### Code

<!-- recipe-source:start -->

```tsx
import { useState } from 'react';
import {
  Button,
  CommandPalette,
  Heading,
  hotkeyKeys,
  HotkeyProvider,
  Inline,
  Kbd,
  SegmentedControl,
  ShortcutsHelp,
  Stack,
  Text,
  toast,
  useHotkeys,
} from 'loui-ds';
import type { Command } from 'loui-ds';

type Page = 'orders' | 'customers' | 'invoices';

const PAGES: { id: Page; label: string; key: string }[] = [
  { id: 'orders', label: 'Orders', key: '1' },
  { id: 'customers', label: 'Customers', key: '2' },
  { id: 'invoices', label: 'Invoices', key: '3' },
];

function Workspace() {
  const [page, setPage] = useState<Page>('orders');
  const [isPaletteOpen, setPaletteOpen] = useState(false);
  const [recent, setRecent] = useState<string[]>([]);

  const createOrder = () => {
    toast.success('Order #1052 created');
  };

  // One definition feeds the shortcut, the palette and the help list.
  useHotkeys([
    ...PAGES.map(({ id, label, key }) => ({
      keys: key,
      handler: () => {
        setPage(id);
      },
      description: `Go to ${label.toLowerCase()}`,
      group: 'Navigation',
    })),
    { keys: 'F2', handler: createOrder, description: 'Create order', group: 'Orders' },
  ]);

  const commands: Command[] = [
    ...PAGES.map(({ id, label, key }) => ({
      id: `go-${id}`,
      label: `Go to ${label.toLowerCase()}`,
      group: 'Navigation',
      shortcut: key,
      onAction: () => {
        setPage(id);
      },
    })),
    {
      id: 'create-order',
      label: 'Create order',
      group: 'Orders',
      keywords: ['new', 'add'],
      shortcut: 'F2',
      onAction: createOrder,
    },
  ];

  return (
    <Stack gap={4}>
      <Inline justify="between">
        <Heading level={2}>{PAGES.find((item) => item.id === page)?.label ?? ''}</Heading>
        <Button
          trailing={<Kbd keys={hotkeyKeys('Mod+K')} />}
          onPress={() => {
            setPaletteOpen(true);
          }}
        >
          Open commands
        </Button>
      </Inline>
      <SegmentedControl
        aria-label="Section"
        value={page}
        onChange={(value) => {
          setPage(value as Page);
        }}
        options={PAGES.map(({ id, label }) => ({ value: id, label }))}
      />
      <Text tone="secondary" as="p">
        Press ? to list every shortcut.
      </Text>
      <CommandPalette
        commands={commands}
        isOpen={isPaletteOpen}
        onOpenChange={setPaletteOpen}
        recentIds={recent}
        onRun={(id) => {
          setRecent((ids) => [id, ...ids.filter((item) => item !== id)].slice(0, 5));
        }}
      />
      <ShortcutsHelp />
    </Stack>
  );
}

export interface CommandPaletteSetupProps {
  /** Pins what Mod means (tests and docs). By default the browser decides. */
  platform?: 'mac' | 'other';
}

/**
 * Keyboard first: Mod+K runs anything, `?` lists the shortcuts, and the same definitions
 * work as bare keys. `HotkeyProvider` owns the registry; the palette lists commands and recent
 * ones, and `ShortcutsHelp` reads whatever `useHotkeys` registered.
 */
export function CommandPaletteSetup({ platform }: CommandPaletteSetupProps) {
  return (
    <HotkeyProvider {...(platform ? { platform } : {})}>
      <Workspace />
    </HotkeyProvider>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/CommandPaletteSetup/CommandPaletteSetup.test.tsx` (number keys, open with `Mod+K`, run by label and by keyword, open from the button and Esc, `F2`, the shortcuts help, recent commands, axe with the palette and the help open) and the `Recipes/CommandPaletteSetup` stories.

### CreateOnTheFly

Status: experimental

Pick an item from a list, or create it without leaving the field: typing a name that matches nothing ends the list with a `Create "name"` row. Choosing it creates the item, selects it and shows a toast with Undo. Built on `Combobox` (`onCreate`, option `leading`) and the `useUndoable` hook.

Components: `Combobox`, `Swatch`, `Text`, `Toast` (through `useUndoable`).

#### When to use

- A field whose list the user can extend as they go: labels, categories, tags, customers, colours.
- The new item needs nothing more than a name (the rest has a sensible default).

#### When not to use

- The new item needs several fields: open a `Sheet` or `Dialog` from `onCreate` instead (see `sheet-form`).
- The typed text is itself the value and nothing is stored (a free-text field with suggestions): use `allowsCustomValue`.

#### What it does

1. The options are alphabetical, each with a decorative `Swatch` as `leading`. The selected option's swatch also shows at the start of the input.
2. While the typed text is not blank and matches no label (accent- and case-insensitive), the list ends with `Create “name”`. It is reachable with `ArrowDown` and chosen with `Enter` or a click, like any option.
3. Choosing it calls `onCreate(name)` and not `onChange`. The handler adds the label and sets `value` to it; the input then shows the new label.
4. A toast says what happened, in the past tense, with **Undo**. Undo removes the label and restores the previous selection. Creating is reversible, so nothing is asked first. The optional `saveLabel` runs when the Undo window closes.

#### Things to keep when you adapt it

- Keep `value` controlled. The Create row never becomes the selection; the handler is what selects the new item.
- Give the new item every default it needs inside `onCreate` (here, the next colour of a palette).
- Trim and normalise the name in the handler; `onCreate` already receives it trimmed.
- The `leading` node is hidden from assistive technology: the option name is its text. Do not use it as the only carrier of meaning.
- If the handler selects nothing, the input empties when the list closes, as in any combobox without `allowsCustomValue`.

#### Code

<!-- recipe-source:start -->

```tsx
import { useState } from 'react';
import { Combobox, sortByText, Stack, Swatch, Text, useUndoable } from 'loui-ds';
import type { ComboboxOption } from 'loui-ds';

export interface Label {
  value: string;
  label: string;
  /** Hex colour, `#rrggbb`. */
  color: string;
}

const LABELS: Label[] = [
  { value: 'fragile', label: 'Fragile', color: '#c2764f' },
  { value: 'gift', label: 'Gift', color: '#6f8fc8' },
  { value: 'priority', label: 'Priority', color: '#d2a44a' },
];

/** Colours given to labels created on the fly, in turn. */
const PALETTE = ['#5fd49a', '#8ab4ff', '#e9b65c', '#f07a6e', '#b49ae8'];

export interface CreateOnTheFlyProps {
  initialLabels?: Label[];
  /** Saves the new label on the server. Runs after the Undo window closes. */
  saveLabel?: (label: Label) => Promise<void>;
}

function toOption(label: Label): ComboboxOption {
  return {
    value: label.value,
    label: label.label,
    leading: <Swatch color={label.color} decorative />,
  };
}

/**
 * Pick a label, or create it without leaving the field. Typing a name that matches no label adds
 * a `Create "name"` row at the end of the list; choosing it creates the label, selects it and
 * shows a toast with Undo (creating is reversible, so it never asks first).
 */
export function CreateOnTheFly({ initialLabels = LABELS, saveLabel }: CreateOnTheFlyProps) {
  const [labels, setLabels] = useState(initialLabels);
  const [value, setValue] = useState<string | null>(null);
  const undoable = useUndoable();
  const options = sortByText(labels.map(toOption), (option) => option.label, 'en');
  const selected = labels.find((label) => label.value === value);

  function create(name: string) {
    const label: Label = {
      value: name.toLowerCase().replace(/\s+/g, '-'),
      label: name,
      color: PALETTE[labels.length % PALETTE.length] ?? '#8ab4ff',
    };
    const previous = value;
    undoable.run({
      message: `Label “${name}” created`,
      apply: () => {
        setLabels((list) => [...list, label]);
        setValue(label.value);
      },
      revert: () => {
        setLabels((list) => list.filter((item) => item.value !== label.value));
        setValue((current) => (current === label.value ? previous : current));
      },
      commit: () => saveLabel?.(label),
    });
  }

  return (
    <Stack gap={3}>
      <Combobox
        label="Label"
        description="Type a new name to create a label."
        options={options}
        value={value}
        onChange={setValue}
        onCreate={create}
        placeholder="Search or create"
      />
      <Text tone="secondary" size="small" as="p">
        {selected ? `Selected: ${selected.label}` : 'No label selected'}
      </Text>
    </Stack>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/CreateOnTheFly/CreateOnTheFly.test.tsx` (alphabetical list with swatches, Create only without a match, create and select from the keyboard, Undo, deferred save, axe), `src/components/Combobox/Combobox.test.tsx` (the `onCreate` and `leading` contracts) and the `Recipes/CreateOnTheFly` stories.

### DestructiveConfirm

Status: experimental

Delete a record from a row action: ask first in a dialog that names the object and the consequence, then delete and offer Undo in a toast.

Components: `DataTable`, `MoreActionsMenu`, `ConfirmDialog`, `Toast` (through `useUndoable`).

#### When to use

- Any deletion of a record the user can see: an order, a customer, an invoice.
- Deleting is the one action that always asks (AGENTS.md section 5, rule 5). The toast with Undo follows it.

#### When not to use

- Reversible actions (archive, mark as done, change status): do them at once and offer Undo, with no dialog. See `undoable-action`.
- Actions that cannot be undone at all: keep the dialog and say so in the consequence ("This can't be undone."), and do not show an Undo toast.

#### What it does

1. The row has a "More actions for order #1048" menu with a danger item, "Delete order".
2. The item opens a `ConfirmDialog` (an `alertdialog`):
   - Title names the object: "Delete order #1048?".
   - Description is the consequence, one sentence.
   - The danger button names the action and the object: "Delete order #1048".
   - **Initial focus is on Cancel**, so Enter or Space right after it opens never deletes. Escape and Cancel close it without side effects.
3. Confirming runs `useUndoable`: the row leaves the table at once and the toast "Order #1048 deleted" appears with **Undo**.
4. Undo puts the row back. If the toast closes without Undo, `deleteOrder(order)` runs (the real delete). If it fails, the row returns and an error toast stays on screen.

#### Things to keep when you adapt it

- Pass the server call as `deleteOrder`; do not call it before the Undo window closes. If your API deletes immediately, omit `commit` in `useUndoable` and make `revert` call a restore endpoint instead (soft delete).
- Mount one `ToastRegion` near the app root (`RecipeHost` does it in the stories and tests).
- The table is alphabetical by customer by default (`defaultSort`), so a restored row lands in its place.
- After the delete, React Aria moves focus to the next row's action. Keep a focusable element in the list; if your list can become empty, move focus to the heading yourself.
- Name each row's menu trigger with `messages={{ moreActions: ... }}` so a screen reader hears which order it belongs to.

#### Code

<!-- recipe-source:start -->

```tsx
import { useState } from 'react';
import {
  ConfirmDialog,
  DataTable,
  formatCurrency,
  Heading,
  MenuItem,
  MoreActionsMenu,
  Stack,
  useDSLocale,
  useUndoable,
} from 'loui-ds';

export interface Order {
  id: string;
  number: number;
  customer: string;
  lines: number;
  /** Integer minor units (cents). */
  total: number;
}

const ORDERS: Order[] = [
  { id: 'o-1046', number: 1046, customer: 'Acme Supply', lines: 6, total: 128_000 },
  { id: 'o-1047', number: 1047, customer: 'Northwind', lines: 3, total: 45_050 },
  { id: 'o-1048', number: 1048, customer: 'Contoso', lines: 14, total: 310_075 },
  { id: 'o-1049', number: 1049, customer: 'Globex', lines: 2, total: 9_900 },
];

export interface DestructiveConfirmProps {
  initialOrders?: Order[];
  /** Permanently deletes the order on the server. Runs after the Undo window closes. */
  deleteOrder?: (order: Order) => Promise<void>;
}

/**
 * Deleting always asks first (a dialog that names the object and the consequence, focus on
 * Cancel), then offers Undo in a toast. The row leaves the list at once; the real delete runs
 * when the Undo window closes, and is reverted with an error toast if it fails.
 */
export function DestructiveConfirm({
  initialOrders = ORDERS,
  deleteOrder,
}: DestructiveConfirmProps) {
  const locale = useDSLocale();
  const [orders, setOrders] = useState(initialOrders);
  const [target, setTarget] = useState<Order | null>(null); // kept while the dialog fades out
  const [isConfirming, setConfirming] = useState(false);
  const undoable = useUndoable();

  function remove(order: Order) {
    undoable.run({
      message: `Order #${order.number} deleted`,
      apply: () => {
        setOrders((list) => list.filter((item) => item.id !== order.id));
      },
      revert: () => {
        setOrders((list) => [...list, order]);
      },
      commit: () => deleteOrder?.(order),
    });
  }

  return (
    <Stack gap={4}>
      <Heading level={2}>Orders</Heading>
      <DataTable
        aria-label="Orders"
        rows={orders}
        defaultSort={{ key: 'customer', direction: 'asc' }}
        columns={[
          { key: 'number', label: 'Order', width: '120px', mono: true, muted: true },
          { key: 'customer', label: 'Customer', isRowHeader: true },
          { key: 'lines', label: 'Lines', width: '96px', align: 'end', mono: true },
          {
            key: 'total',
            label: 'Total',
            width: '140px',
            align: 'end',
            mono: true,
            render: (order) => formatCurrency(order.total, 'USD', locale),
          },
          {
            key: 'actions',
            label: 'Actions',
            width: '96px',
            align: 'end',
            sortable: false,
            render: (order) => (
              <MoreActionsMenu
                size="sm"
                messages={{ moreActions: `More actions for order #${order.number}` }}
                onAction={() => {
                  setTarget(order);
                  setConfirming(true);
                }}
              >
                <MenuItem id="delete" tone="danger">
                  Delete order
                </MenuItem>
              </MoreActionsMenu>
            ),
          },
        ]}
      />
      <ConfirmDialog
        isOpen={isConfirming}
        onOpenChange={setConfirming}
        title={target ? `Delete order #${target.number}?` : ''}
        description={
          target
            ? `The order and its ${target.lines} lines will be removed. You can undo this for a few seconds.`
            : ''
        }
        confirmLabel={target ? `Delete order #${target.number}` : 'Delete order'}
        onConfirm={() => {
          if (target) remove(target);
        }}
      />
    </Stack>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/DestructiveConfirm/DestructiveConfirm.test.tsx` (behavior, keyboard flow through the grid and the dialog, fake-timer commit and failure, axe on the list, the dialog and the toast) and the `Recipes/DestructiveConfirm` stories.

### DetailSheet

Status: experimental

Open a record next to its list: a row opens a side `Sheet` with the details in editable fields, a footer with the destructive action at the start and Cancel plus one primary action at the end.

Components: `DataTable`, `Sheet`, `ConfirmDialog`, `Input`, `Select`, `Textarea`, `Badge`, `Toast`.

#### When to use

- View and edit a record without leaving the list (orders, customers, invoices).
- Edits that are a few fields. For a large editor use a page.

#### When not to use

- A short decision with two buttons: use a `Dialog`.
- A very small edit of one value: edit it in the row.

#### What it does

- **Rows are actionable.** `onRowAction` runs on click and on Enter; the open row keeps a raised background and an ink bar (`activeKey`).
- **The sheet** is a modal dialog named "Order", with the order number in mono next to the title. Focus is trapped; **Esc** closes it and focus returns to the row.
- **Footer layout:** "Delete order" (danger) at the start, "Cancel" and "Save order" (the one primary) at the end.
- **Delete asks first.** The button opens a `ConfirmDialog` on top of the sheet. Esc closes **only the confirmation**; the sheet stays. Confirming removes the order, closes the sheet and shows "Order ORD-1048 deleted" with Undo.
- **Save** updates the row, closes the sheet and shows "Order ORD-1048 saved".
- Edits live in a `draft` copy, so Cancel and Esc discard them. The draft is cleared when the sheet closes; the `Sheet` keeps showing the last details while it slides out, so the panel never animates out empty.

#### Things to keep when you adapt it

- Edit a copy; commit it only on Save.
- Unsaved changes: if losing them matters, close with a `ConfirmDialog` instead of silently discarding. The sheet's `isDismissable` can be turned off while the draft is dirty.
- Build the footer with the render function (`({ close }) => ...`) so Cancel closes the sheet without extra state.

#### Code

<!-- recipe-source:start -->

```tsx
import { useState } from 'react';
import {
  Badge,
  Button,
  ConfirmDialog,
  DataTable,
  Heading,
  Input,
  Select,
  Sheet,
  Stack,
  Textarea,
  toast,
  useUndoable,
} from 'loui-ds';

type Status = 'open' | 'shipped';

export interface Order {
  id: string;
  number: string;
  customer: string;
  status: Status;
  notes: string;
}

const ORDERS: Order[] = [
  { id: 'o-1', number: 'ORD-1047', customer: 'Northwind', status: 'open', notes: '' },
  {
    id: 'o-2',
    number: 'ORD-1048',
    customer: 'Contoso',
    status: 'open',
    notes: 'Call before delivery.',
  },
  { id: 'o-3', number: 'ORD-1050', customer: 'Initech', status: 'shipped', notes: '' },
];

const STATUSES = [
  { value: 'open', label: 'Open' },
  { value: 'shipped', label: 'Shipped' },
];

export interface DetailSheetProps {
  initialOrders?: Order[];
}

/**
 * Open a record next to its list. A row opens a Sheet with the details in editable fields;
 * the footer puts the destructive action at the start (behind a confirmation) and Cancel plus
 * the one primary action at the end. Esc closes the sheet, or only the confirmation when that
 * is on top, and focus returns to the row.
 */
export function DetailSheet({ initialOrders = ORDERS }: DetailSheetProps) {
  const [orders, setOrders] = useState(initialOrders);
  const [activeId, setActiveId] = useState<string | null>(null);
  const [draft, setDraft] = useState<Order | null>(null);
  const undoable = useUndoable();

  function open(order: Order) {
    setDraft(order);
    setActiveId(order.id);
  }

  function save(order: Order, close: () => void) {
    setOrders((list) => list.map((item) => (item.id === order.id ? order : item)));
    toast.success(`Order ${order.number} saved`);
    close();
  }

  function remove(order: Order, close: () => void) {
    undoable.run({
      message: `Order ${order.number} deleted`,
      apply: () => {
        setOrders((list) => list.filter((item) => item.id !== order.id));
      },
      revert: () => {
        setOrders((list) => [...list, order]);
      },
    });
    close();
  }

  return (
    <Stack gap={4}>
      <Heading level={2}>Orders</Heading>
      <DataTable
        aria-label="Orders"
        rows={orders}
        defaultSort={{ key: 'customer', direction: 'asc' }}
        activeKey={activeId ?? ''}
        onRowAction={open}
        columns={[
          { key: 'number', label: 'Order', width: '140px', mono: true, muted: true },
          { key: 'customer', label: 'Customer', isRowHeader: true },
          {
            key: 'status',
            label: 'Status',
            width: '140px',
            render: (order) => (
              <Badge tone={order.status === 'shipped' ? 'success' : 'warning'}>
                {order.status === 'shipped' ? 'Shipped' : 'Open'}
              </Badge>
            ),
          },
        ]}
      />
      <Sheet
        isOpen={activeId !== null}
        onOpenChange={(isOpen) => {
          if (!isOpen) {
            // Clearing the draft is safe: the Sheet keeps showing the last details while it
            // slides out, so there is no need to hold on to the record for the animation.
            setActiveId(null);
            setDraft(null);
          }
        }}
        title="Order"
        meta={draft?.number}
        footerStart={({ close }) =>
          draft ? (
            <ConfirmDialog
              trigger={<Button variant="danger">Delete order</Button>}
              title={`Delete order ${draft.number}?`}
              description="The order will be removed from the list. You can undo this for a few seconds."
              confirmLabel="Delete order"
              onConfirm={() => {
                remove(draft, close);
              }}
            />
          ) : null
        }
        footer={({ close }) => (
          <>
            <Button onPress={close}>Cancel</Button>
            <Button
              variant="primary"
              onPress={() => {
                if (draft) save(draft, close);
              }}
            >
              Save order
            </Button>
          </>
        )}
      >
        {draft ? (
          <Stack gap={4}>
            <Input
              label="Customer"
              value={draft.customer}
              onChange={(customer) => {
                setDraft({ ...draft, customer });
              }}
            />
            <Select
              label="Status"
              options={STATUSES}
              value={draft.status}
              onChange={(status) => {
                if (status) setDraft({ ...draft, status: status as Status });
              }}
            />
            <Textarea
              label="Notes"
              value={draft.notes}
              onChange={(notes) => {
                setDraft({ ...draft, notes });
              }}
            />
          </Stack>
        ) : null}
      </Sheet>
    </Stack>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/DetailSheet/DetailSheet.test.tsx` (open, footer order, Esc and focus return, keyboard open, save, cancel, nested confirmation and Esc, delete with Undo, axe with the sheet and the confirmation open) and the `Recipes/DetailSheet` stories.

### FilterableTable

Status: experimental

A list of records with search, status filters that show counts, a sortable table, row selection with a bulk action and an empty state that tells the user what to do.

Components: `SearchInput`, `SegmentedControl`, `DataTable`, `EmptyState`, `Badge`, `Toast` (through `useUndoable`).

#### When to use

- Orders, customers, invoices, projects: any list the user scans, narrows and acts on.
- When the filters are a small fixed set. For many filters use a `Menu`/`Popover` filter panel and keep the same table.

#### When not to use

- Fewer than three columns: use `ActionList`.
- Server-side data sets: control `sort` and `page` on `DataTable` and fetch per change.

#### What it does

- **Alphabetical by default** (`defaultSort` on the customer column; AGENTS.md rule 5b). The user can sort other columns; the cycle ends in "none".
- **Search** matches the customer or the order number, ignoring case and accents (`matchesSearch`).
- **Filters** are a `SegmentedControl` named "Order status". Counts come from all rows, not from the current search, so they do not jump while typing. `countLabel` gives the screen reader a sentence ("3 open").
- **Empty state:** "No orders found. Try another filter or search term." with a "Clear filters" button.
- **Bulk action:** select rows (the checkbox is named "Select row Contoso"), press "Archive orders". It is reversible, so it applies at once and a toast offers Undo: "2 orders archived" (plural-aware with `plural`).

#### Things to keep when you adapt it

- The bulk bar reserves its space, so the table does not jump when the first row is selected.
- Money is integer minor units formatted with `formatCurrency` and the active locale; never build the string by hand.
- A destructive bulk action (delete) still goes through a `ConfirmDialog`. See `destructive-confirm`.
- The segmented control changes the selection with `Space`; arrows only move focus.

#### Code

<!-- recipe-source:start -->

```tsx
import { useState } from 'react';
import {
  Badge,
  Button,
  DataTable,
  EmptyState,
  formatCurrency,
  Heading,
  Inline,
  matchesSearch,
  plural,
  SearchInput,
  SegmentedControl,
  Stack,
  useDSLocale,
  useUndoable,
} from 'loui-ds';
import type { BadgeTone } from 'loui-ds';

type Status = 'open' | 'shipped' | 'archived';

export interface Order {
  id: string;
  number: string;
  customer: string;
  status: Status;
  /** Integer minor units (cents). */
  total: number;
}

const ORDERS: Order[] = [
  { id: 'o-1', number: 'ORD-1046', customer: 'Acme Supply', status: 'shipped', total: 128_000 },
  { id: 'o-2', number: 'ORD-1047', customer: 'Northwind', status: 'open', total: 45_050 },
  { id: 'o-3', number: 'ORD-1048', customer: 'Contoso', status: 'open', total: 310_075 },
  { id: 'o-4', number: 'ORD-1049', customer: 'Globex', status: 'archived', total: 9_900 },
  { id: 'o-5', number: 'ORD-1050', customer: 'Initech', status: 'shipped', total: 76_200 },
  { id: 'o-6', number: 'ORD-1051', customer: 'Umbrella', status: 'open', total: 18_400 },
];

const STATUS_TONE: Record<Status, BadgeTone> = {
  open: 'warning',
  shipped: 'success',
  archived: 'neutral',
};

const STATUS_LABEL: Record<Status, string> = {
  open: 'Open',
  shipped: 'Shipped',
  archived: 'Archived',
};

export interface FilterableTableProps {
  initialOrders?: Order[];
}

/**
 * Search plus status filters with counts above a sortable table. Alphabetical by customer
 * until the user sorts, rows selectable with a bulk action that offers Undo, and an empty state
 * that says what happened and what to do.
 */
export function FilterableTable({ initialOrders = ORDERS }: FilterableTableProps) {
  const locale = useDSLocale();
  const undoable = useUndoable();
  const [orders, setOrders] = useState(initialOrders);
  const [query, setQuery] = useState('');
  const [filter, setFilter] = useState<'all' | Status>('all');

  const count = (status: Status) => orders.filter((order) => order.status === status).length;
  const rows = orders.filter(
    (order) =>
      (filter === 'all' || order.status === filter) &&
      (matchesSearch(order.customer, query) || matchesSearch(order.number, query)),
  );

  function clearFilters() {
    setQuery('');
    setFilter('all');
  }

  function archive(keys: ReadonlySet<string>) {
    const previous = orders; // saved before acting
    const n = keys.size;
    undoable.run({
      message: plural(locale, n, {
        one: '1 order archived',
        other: `${String(n)} orders archived`,
      }),
      apply: () => {
        setOrders((list) =>
          list.map((order) => (keys.has(order.id) ? { ...order, status: 'archived' } : order)),
        );
      },
      revert: () => {
        setOrders(previous);
      },
    });
  }

  return (
    <Stack gap={4}>
      <Heading level={2}>Orders</Heading>
      <Inline justify="between">
        <SearchInput aria-label="Search orders" value={query} onChange={setQuery} />
        <SegmentedControl
          aria-label="Order status"
          size="sm"
          value={filter}
          onChange={(value) => {
            setFilter(value as 'all' | Status);
          }}
          options={[
            { value: 'all', label: 'All', count: orders.length },
            {
              value: 'open',
              label: 'Open',
              count: count('open'),
              countLabel: `${String(count('open'))} open`,
            },
            { value: 'shipped', label: 'Shipped', count: count('shipped') },
            { value: 'archived', label: 'Archived', count: count('archived') },
          ]}
        />
      </Inline>
      <DataTable
        aria-label="Orders"
        rows={rows}
        defaultSort={{ key: 'customer', direction: 'asc' }}
        selectionMode="multiple"
        columns={[
          { key: 'number', label: 'Order', width: '140px', mono: true, muted: true },
          { key: 'customer', label: 'Customer', isRowHeader: true },
          {
            key: 'status',
            label: 'Status',
            width: '140px',
            render: (order) => (
              <Badge tone={STATUS_TONE[order.status]}>{STATUS_LABEL[order.status]}</Badge>
            ),
          },
          {
            key: 'total',
            label: 'Total',
            width: '140px',
            align: 'end',
            mono: true,
            render: (order) => formatCurrency(order.total, 'USD', locale),
          },
        ]}
        bulkActions={(keys, clear) => (
          <Button
            size="sm"
            onPress={() => {
              archive(keys);
              clear();
            }}
          >
            Archive orders
          </Button>
        )}
        emptyState={
          <EmptyState
            compact
            bordered={false}
            title="No orders found"
            description="Try another filter or search term."
            action={<Button onPress={clearFilters}>Clear filters</Button>}
          />
        }
      />
    </Stack>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/FilterableTable/FilterableTable.test.tsx` (alphabetical order, filter, search, combined, empty state and reset, bulk archive and Undo, keyboard, axe including the bulk bar and the empty state) and the `Recipes/FilterableTable` stories.

### FormWithValidation

Status: experimental

A form that fails well: native validation with one message per field, an error summary that takes focus, server errors on the same fields, a Save button that always works, and "Saved" next to it.

Components: `Form`, `Input`, `Select`, `FieldSet`, `Button`, `Text`.

#### When to use

- Create or edit a record with required fields and rules the server also checks.
- Settings forms that submit together. For a single field that saves as you type, use the field alone and show "Saved" beside it.

#### When not to use

- A filter or search bar that updates as you type: no form, no submit.
- Reversible one-click actions: see `undoable-action`.

#### What it does

1. **Submit empty.** The browser blocks the submit, each invalid field shows its message ("Enter the customer's full name."), and focus moves to the error summary, "Fix 3 fields before saving". Each entry links to its field.
2. **Messages say how to fix it.** Email uses a function for `errorMessage` so a server message is not replaced by a static one: missing or malformed gives "Enter a complete email address."; anything else shows what the server said.
3. **Server errors.** `saveCustomer` resolves with `{ field: message }`. They are passed to `validationErrors`, appear on the fields and in the summary, and are cleared at the start of the next submit.
4. **Save stays enabled** and shows a spinner while the request runs (`isPending`). A disabled button would hide what is wrong.
5. **Saved.** A polite `role="status"` region says "Saved" after a successful save and empties when the user edits again. The region is always in the DOM so screen readers announce the change.

#### Things to keep when you adapt it

- Give the form a name (`aria-label`) so it is a landmark.
- Use `autoComplete` tokens on personal data fields.
- Required fields are marked by the component and described by the summary; do not add "(required)" text.
- Keep the field order the same as the reading order.

#### Code

<!-- recipe-source:start -->

```tsx
import { useState } from 'react';
import type { SyntheticEvent } from 'react';
import { Button, FieldSet, Form, Heading, Inline, Input, Select, Stack, Text } from 'loui-ds';

export interface CustomerValues {
  name: string;
  email: string;
  street: string;
  country: string;
}

/** Field name to message. This is the shape most APIs can produce for a rejected save. */
export type ServerErrors = Record<string, string>;

export interface FormWithValidationProps {
  /** Saves the customer. Resolve with server-side errors keyed by field name, or nothing. */
  saveCustomer?: (values: CustomerValues) => Promise<ServerErrors | undefined>;
}

const COUNTRIES = [
  { value: 'br', label: 'Brazil' },
  { value: 'de', label: 'Germany' },
  { value: 'us', label: 'United States' },
];

/** Stand-in for a real request: the server rejects an address that is already taken. */
async function fakeSave(values: CustomerValues): Promise<ServerErrors | undefined> {
  await new Promise((resolve) => setTimeout(resolve, 300));
  if (values.email === 'taken@example.com') {
    return { email: 'This email belongs to another customer. Enter a different email.' };
  }
  return undefined;
}

/**
 * A form that fails well: native validation with one message per field, an error summary that
 * takes focus on a failed submit, server errors on the same fields, a Save button that stays
 * enabled, and a "Saved" confirmation next to it.
 */
export function FormWithValidation({ saveCustomer = fakeSave }: FormWithValidationProps) {
  const [errors, setErrors] = useState<ServerErrors>({});
  const [isSaving, setIsSaving] = useState(false);
  const [saved, setSaved] = useState(false);

  async function handleSubmit(event: SyntheticEvent<HTMLFormElement>) {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    const text = (name: string) => {
      const value = data.get(name);
      return typeof value === 'string' ? value : '';
    };
    setErrors({}); // clear the previous server errors on every attempt
    setSaved(false);
    setIsSaving(true);
    const result = await saveCustomer({
      name: text('name'),
      email: text('email'),
      street: text('street'),
      country: text('country'),
    });
    setIsSaving(false);
    if (result) setErrors(result);
    else setSaved(true);
  }

  return (
    <Stack
      gap={4}
      onInput={() => {
        setSaved(false); // editing again makes "Saved" stale
      }}
    >
      <Heading level={2}>New customer</Heading>
      <Form
        aria-label="New customer"
        errorSummary
        validationErrors={errors}
        onSubmit={(event) => {
          void handleSubmit(event);
        }}
      >
        <Input
          label="Full name"
          name="name"
          autoComplete="name"
          isRequired
          errorMessage="Enter the customer's full name."
        />
        <Input
          label="Email"
          name="email"
          type="email"
          autoComplete="email"
          description="Invoices are sent to this address."
          isRequired
          errorMessage={(validity) =>
            validity.validationDetails.valueMissing || validity.validationDetails.typeMismatch
              ? 'Enter a complete email address.'
              : validity.validationErrors.join(' ')
          }
        />
        <FieldSet legend="Billing address" description="Shown on every invoice.">
          <Input label="Street" name="street" autoComplete="street-address" />
          <Select
            label="Country"
            name="country"
            options={COUNTRIES}
            isRequired
            errorMessage="Select a country."
          />
        </FieldSet>
        <Inline gap={3}>
          <Button type="submit" variant="primary" isPending={isSaving}>
            Save customer
          </Button>
          <Text role="status" size="small" tone="secondary">
            {saved ? 'Saved' : ''}
          </Text>
        </Inline>
      </Form>
    </Stack>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/FormWithValidation/FormWithValidation.test.tsx` (empty submit and focus on the summary, malformed email, server error cycle, Enter to submit, tab order, axe in the empty, error and saved states) and the `Recipes/FormWithValidation` stories.

### InlinePriceEdit

Status: experimental

A price that reads as text and turns into a field when pressed. Enter confirms, Esc cancels and restores the old value, leaving the field confirms. An empty field means "use the inherited price", which the placeholder shows.

Components: `Button`, `CurrencyInput`, `Text`, `Inline`, `Stack`.

#### When to use

- Prices, quantities of money or any single value edited in a table cell or a list row, where a form or a sheet would be heavy.
- A value that can fall back to an inherited one (a variant price that follows its product).

#### When not to use

- Several fields that belong together: use a form. See `form-with-validation` or `sheet-form`.
- A value whose change needs a confirmation (it reaches a customer or moves money): use an approval step. See `approval-queue`.

#### What it does

1. **Press** the price (or `Enter` / `Space` on it) to open the field. It takes focus with the current value selected as plain text. The field uses `entryMode="amount"`: digits are whole units and the decimal mark starts the cents ("18" gives $18.00, "12.5" gives $12.50), which matches how people say a price.
2. **Enter** confirms. **Esc** cancels: the old value stays, nothing is saved, and the key does not close a surrounding dialog or sheet (`stopPropagation`).
3. **Blur** confirms (clicking or tabbing elsewhere). Focus stays where the user moved it. After Enter or Esc, focus returns to the price button.
4. **Empty** (select all, then `Delete`) means "no price of its own". The placeholder shows the inherited price while the field is empty, even focused, until the first digit is typed.
5. A polite `role="status"` region says "Price saved: $18.00". It is always in the DOM so the change is announced. Nothing is saved when the value did not change.

#### Things to keep when you adapt it

- Guard against saving twice: Enter unmounts the field, which can also fire a blur. The recipe settles once per edit with a ref.
- Give the price button a full name ("Edit price of Linen, white: $12.50"); it starts with the visible text, so voice control still works.
- `0` is a value, not empty. If `0` should mean "inherit" in your product, say so in the handler (`draft || null` here).
- Save errors: show an `Alert` or error toast and restore the old price. Reversible edits may also use `useUndoable` instead of the status line; see `undoable-action`.

#### Code

<!-- recipe-source:start -->

```tsx
import { useLayoutEffect, useRef, useState } from 'react';
import { Button, CurrencyInput, formatCurrency, Inline, Stack, Text, useDSLocale } from 'loui-ds';

export interface InlinePriceEditProps {
  /** What is priced, used in the accessible names: "Linen, white". */
  name?: string;
  /** The product's own price in minor units, or `null` to inherit `inheritedPrice`. */
  initialPrice?: number | null;
  /** The price used while the product has none of its own, in minor units. */
  inheritedPrice?: number;
  currency?: string;
  /** Called with the confirmed price (`null` means "inherit"). Not called on cancel. */
  onSave?: (price: number | null) => void;
}

/**
 * A price that reads as text and edits in place. Press (or Enter on) the price to edit it:
 * Enter confirms, Esc cancels and restores the old value, and leaving the field confirms. An
 * empty field means "use the inherited price", which the placeholder shows while it is empty.
 */
export function InlinePriceEdit({
  name = 'Linen, white',
  initialPrice = null,
  inheritedPrice = 4990,
  currency = 'USD',
  onSave,
}: InlinePriceEditProps) {
  const locale = useDSLocale();
  const [price, setPrice] = useState<number | null>(initialPrice);
  const [draft, setDraft] = useState<number | null>(null);
  const [editing, setEditing] = useState(false);
  const [saved, setSaved] = useState('');
  const settled = useRef(false);
  const trigger = useRef<HTMLButtonElement>(null);
  const field = useRef<HTMLInputElement>(null);
  const restoreFocus = useRef(false);
  const money = (minor: number) => formatCurrency(minor, currency, locale);

  // The field unmounts when editing ends, so focus goes back to the trigger by hand. After a
  // blur it stays where the user moved it.
  useLayoutEffect(() => {
    if (!editing && restoreFocus.current) {
      restoreFocus.current = false;
      trigger.current?.focus();
    }
  }, [editing]);

  // Focus the field when it opens (the autoFocus attribute is avoided on purpose).
  useLayoutEffect(() => {
    if (editing) field.current?.focus();
  }, [editing]);

  function start() {
    settled.current = false;
    setSaved('');
    setDraft(price);
    setEditing(true);
  }

  function finish(commit: boolean, returnFocus: boolean) {
    if (settled.current) return; // Enter and the blur it causes must not save twice.
    settled.current = true;
    restoreFocus.current = returnFocus;
    setEditing(false);
    // 0 and empty both mean "no price of its own".
    const next = commit ? draft || null : price;
    if (commit && next !== price) {
      setPrice(next);
      onSave?.(next);
      setSaved(`Price saved: ${money(next ?? inheritedPrice)}`);
    }
  }

  return (
    <Stack gap={2}>
      <Inline gap={3} align="center">
        <Text>{name}</Text>
        {editing ? (
          <CurrencyInput
            size="sm"
            entryMode="amount"
            aria-label={`Price of ${name}`}
            currency={currency}
            inputRef={field}
            placeholder={money(inheritedPrice)}
            description="Leave empty to use the inherited price."
            value={draft}
            onChange={setDraft}
            onBlur={() => {
              finish(true, false);
            }}
            onKeyDown={(event) => {
              if (event.key === 'Enter') {
                event.preventDefault();
                finish(true, true);
              } else if (event.key === 'Escape') {
                // Stop here so a surrounding dialog or sheet does not close with it.
                event.preventDefault();
                event.stopPropagation();
                finish(false, true);
              }
            }}
          />
        ) : (
          <Button
            ref={trigger}
            size="sm"
            variant="ghost"
            aria-label={`Edit price of ${name}: ${money(price ?? inheritedPrice)}`}
            onPress={start}
          >
            {money(price ?? inheritedPrice)}
          </Button>
        )}
      </Inline>
      <Text role="status" size="small" tone="secondary">
        {saved}
      </Text>
    </Stack>
  );
}
```

<!-- recipe-source:end -->

### MarkdownMessage

Status: experimental

Safe markdown in the replies of a `ChatPanel`, through its `renderContent` prop. A small subset is parsed into React elements: no markdown library, no `dangerouslySetInnerHTML`, no HTML string anywhere.

Components: `ChatPanel` (from `loui-ds/patterns`), `Code`, `Link`, `Stack`, `Inline`, `Text`.

#### When to use

- An agent answers in markdown and you want lists, emphasis, code and links to look right in the chat.
- You need the output to be safe by construction: model output is untrusted text.

#### When not to use

- Full markdown (headings, tables, images, nested lists, raw HTML). Add a reviewed, sanitizing renderer of your choice behind the same `renderContent` function, or keep the text plain.
- Your own messages and error texts: they stay plain, so what a person typed is what they see.

#### What it does

- **Paragraphs** separated by a blank line; a single line break inside a paragraph is kept.
- **Inline:** `**bold**`, `*italic*` or `_italic_`, `` `code` `` and `[text](https://example.com)`.
- **Code blocks** fenced with three backticks render with `Code variant="block"`, which scrolls sideways and becomes a keyboard stop when it overflows.
- **Lists:** `-` or `*` bullets, and `1.` numbers (the first number is kept). Bullets are hidden from assistive technology; the list keeps its role.
- **Links** open in a new tab, and only `http`, `https` and `mailto` addresses become links. Any other address (`javascript:`, `data:`) keeps the text and drops the link.
- **Streaming:** a fence or emphasis that is not closed yet renders as it is typed and settles when the closing marker arrives.
- Anything else (headings, tables, images, raw HTML such as `<script>`) is shown as plain text, escaped by React.

#### Things to keep when you adapt it

- Never build an HTML string and never use `dangerouslySetInnerHTML`. Keep building elements.
- Keep the link protocol allow-list when you add features.
- Do not render the user's own messages as markdown.

#### Code

<!-- recipe-source:start -->

```tsx
import { useState } from 'react';
import type { ReactNode } from 'react';
import { Code, Inline, Link, Stack, Text } from 'loui-ds';
import { ChatPanel } from 'loui-ds/patterns';
import type { ChatMessage } from 'loui-ds/patterns';

/**
 * A small markdown subset, rendered as React elements. There is no HTML string anywhere, so
 * nothing the model writes can inject markup: React escapes every piece of text, and links are
 * kept only when their address is http, https or mailto.
 *
 * Supported: paragraphs, **bold**, *italic* (or _italic_), `inline code`, fenced code blocks,
 * "-" and "1." lists, and [links](https://example.com). Everything else (headings, tables,
 * images, raw HTML) stays visible as plain text. A fence or an emphasis that is not closed yet
 * renders as it is, so a reply that is still streaming never flickers into broken markup.
 */

const SAFE_LINK = /^(https?:\/\/|mailto:)/i;
const FENCE = /^`{3}(.*)$/;
const FENCE_END = /^`{3}\s*$/;
// Written this way so the source of this file can sit inside a fenced block of its own doc.
const FENCE_MARK = '`'.repeat(3);
const BULLET = /^\s*[-*]\s+(.*)$/;
const NUMBERED = /^\s*(\d{1,9})\.\s+(.*)$/;
// Order matters: code first (nothing inside it is markup), then strong before emphasis.
const INLINE =
  /`([^`\n]+)`|\*\*(\S(?:.*?\S)?)\*\*|\*(\S(?:[^*\n]*\S)?)\*|(?<![\w])_([^_\n]+)_(?![\w])|\[([^\]\n]+)\]\(((?:[^()\s]|\([^()\s]*\))+)\)/;

export function renderInline(text: string): ReactNode[] {
  const nodes: ReactNode[] = [];
  let rest = text;
  while (rest !== '') {
    const match = INLINE.exec(rest);
    if (!match) {
      nodes.push(rest);
      break;
    }
    if (match.index > 0) nodes.push(rest.slice(0, match.index));
    const key = nodes.length;
    const [, code, strong, emphasis, underscore, label, href] = match;
    if (code !== undefined) {
      nodes.push(<Code key={key}>{code}</Code>);
    } else if (strong !== undefined) {
      nodes.push(<strong key={key}>{renderInline(strong)}</strong>);
    } else if (emphasis !== undefined || underscore !== undefined) {
      nodes.push(<em key={key}>{renderInline(emphasis ?? underscore ?? '')}</em>);
    } else if (label !== undefined && href !== undefined) {
      // Unsafe addresses (javascript:, data:) lose the link and keep the text.
      nodes.push(
        SAFE_LINK.test(href) ? (
          <Link key={key} href={href} target="_blank">
            {label}
          </Link>
        ) : (
          label
        ),
      );
    }
    rest = rest.slice(match.index + match[0].length);
  }
  return nodes;
}

function renderLines(lines: string[]): ReactNode[] {
  return lines.flatMap((line, index) => [
    ...(index > 0 ? [<br key={`br-${String(index)}`} />] : []),
    ...renderInline(line),
  ]);
}

/** Turns the markdown subset into React elements. Pass it to `ChatPanel` as `renderContent`. */
export function renderMarkdown(source: string): ReactNode {
  const lines = source.replace(/\r\n?/g, '\n').split('\n');
  const blocks: ReactNode[] = [];
  let paragraph: string[] = [];

  function flushParagraph() {
    if (paragraph.length === 0) return;
    blocks.push(
      <Text as="p" size="label" key={blocks.length}>
        {renderLines(paragraph)}
      </Text>,
    );
    paragraph = [];
  }

  for (let i = 0; i < lines.length; i += 1) {
    const line = lines[i] ?? '';
    if (FENCE.test(line)) {
      flushParagraph();
      const code: string[] = [];
      i += 1;
      while (i < lines.length && !FENCE_END.test(lines[i] ?? '')) {
        code.push(lines[i] ?? '');
        i += 1;
      }
      blocks.push(
        <Code variant="block" key={blocks.length}>
          {code.join('\n')}
        </Code>,
      );
    } else if (BULLET.test(line) || NUMBERED.test(line)) {
      flushParagraph();
      const ordered = NUMBERED.test(line);
      const pattern = ordered ? NUMBERED : BULLET;
      const start = ordered ? Number(NUMBERED.exec(line)?.[1]) : 1;
      const items: string[] = [];
      while (i < lines.length && pattern.test(lines[i] ?? '')) {
        const found = pattern.exec(lines[i] ?? '');
        items.push(found?.[ordered ? 2 : 1] ?? '');
        i += 1;
      }
      i -= 1;
      blocks.push(
        // The list reset comes from Stack. The marker is real text for numbers, and hidden for bullets.
        <Stack as={ordered ? 'ol' : 'ul'} gap={1} key={blocks.length}>
          {items.map((item, index) => (
            <Inline as="li" gap={2} align="baseline" wrap={false} key={index}>
              <Text size="label" tone="secondary" mono aria-hidden={ordered ? undefined : true}>
                {ordered ? `${String(start + index)}.` : '•'}
              </Text>
              <Text size="label">{renderInline(item)}</Text>
            </Inline>
          ))}
        </Stack>,
      );
    } else if (line.trim() === '') {
      flushParagraph();
    } else {
      paragraph.push(line);
    }
  }
  flushParagraph();
  return <Stack gap={2}>{blocks}</Stack>;
}

const INITIAL: ChatMessage[] = [
  { id: 'm-1', role: 'user', content: 'How do I check the status of an order?' },
  {
    id: 'm-2',
    role: 'assistant',
    content: [
      'Open **Orders** and search by the order code, for example `ORD-1048`.',
      '',
      'Then:',
      '',
      '1. Select the order.',
      '2. Read the *Status* field.',
      '3. Use [the guide](https://example.com/orders) for the full list.',
      '',
      FENCE_MARK,
      'GET /orders/ORD-1048',
      FENCE_MARK,
    ].join('\n'),
  },
];

export interface MarkdownChatProps {
  initialItems?: ChatMessage[];
}

/**
 * A chat whose assistant replies are rendered as markdown. Your own messages and errors stay
 * plain text: they are not formatted, so what a person typed is what they see.
 */
export function MarkdownChat({ initialItems = INITIAL }: MarkdownChatProps) {
  const [items, setItems] = useState(initialItems);
  return (
    <ChatPanel
      items={items}
      onSend={(text) => {
        setItems((current) => [
          ...current,
          { id: `m-${String(current.length + 1)}`, role: 'user', content: text },
        ]);
      }}
      renderContent={(message) =>
        message.role === 'assistant' && message.status !== 'error'
          ? renderMarkdown(message.content)
          : message.content
      }
    />
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/MarkdownMessage/MarkdownMessage.test.tsx` (every supported construct, escaping of raw HTML, unsafe link addresses, unclosed markers while streaming, the chat integration and axe) and the `Recipes/MarkdownMessage` stories.

### PasswordField

Status: experimental

A password field with a show/hide toggle, built from `Input` and a labelled `Button` in its `trailing` slot. It satisfies WCAG 3.3.8 (accessible authentication): pasting and password managers keep working, and nothing asks the user to remember or retype a password.

Components: `Input`, `Button`, `VisuallyHidden`.

#### When to use

- Sign-in, sign-up and change-password forms.
- Any secret the user types that a typo would make hard to correct: API keys, access tokens.

#### When not to use

- A PIN or one-time code: use `Input` with `inputMode="numeric"` and `autoComplete="one-time-code"`.
- Confirming a password by typing it twice: do not add a second field. The toggle lets the user check what they typed, and a second field defeats password managers.

#### What it does

1. The field is `type="password"` and the toggle sits inside it, after the text. The toggle is a real button in the tab order, so keyboard and switch users can reach it. Enter and Space press it.
2. The toggle's visible text and its accessible name change together: "Show" with the name "Show password", then "Hide" with "Hide password". The name contains the visible text (WCAG 2.5.3, Label in Name).
3. A visually hidden `role="status"` announces "Password shown" or "Password hidden". Focus stays on the toggle, and the typed value is kept.
4. `mode="current"` sets `autoComplete="current-password"` (sign-in). `mode="new"` sets `autoComplete="new-password"` (sign-up, change password), which also lets the password manager offer a generated password.

#### Why not `autoComplete="off"`

`off` on a password field tells password managers and the browser not to help. Browsers mostly ignore it for login forms, and where they obey it the user is pushed towards a weak, memorable password or to retyping one. WCAG 3.3.8 asks for the opposite: let the user paste and use a manager. Use `current-password` or `new-password`, always.

#### Why not `aria-pressed`

The toggle changes its name ("Show password" / "Hide password"), so its state is already in the name. A button whose name changes **and** has `aria-pressed` reads as "Hide password, pressed", which is ambiguous. Use one of the two: a changing name (this recipe), or a fixed name ("Show password") with `aria-pressed={visible}` and no visible text swap.

#### Things to keep when you adapt it

- Never add an `onPaste` handler that blocks, `autoComplete="off"`, or any rule that forbids pasting.
- Keep `spellCheck="false"`; a password is not a word.
- Pass translated strings through `labels`; each pair (visible text and name) must stay consistent, with the visible text inside the name.
- Do not hide the password again automatically in a way that moves focus or clears the value.
- Show the password rule in `description` (not in a placeholder) when you create a password, and put server errors in `errorMessage`.

#### Code

<!-- recipe-source:start -->

```tsx
import { useState } from 'react';
import type { ReactNode } from 'react';
import { Button, Input, VisuallyHidden } from 'loui-ds';
import type { InputProps } from 'loui-ds';

export interface PasswordFieldLabels {
  /** Visible text of the toggle while the password is hidden. */
  show: string;
  /** Visible text of the toggle while the password is visible. */
  hide: string;
  /** Accessible name while hidden. Must contain `show` (WCAG 2.5.3 Label in Name). */
  showPassword: string;
  /** Accessible name while visible. Must contain `hide`. */
  hidePassword: string;
  /** Announced after showing the password. */
  shown: string;
  /** Announced after hiding the password. */
  hidden: string;
}

const DEFAULT_LABELS: PasswordFieldLabels = {
  show: 'Show',
  hide: 'Hide',
  showPassword: 'Show password',
  hidePassword: 'Hide password',
  shown: 'Password shown',
  hidden: 'Password hidden',
};

export interface PasswordFieldProps extends Omit<
  Extract<InputProps, { label: ReactNode }>,
  'type' | 'trailing' | 'autoComplete' | 'label'
> {
  /** Label of the field. */
  label?: string;
  /**
   * `current` for signing in (`autoComplete="current-password"`), `new` for creating or changing
   * a password (`autoComplete="new-password"`), which also lets a password manager offer a
   * generated one.
   */
  mode?: 'current' | 'new';
  /** Strings of the toggle, so they can be translated. */
  labels?: Partial<PasswordFieldLabels>;
}

/**
 * A password field with a show/hide toggle. The toggle is a labelled `Button` inside the field,
 * after the text; it never leaves the tab order, so keyboard and switch users can use it.
 *
 * Accessible authentication (WCAG 3.3.8): the field keeps pasting and password managers working.
 * It sets `autoComplete` to `current-password` or `new-password`, never `off`, and it blocks
 * nothing: no `onPaste` handler, no `autoComplete="off"`, no "type it, do not paste it" rule.
 */
export function PasswordField({
  label = 'Password',
  mode = 'current',
  labels,
  ...rest
}: PasswordFieldProps) {
  const text = { ...DEFAULT_LABELS, ...labels };
  const [visible, setVisible] = useState(false);
  const [announcement, setAnnouncement] = useState('');

  function toggle() {
    const next = !visible;
    setVisible(next);
    setAnnouncement(next ? text.shown : text.hidden);
  }

  return (
    <>
      <Input
        {...rest}
        label={label}
        type={visible ? 'text' : 'password'}
        autoComplete={mode === 'new' ? 'new-password' : 'current-password'}
        // Passwords are not words: no spell checking.
        spellCheck="false"
        trailing={
          <Button
            size="sm"
            variant="ghost"
            aria-label={visible ? text.hidePassword : text.showPassword}
            isDisabled={rest.isDisabled === true}
            onPress={toggle}
          >
            {visible ? text.hide : text.show}
          </Button>
        }
      />
      <VisuallyHidden role="status">{announcement}</VisuallyHidden>
    </>
  );
}
```

<!-- recipe-source:end -->

### SettingsPage

Status: experimental

A settings screen: app shell, a top bar with the page's one primary action and its keyboard shortcut, and one card per topic with switches, a select and a radio group.

Components: `AppShell`, `Sidebar`, `TopBar`, `Card`, `Switch`, `Select`, `RadioGroup`, `Button`, `Kbd`, `Toast`, `useHotkeys`.

#### When to use

- Preferences and configuration that the user changes and saves together.
- As the frame for other screens too: the shell, sidebar and top bar are the same.

#### When not to use

- A form with validation rules and server errors: see `form-with-validation`.
- A single toggle that applies on change: use the `Switch` alone and show "Saved".

#### What it does

- **One primary action, top right:** "Save settings", with the shortcut shown inside the button (`Kbd`). Everything else on the page is secondary or a control.
- **The shortcut works from anywhere**, including while a field has focus (`allowInEditable`), and it is registered with a description and group, so it appears in `ShortcutsHelp` and in a `CommandPalette` that uses `includeHotkeys`.
- **Landmarks:** `aside` (sidebar), `header` (top bar), one `main`, one `h1` ("Settings"). The skip link is built in; below 768 px the sidebar becomes an off-canvas panel opened by `AppShellNavToggle`.
- **Cards** group topics; each card title is an `h2`. Switches carry a description; the select and the radio group have visible labels.
- Saving shows a toast, "Settings saved". Nothing is validated here because every option is valid.

#### Things to keep when you adapt it

- The shell fills its parent: give the parent a height (the story frame is 640 px tall).
- Currency, language and similar lists are alphabetical by label; pass them sorted (`sortByText`) unless the order carries meaning.
- If settings save automatically, drop the button and show "Saved" beside the control; keep a primary action only if something still needs one.
- `Mod+S` is Control S or Command S, resolved when the key is pressed.
- A `Card` is a labelled region. Do not title one "Notifications": the toast region has that name, and two landmarks with the same name fail axe (`landmark-unique`) whenever a toast is on screen. This recipe uses "Email alerts".

#### Code

<!-- recipe-source:start -->

```tsx
import { useState } from 'react';
import {
  AppShell,
  AppShellNavToggle,
  Button,
  Card,
  hotkeyKeys,
  Kbd,
  Radio,
  RadioGroup,
  Select,
  Sidebar,
  Stack,
  Switch,
  toast,
  TopBar,
  useHotkeys,
} from 'loui-ds';

export interface Settings {
  orderShipped: boolean;
  weeklySummary: boolean;
  currency: string;
  invoiceDelivery: string;
}

const DEFAULTS: Settings = {
  orderShipped: true,
  weeklySummary: false,
  currency: 'usd',
  invoiceDelivery: 'email',
};

const CURRENCIES = [
  { value: 'brl', label: 'Brazilian real' },
  { value: 'eur', label: 'Euro' },
  { value: 'usd', label: 'US dollar' },
];

export interface SettingsPageProps {
  initialSettings?: Settings;
  /** Persists the settings. */
  onSave?: (settings: Settings) => void;
}

/**
 * A settings screen: app shell, one top bar with the page's single primary action and its
 * shortcut, and one card per topic. Controls are plain Switch, Select and RadioGroup; the
 * shortcut is registered with `useHotkeys` so it also shows up in the command palette and
 * the shortcuts help.
 */
export function SettingsPage({ initialSettings = DEFAULTS, onSave }: SettingsPageProps) {
  const [settings, setSettings] = useState(initialSettings);

  function save() {
    onSave?.(settings);
    toast.success('Settings saved');
  }

  useHotkeys([
    {
      keys: 'Mod+S',
      handler: save,
      description: 'Save settings',
      group: 'Settings',
      allowInEditable: true,
    },
  ]);

  return (
    <AppShell
      sidebar={
        <Sidebar
          workspace={{ name: 'Northwind', subtitle: 'Production' }}
          value="settings"
          sections={[
            {
              id: 'work',
              title: 'Work',
              items: [
                { value: 'orders', label: 'Orders', href: '#orders' },
                { value: 'customers', label: 'Customers', href: '#customers' },
              ],
            },
            {
              id: 'account',
              title: 'Account',
              items: [{ value: 'settings', label: 'Settings', href: '#settings' }],
            },
          ]}
        />
      }
      topBar={
        <TopBar
          title="Settings"
          actions={
            <Button variant="primary" trailing={<Kbd keys={hotkeyKeys('Mod+S')} />} onPress={save}>
              Save settings
            </Button>
          }
        >
          <AppShellNavToggle />
        </TopBar>
      }
    >
      <Stack gap={6}>
        <Card title="Email alerts">
          <Stack gap={4}>
            <Switch
              label="Order shipped"
              description="Email me when an order leaves the warehouse."
              isSelected={settings.orderShipped}
              onChange={(orderShipped) => {
                setSettings((current) => ({ ...current, orderShipped }));
              }}
            />
            <Switch
              label="Weekly summary"
              description="Email me a summary of orders every Monday."
              isSelected={settings.weeklySummary}
              onChange={(weeklySummary) => {
                setSettings((current) => ({ ...current, weeklySummary }));
              }}
            />
          </Stack>
        </Card>
        <Card title="Regional">
          <Select
            label="Currency"
            description="Used for new orders and invoices."
            options={CURRENCIES}
            value={settings.currency}
            onChange={(currency) => {
              if (currency) setSettings((current) => ({ ...current, currency }));
            }}
          />
        </Card>
        <Card title="Invoices">
          <RadioGroup
            label="Delivery"
            value={settings.invoiceDelivery}
            onChange={(invoiceDelivery) => {
              setSettings((current) => ({ ...current, invoiceDelivery }));
            }}
          >
            <Radio value="email" label="Send by email" />
            <Radio value="download" label="Download only" />
          </RadioGroup>
        </Card>
      </Stack>
    </AppShell>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/SettingsPage/SettingsPage.test.tsx` (landmarks and a single primary action, save with the button and with the shortcut, the shortcut listed in the help, Space on a switch, axe) and the `Recipes/SettingsPage` stories.

The axe checks skip the `Kbd` inside the primary button: it keeps its own light text color on the light button fill (2.13:1). That is a component issue, not a property of the recipe; see the report.

### SheetForm

Status: experimental

A form inside a side `Sheet` whose primary button sits in the sheet footer, outside the `<form>`. The button is linked to the form with the `form` attribute, so the browser submits and validates natively.

Components: `Sheet`, `Form`, `Input`, `Select`, `Button`, `Toast`.

#### When to use

- Create or edit a record in a sheet or dialog where the actions live in a fixed footer and the fields scroll.
- Any layout where the submit button cannot be a child of the form.

#### When not to use

- A form on a page: put the submit button inside the form.
- A short yes/no decision: use a `Dialog`.

#### What it does

- **Linked, not wired.** `Form` gets an `id`; the footer button is `type="submit"` with `form={id}`. No `onPress` handler calls submit.
- **Enter submits.** Pressing Enter in a field submits the form, as in any native form.
- **Validation is native.** An invalid submit is blocked, the first invalid field takes focus and every invalid field shows its message (`errorMessage` in plain words that say how to fix it).
- **One primary action.** "Save supplier" is the only primary button; "Cancel" sits beside it. Esc also cancels.
- **Saved.** A valid submit closes the sheet and shows "Supplier Northwind saved" in a toast.

#### Things to keep when you adapt it

- Generate the id with `useId()`; never derive it from a label.
- Keep the submit button enabled so a click always shows what is wrong.
- For a server-side check, keep the sheet open and pass `validationErrors` to the `Form` (see `FormWithValidation`).
- To show progress, set `isPending` on the submit button.

#### Code

<!-- recipe-source:start -->

```tsx
import { useId, useState } from 'react';
import type { SyntheticEvent } from 'react';
import { Button, Form, Heading, Input, Select, Sheet, Stack, Text, toast } from 'loui-ds';

export interface SupplierValues {
  name: string;
  email: string;
  country: string;
}

export interface SheetFormProps {
  /** Called with the values after a valid submit. The sheet closes and "saved" is announced. */
  onSave?: (values: SupplierValues) => void;
}

const COUNTRIES = [
  { value: 'br', label: 'Brazil' },
  { value: 'de', label: 'Germany' },
  { value: 'us', label: 'United States' },
];

/**
 * A form inside a Sheet whose submit button lives in the Sheet footer, outside the form. The
 * button and the form are linked with the `form` attribute, so the browser does the work: a
 * click submits natively, Enter inside a field submits, and an invalid form is blocked with
 * focus on the first invalid field. One primary action (the submit button), Cancel beside it.
 */
export function SheetForm({ onSave }: SheetFormProps) {
  const formId = useId();
  const [isOpen, setIsOpen] = useState(false);

  function handleSubmit(event: SyntheticEvent<HTMLFormElement>) {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    const text = (name: string) => {
      const value = data.get(name);
      return typeof value === 'string' ? value : '';
    };
    const values = { name: text('name'), email: text('email'), country: text('country') };
    onSave?.(values);
    toast.success(`Supplier ${values.name} saved`);
    setIsOpen(false);
  }

  return (
    <Stack gap={4}>
      <Heading level={2}>Suppliers</Heading>
      <Text tone="secondary">No suppliers yet. Add the first one.</Text>
      <div>
        <Button
          onPress={() => {
            setIsOpen(true);
          }}
        >
          New supplier
        </Button>
      </div>
      <Sheet
        isOpen={isOpen}
        onOpenChange={setIsOpen}
        title="New supplier"
        footer={({ close }) => (
          <>
            <Button onPress={close}>Cancel</Button>
            {/* Outside the <form>, but `form` points at it: a native submit with validation. */}
            <Button type="submit" form={formId} variant="primary">
              Save supplier
            </Button>
          </>
        )}
      >
        <Form id={formId} aria-label="New supplier" onSubmit={handleSubmit}>
          <Input
            label="Name"
            name="name"
            autoComplete="organization"
            isRequired
            errorMessage="Enter the supplier's name."
          />
          <Input
            label="Email"
            name="email"
            type="email"
            autoComplete="email"
            isRequired
            errorMessage={(validity) =>
              validity.validationDetails.valueMissing || validity.validationDetails.typeMismatch
                ? 'Enter a complete email address.'
                : validity.validationErrors.join(' ')
            }
          />
          <Select
            label="Country"
            name="country"
            options={COUNTRIES}
            isRequired
            errorMessage="Select a country."
          />
        </Form>
      </Sheet>
    </Stack>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/SheetForm/SheetForm.test.tsx` (footer button linked by `form`, invalid submit focus and messages, submit by click and by Enter, Cancel and Esc, saved toast, axe in the closed, open and error states).

### UndoableAction

Status: experimental

A reversible action (archive, mark as done, change status) that happens at once, with no confirmation, and an Undo in a toast. Built on the `useUndoable` hook.

Components: `Button`, `Badge`, `Toast` (through `useUndoable`).

#### When to use

- Archive, mark as done, link, unlink, change a status: anything the user can take back.
- "Reversible actions never ask; they offer Undo" (AGENTS.md section 5).

#### When not to use

- Deleting: ask first. See `destructive-confirm`.
- Anything that cannot be reversed or that reaches a customer: use an approval step. See `approval-queue`.

#### What it does

1. Archive applies the change immediately: the order leaves the list and the counter changes.
2. A toast says what happened, in the past tense: "Order #1051 archived", with **Undo**. The timer is 5 seconds and pauses while the pointer or focus is on the toast (WCAG 2.2.1); `F6` moves focus into the toast region.
3. Undo calls `revert` with the status saved before acting. If the toast closes first, `commit` runs (`saveStatus`, the server call). A failing commit reverts the change and shows an error toast that stays until dismissed.

#### `useUndoable`

```tsx
const undoable = useUndoable();
undoable.run({
  message: 'Order #1051 archived',
  apply: () => setStatus(id, 'archived'), // now
  revert: () => setStatus(id, previous), // Undo, or a failed commit
  commit: () => api.archive(id), // after the Undo window (optional)
});
```

Two ways to persist:

- **Deferred (this recipe):** `apply` changes local state, `commit` saves when the window closes. Simple, but a closed tab loses a pending change.
- **Immediate:** `apply` saves, `revert` sends the inverse change, no `commit`. Use it when losing the change is worse than a second request.

#### Things to keep when you adapt it

- Save what Undo needs **before** acting (`order.status` here), not state that may move on.
- The element that had focus is gone after the action. The recipe moves focus to the list heading (`tabIndex={-1}`); focusing the next row's button is also fine.
- Give each repeated button a distinct name (`aria-label="Archive order #1051"`). It starts with the visible text, so voice control still works.

#### Code

<!-- recipe-source:start -->

```tsx
import { useRef, useState } from 'react';
import { Badge, Button, Heading, Inline, Stack, Text, useUndoable } from 'loui-ds';

export interface Order {
  id: string;
  number: number;
  customer: string;
  status: 'open' | 'archived';
}

const ORDERS: Order[] = [
  { id: 'o-1049', number: 1049, customer: 'Globex', status: 'open' },
  { id: 'o-1050', number: 1050, customer: 'Contoso', status: 'open' },
  { id: 'o-1051', number: 1051, customer: 'Northwind', status: 'open' },
];

export interface UndoableActionProps {
  initialOrders?: Order[];
  /** Saves the new status on the server. Runs after the Undo window closes. */
  saveStatus?: (order: Order, status: Order['status']) => Promise<void>;
}

/**
 * A reversible action never asks for confirmation: it happens now and a toast offers Undo.
 * `useUndoable` applies the change, shows "Order #1051 archived" with an Undo button and either
 * reverts (Undo) or commits (the toast closes).
 */
export function UndoableAction({ initialOrders = ORDERS, saveStatus }: UndoableActionProps) {
  const [orders, setOrders] = useState(initialOrders);
  const headingRef = useRef<HTMLHeadingElement>(null);
  const undoable = useUndoable();
  const open = orders.filter((order) => order.status === 'open');

  function setStatus(id: string, status: Order['status']) {
    setOrders((list) => list.map((order) => (order.id === id ? { ...order, status } : order)));
  }

  function archive(order: Order) {
    undoable.run({
      message: `Order #${order.number} archived`,
      apply: () => {
        setStatus(order.id, 'archived');
      },
      revert: () => {
        setStatus(order.id, order.status); // the status saved before acting
      },
      commit: () => saveStatus?.(order, 'archived'),
    });
    headingRef.current?.focus();
  }

  return (
    <Stack gap={4}>
      <Heading level={2} ref={headingRef} tabIndex={-1}>
        Open orders
      </Heading>
      <Text tone="secondary" size="small" as="p">
        {`${open.length} open, ${orders.length - open.length} archived`}
      </Text>
      <Stack as="ul" gap={2}>
        {open.map((order) => (
          <Inline as="li" key={order.id} justify="between">
            <Inline gap={3}>
              <Text mono tone="secondary">{`#${order.number}`}</Text>
              <Text>{order.customer}</Text>
              <Badge tone="warning">Open</Badge>
            </Inline>
            <Button
              size="sm"
              aria-label={`Archive order #${order.number}`}
              onPress={() => {
                archive(order);
              }}
            >
              Archive
            </Button>
          </Inline>
        ))}
      </Stack>
    </Stack>
  );
}
```

<!-- recipe-source:end -->

#### Verified by

`src/recipes/UndoableAction/UndoableAction.test.tsx` (no dialog appears, Undo, keyboard, fake-timer commit, failed commit, axe), `src/hooks/useUndoable.test.tsx` (the hook itself) and the `Recipes/UndoableAction` stories.