# Loui DS
> 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.
Package loui-ds@0.7.4. Entry points: `loui-ds`, `loui-ds/patterns`, `loui-ds/styles.css`. All component and token names below are exact; do not invent others.
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.
## Guides
- [Introduction](./guides/introduction.md): What Loui DS is and how it is organized.
- [Getting started](./guides/getting-started.md): Install, load the stylesheet, wrap the app in DSProvider, fonts, SSR.
- [Principles](./guides/principles.md): The three visual rules, the product principles and the agent principles.
- [Content guidelines](./guides/content-guidelines.md): Microcopy rules: tone, casing, buttons, errors, empty states, numbers.
- [Accessibility](./guides/accessibility.md): WCAG 2.2 AA target, keyboard model and how it is tested.
- [Using with AI](./guides/using-with-ai.md): The manifest, llms.txt, content rules and Storybook MCP.
- [Bundle size](./guides/bundle-size.md): What an app ships, stripping unused React Aria locales, code splitting.
## Foundations
- [Color](./foundations/color.md): Layers, lines, text and signal colors: usage rules and contrast.
- [Typography](./foundations/typography.md): Geist and Geist Mono, the type scale, tracking and when to use mono.
- [Spacing, sizing and radius](./foundations/spacing.md): The 4px grid, control and layout sizes, radius roles and elevation.
- [States and interaction](./foundations/states.md): Rest, hover, focus, selected, disabled and invalid; keyboard model; undo vs confirm.
- [Motion, layering and iconography](./foundations/motion.md): Durations and easing, reduced motion, the z-index stack and icon rules.
## Components
- [Accordion](./ai/components/Accordion.md): A stack of sections that expand and collapse. (experimental)
- [ActionList](./ai/components/ActionList.md): 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"`). (experimental)
- [AddCard](./ai/components/AddCard.md): A dashed "create new" tile that sits in a grid next to cards. (experimental)
- [AgentCard](./ai/components/AgentCard.md): A card for one agent: icon, name, status, description and a footer with the last activity and the number of items waiting for approval. (experimental)
- [Alert](./ai/components/Alert.md): An inline message with a tone, an icon, an optional title, an action and a dismiss button. (experimental)
- [ApprovalCard](./ai/components/ApprovalCard.md): A reply waiting for approval: the original message, an editable draft written by an agent and two actions, send and discard. (experimental)
- [AppShell](./ai/components/AppShell.md): The application layout: a sidebar, and a main column with a top bar above a scrollable content region. (experimental)
- [AppShellNavToggle](./ai/components/AppShellNavToggle.md): The icon button (menu icon) that opens the off-canvas sidebar. (experimental)
- [Avatar](./ai/components/Avatar.md): A circular photo or initials of a person, in grays (never a color per person). (experimental)
- [Badge](./ai/components/Badge.md): A pill with a short status label. (experimental)
- [Banner](./ai/components/Banner.md): A persistent, full-width message for a whole page or section: maintenance, a limited account, an offline mode. (experimental)
- [Breadcrumb](./ai/components/Breadcrumb.md): The path to the current page as an ordered list of links inside a `nav` landmark. (experimental)
- [Button](./ai/components/Button.md): An action button built on React Aria's `Button`. (experimental)
- [Calendar](./ai/components/Calendar.md): A month calendar (React Aria `Calendar`, an ARIA grid). (experimental)
- [Card](./ai/components/Card.md): A bordered surface that groups related content. (experimental)
- [CardLink](./ai/components/CardLink.md): A card whose whole surface is one link or button. (experimental)
- [Chart](./ai/components/Chart.md): A responsive bar or line chart for one series, drawn in SVG. (experimental)
- [ChatPanel](./ai/components/ChatPanel.md): A chat side panel for talking to an agent: header with Clear, a message log, suggested prompts when empty, and a composer. (experimental)
- [Checkbox](./ai/components/Checkbox.md): A checkbox with a native `` (so `name` / `value` take part in form submission), an 18px box and an optional description. (experimental)
- [CheckboxGroup](./ai/components/CheckboxGroup.md): A labelled `role="group"` of checkboxes that share one value (`string[]`), one `name`, and one description and error. (experimental)
- [ChoiceTiles](./ai/components/ChoiceTiles.md): Single-choice tiles: a `radiogroup` whose options are drawn as big buttons with a label and an optional meta line. (experimental)
- [Citation](./ai/components/Citation.md): An inline marker for a claim in an answer. (experimental)
- [Code](./ai/components/Code.md): Monospace code: inline in a sentence, or as a block (`pre` + `code`). (experimental)
- [ColorField](./ai/components/ColorField.md): A hex colour field: a text input in Geist Mono with a `Swatch` preview of the current colour, built on React Aria `ColorField`. (experimental)
- [ColorOption](./ai/components/ColorOption.md): A selectable option that shows a color swatch and its name. (experimental)
- [ColorOptionGroup](./ai/components/ColorOptionGroup.md): A named group of `ColorOption`s that shares one value: the list of chosen option `id`s. (experimental)
- [Combobox](./ai/components/Combobox.md): 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. (experimental)
- [CommandPalette](./ai/components/CommandPalette.md): A command palette: a modal with a search field and a grouped list of commands, opened with `Mod+K` (configurable). (experimental)
- [ConfirmDialog](./ai/components/ConfirmDialog.md): 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. (experimental)
- [Container](./ai/components/Container.md): Centers page content and limits its line length: a maximum inline size plus a side gutter. (experimental)
- [CurrencyInput](./ai/components/CurrencyInput.md): A money field. (experimental)
- [DataTable](./ai/components/DataTable.md): A data table with locale-aware sorting, row selection with a bulk action bar, client-side pagination, loading and empty states. (experimental)
- [DatePicker](./ai/components/DatePicker.md): A date field with a calendar popover (React Aria `DatePicker`). (experimental)
- [Description](./ai/components/Description.md): Helper text under a field (the handoff `hint`). (experimental)
- [Dialog](./ai/components/Dialog.md): A modal dialog built on React Aria `DialogTrigger`, `ModalOverlay`, `Modal` and `Dialog`. (experimental)
- [Divider](./ai/components/Divider.md): A 1px line that separates groups of content, built on React Aria `Separator` (``, or `role="separator"` with `aria-orientation` when vertical). (experimental)
- [DonutMeter](./ai/components/DonutMeter.md): A circular meter for one proportion: how much of a whole is used, done or filled (storage used, goal reached, stock level). (experimental)
- [Drawer](./ai/components/Drawer.md): A non-modal side panel for filters, inspectors and secondary navigation. (experimental)
- [DueIndicator](./ai/components/DueIndicator.md): A due date with a status in words: "Mar 9 Overdue by 3 days", "Due today", "Due in 5 days", "Paid", "Paid Oct 30". (experimental)
- [EmptyState](./ai/components/EmptyState.md): Tells the user that there is nothing to show, why, and what to do next. (experimental)
- [ErrorText](./ai/components/ErrorText.md): 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). (experimental)
- [FieldError](./ai/components/FieldError.md): Error text of a field. (experimental)
- [FieldMessages](./ai/components/FieldMessages.md): Description followed by the error: the footer every field renders under its control. (experimental)
- [FieldSet](./ai/components/FieldSet.md): Groups related fields under a caption: a real `fieldset` with a `legend`, an optional description, and disabled propagation. (experimental)
- [FileUpload](./ai/components/FileUpload.md): A drop zone with a "Choose files" button and the list of added files (React Aria `DropZone` and `FileTrigger`). (experimental)
- [Form](./ai/components/Form.md): 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. (experimental)
- [FormErrorSummary](./ai/components/FormErrorSummary.md): 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. (experimental)
- [Grid](./ai/components/Grid.md): 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). (experimental)
- [Heading](./ai/components/Heading.md): A heading whose semantic level and visual size are separate choices, so the document outline stays correct while the design picks the size. (experimental)
- [Icon](./ai/components/Icon.md): An inline SVG icon (Lucide, bundled) that inherits the text color and draws a 1.5px stroke. (experimental)
- [IconButton](./ai/components/IconButton.md): A square button with a single icon and a required accessible name. (experimental)
- [Inline](./ai/components/Inline.md): Lays its children out in a horizontal row with a consistent gap. (experimental)
- [InlineConfirm](./ai/components/InlineConfirm.md): A two-step confirmation without a dialog: the trigger button turns into a question with Cancel and a confirm button, in place. (experimental)
- [Input](./ai/components/Input.md): Single-line text field: label, control, description and error wired together (`for`, `aria-describedby`, `aria-invalid`), built on React Aria `TextField`. (experimental)
- [Kbd](./ai/components/Kbd.md): A keyboard shortcut hint in mono type. (experimental)
- [Label](./ai/components/Label.md): The visible label of a field. (experimental)
- [LedgerList](./ai/components/LedgerList.md): A list of signed ledger entries: date, title, optional sub line, a signed amount and an optional running balance. (stable)
- [Legend](./ai/components/Legend.md): A list of the series of a chart: swatch, name and, optionally, a value. (experimental)
- [Link](./ai/components/Link.md): A link built on React Aria's `Link`. (experimental)
- [MatrixGrid](./ai/components/MatrixGrid.md): A matrix of toggle cells: rows by columns, each cell linking or unlinking one row with one column. (experimental)
- [Menu](./ai/components/Menu.md): A menu of commands that opens from a trigger, built on React Aria `MenuTrigger`, `Popover` and `Menu`. (experimental)
- [MenuItem](./ai/components/MenuItem.md): One command. (experimental)
- [MenuSection](./ai/components/MenuSection.md): A group of items with an optional caption. (experimental)
- [MenuSeparator](./ai/components/MenuSeparator.md): A 1px line between groups of items. (experimental)
- [Meter](./ai/components/Meter.md): A bar that shows a quantity within a known range (disk used, quota, score), as opposed to progress of a task. (experimental)
- [MoreActionsMenu](./ai/components/MoreActionsMenu.md): The common "more actions" menu: an icon button with three dots whose name comes from the message catalog ("More actions"), opening a `Menu`. (experimental)
- [NavItem](./ai/components/NavItem.md): One entry of a navigation list. (experimental)
- [NumberField](./ai/components/NumberField.md): A number field with minus and plus steppers (the handoff `Stepper`), built on React Aria `NumberField`: a text `` with `aria-roledescription="Number field"` (React Aria deliberately drops `role="spinbutton"`: VoiceOver cannot focus a spin button with typed text). (experimental)
- [Pagination](./ai/components/Pagination.md): 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). (experimental)
- [Popover](./ai/components/Popover.md): A floating surface for interactive content (filters, a small form, a color picker), built on React Aria `DialogTrigger`, `Popover` and `Dialog`. (experimental)
- [Progress](./ai/components/Progress.md): A thin bar for a task that makes progress: determinate with a `value`, or indeterminate when the amount is unknown. (experimental)
- [ProportionBar](./ai/components/ProportionBar.md): A single bar split into the parts of a whole (payment methods, composition). (experimental)
- [Radio](./ai/components/Radio.md): One option of a `RadioGroup`. (experimental)
- [RadioGroup](./ai/components/RadioGroup.md): A labelled `role="radiogroup"` of mutually exclusive options with native radio inputs. (experimental)
- [RankList](./ai/components/RankList.md): An ordered list of items with a value, a bar relative to the largest value and an optional detail. (experimental)
- [Rating](./ai/components/Rating.md): A read-only star rating. (experimental)
- [RequiredMark](./ai/components/RequiredMark.md): The visible marker of a required field, text from messages. (experimental)
- [ResponseFeedback](./ai/components/ResponseFeedback.md): Feedback and follow-up actions under an assistant response: two toggle buttons (good and bad response, `aria-pressed`), then optional Copy and Regenerate. (experimental)
- [ScrollArea](./ai/components/ScrollArea.md): A scrolling container with thin, themed scrollbars. (experimental)
- [SearchInput](./ai/components/SearchInput.md): A search box: leading search icon, clear button (and `Escape` clears), optional decorative shortcut hint, optional suggestions with accent-insensitive match highlighting. (experimental)
- [SegmentedControl](./ai/components/SegmentedControl.md): A segmented control picks one value from a few options, like a radio group drawn as a bar. (experimental)
- [Select](./ai/components/Select.md): A single-choice dropdown built on React Aria `Select`: a button that opens a listbox in a popover. (experimental)
- [Sheet](./ai/components/Sheet.md): A side panel that slides in from the inline-end edge, for viewing or editing one record without leaving the list. (experimental)
- [ShortcutsHelp](./ai/components/ShortcutsHelp.md): 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`. (experimental)
- [Sidebar](./ai/components/Sidebar.md): The app sidebar: a workspace block, navigation sections, an optional status card, a footer slot and the signed-in user. (experimental)
- [Skeleton](./ai/components/Skeleton.md): A placeholder block in the shape of content that is still loading. (experimental)
- [SkipLink](./ai/components/SkipLink.md): 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). (experimental)
- [Slider](./ai/components/Slider.md): A single-value slider built on React Aria `Slider`: a labelled track with one thumb that is a real ``, so keyboard, pointer, touch and form submission (`name`) work natively. (experimental)
- [SourceList](./ai/components/SourceList.md): The numbered list of sources an answer is based on. (experimental)
- [Sparkline](./ai/components/Sparkline.md): A tiny trend line (or area) without axes, drawn in SVG, for tables, stat cards and lists. (experimental)
- [Spinner](./ai/components/Spinner.md): An indeterminate loading ring that inherits the text color. (experimental)
- [SplitLayout](./ai/components/SplitLayout.md): A main column with a fixed-width side panel beside it: an editor with a chat, a list with a summary. (experimental)
- [Stack](./ai/components/Stack.md): Lays its children out in a vertical column with a consistent gap. (experimental)
- [StackedBar](./ai/components/StackedBar.md): Stacked bars: how each category divides into the same set of parts, horizontal (a row per category) or vertical (a column per category). (experimental)
- [StatCard](./ai/components/StatCard.md): 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. (experimental)
- [StatusSteps](./ai/components/StatusSteps.md): A horizontal indicator of progress through a linear status flow (Draft, Packed, Shipped). (experimental)
- [Stepper](./ai/components/Stepper.md): Progress through a multi-step flow such as a setup assistant. (experimental)
- [SubMenu](./ai/components/SubMenu.md): An item that opens a nested menu. (experimental)
- [SuggestionChip](./ai/components/SuggestionChip.md): A dashed chip that proposes a piece of text. (experimental)
- [Swatch](./ai/components/Swatch.md): A small circle filled with a color, with a subtle inset ring so dark colors stay visible on dark surfaces. (experimental)
- [Switch](./ai/components/Switch.md): An on/off setting that applies immediately. (experimental)
- [Tab](./ai/components/Tab.md): One tab of a `TabList`, with an optional count and shortcut hint. (experimental)
- [TabList](./ai/components/TabList.md): The row of tabs. (experimental)
- [TabPanel](./ai/components/TabPanel.md): The content of one tab. (experimental)
- [Tabs](./ai/components/Tabs.md): Tabs switch between panels of related content. (experimental)
- [Tag](./ai/components/Tag.md): A mono outlined label for versions, SKUs and filters. (experimental)
- [TagGroup](./ai/components/TagGroup.md): A group of tags with one tab stop and arrow-key navigation. (experimental)
- [TagInput](./ai/components/TagInput.md): 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. (experimental)
- [Text](./ai/components/Text.md): Body text on the type scale. (experimental)
- [Textarea](./ai/components/Textarea.md): Multi-line text field built on React Aria `TextField` + `TextArea`. (experimental)
- [Timeline](./ai/components/Timeline.md): A chronological list of events. (experimental)
- [ToastRegion](./ai/components/ToastRegion.md): Renders the toasts of a queue. (experimental)
- [Toggle](./ai/components/Toggle.md): A button that stays pressed: it switches one setting on or off (bold text, a filter, "show archived"). (experimental)
- [ToggleGroup](./ai/components/ToggleGroup.md): A row (or column) of related `Toggle`s that share one value: the list of pressed `id`s. (experimental)
- [ToolCallList](./ai/components/ToolCallList.md): The steps of a multi-step agent run as an ordered list of `ToolCallStep`. (experimental)
- [ToolCallStep](./ai/components/ToolCallStep.md): 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. (experimental)
- [Tooltip](./ai/components/Tooltip.md): An ink-style hint for a control, built on React Aria `TooltipTrigger` and `Tooltip`. (experimental)
- [TopBar](./ai/components/TopBar.md): The page header: a title with an optional subtitle, or a breadcrumb trail, and an actions slot. (experimental)
- [Tour](./ai/components/Tour.md): A step-by-step onboarding tour. (experimental)
- [VisuallyHidden](./ai/components/VisuallyHidden.md): Hides content visually while keeping it available to assistive technology. (stable)
## Recipes
Tested compositions for common situations. Start from the one that fits, keep its structure and wording, then validate what you produce.
- [ApprovalQueue](./recipes/approval-queue.md): A queue of replies written by an agent that wait for a person to approve them before anything reaches a customer. (experimental)
- [CommandPaletteSetup](./recipes/command-palette-setup.md): 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 (`?`). (experimental)
- [CreateOnTheFly](./recipes/create-on-the-fly.md): 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. (experimental)
- [DestructiveConfirm](./recipes/destructive-confirm.md): 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. (experimental)
- [DetailSheet](./recipes/detail-sheet.md): 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. (experimental)
- [FilterableTable](./recipes/filterable-table.md): 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. (experimental)
- [FormWithValidation](./recipes/form-with-validation.md): 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. (experimental)
- [InlinePriceEdit](./recipes/inline-price-edit.md): A price that reads as text and turns into a field when pressed. (experimental)
- [MarkdownMessage](./recipes/markdown-message.md): Safe markdown in the replies of a `ChatPanel`, through its `renderContent` prop. (experimental)
- [PasswordField](./recipes/password-field.md): A password field with a show/hide toggle, built from `Input` and a labelled `Button` in its `trailing` slot. (experimental)
- [SettingsPage](./recipes/settings-page.md): 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. (experimental)
- [SheetForm](./recipes/sheet-form.md): A form inside a side `Sheet` whose primary button sits in the sheet footer, outside the `