---
name: arbol-ui
description: Build dashboards fast with @arbol-ai/ui (React Aria Components + Tailwind CSS v4). Load it before building or changing any screen, page, form, table, filter, dialog, sheet, chart or app shell with @arbol-ai/ui. It covers which pattern a flow needs, the anatomy of list, record, settings and analytics pages, and the rules every screen keeps.
---

# Dashboards with @arbol-ai/ui

People use these dashboards all day, often on a phone or a small laptop. Every rule here exists so that
nothing is hidden, nothing typed is lost, and every state has a URL. Compose the library's components;
write a component of your own only when none fits.

## Setup

```bash
bun add @arbol-ai/ui react-aria-components react-aria @tanstack/react-router @tanstack/react-query
# + echarts for /charts, @tanstack/react-form for /form
```

```tsx
// app.css: @import 'tailwindcss'; @import '@arbol-ai/ui/theme.css';
// The root route's component: every href routes through TanStack Router, query string included, and
// tel:, mailto: and other sites' links stay as they are (another router: `UIProvider`, in setup.md).
<RouterUIProvider locale={locale}>
  <Outlet />
  <Toaster />
</RouterUIProvider>
```

Fonts, dark mode, typed hrefs (`RouterConfig`) and single-copy React Aria: `references/setup.md`. Entries:
`@arbol-ai/ui` (components), `@arbol-ai/ui/router` (TanStack Router: `RouterUIProvider`,
`useUnsavedChangesBlocker`), `@arbol-ai/ui/query` (TanStack Query: `QueryView`), `@arbol-ai/ui/charts`
(ECharts), `@arbol-ai/ui/form` (TanStack Form).

## Page, dialog, sheet or alert?

| Use | When | Examples |
| --- | --- | --- |
| **Page** (its own route) | Long forms, configuration, anything worth a link or the back button | A contact, Settings, a report |
| **Dialog** (`Overlay kind="dialog"`, the default) | A short focused task that creates something or needs a decision, then returns | New contact, Invite a teammate, Export |
| **Sheet** (`Overlay kind="sheet"`) | Look at or tweak one record in context without leaving the page | A conversation from the inbox, a row's quick edit |
| **Alert** (`ConfirmDialog`) | One question before something irreversible | Delete this contact?, Stop the campaign? |

- Render `<Overlay onClose={…}>` while open (or inside `OverlayTrigger`, or controlled with `isOpen` and
  `onOpenChange`). Compose it from `OverlayHeader` (`OverlayTitle`, `OverlayDescription`), `OverlayBody`
  (scrolls) and `OverlayFooter` (stays in view, the main action last).
- **The discard guard is built in.** Closing with something typed asks "Discard what you wrote?". Pass
  `dirty={false}` when changes apply at once, and `busy` while a save runs (nothing dismisses it). After a
  successful save call the render prop's `leave()` (`{(close, leave) => …}`), never `close()`, which would
  ask. Inner forms cancel with `useOverlayClose() ?? onCancel`.
- A sheet showing a record writes its id to the URL (`?contact=<id>`) and is keyed by the id, never by
  its version, so a save does not open it again.
- Pages with a draft ask before leaving: `<UnsavedChangesDialog {...useUnsavedChangesBlocker(isDirty)} />`
  (from `/router`). It asks only when the path changes (a tab or an opened sheet never asks) and adds the
  browser's own warning for reloads and closed tabs.
- `ConfirmDialog`: the question as `title`, what happens as `body`, the verb as `confirmLabel`. Use
  `isPending` while it runs and `error` to keep it open on failure; `confirmationText` makes the person
  type the name for the gravest actions.

## The four standard pages

Recipes for each, ready to copy, are in `references/patterns.md`.

```text
List      PageContainer
            PageHeader: PageTitle · PageDescription hideOnPhone · PageActions (one filled "New …")
            PageContent
              filters: SearchField debounceMs · FilterChips · FoldingFilters > FilterSelect · ColumnPicker
              QueryView query pending={<TableSkeleton />} errorDescription > (rows, { isUpdating }) =>
                DataTable aria-label columns data getRowId getRowHref|onRowAction sorting onSortingChange
                manualSorting (server) isUpdating (next answer loading) columnVisibility columnOrder
                emptyState: EmptyState (nothing yet, with the action) | EmptyState variant="filtered"
              CursorPagination (cursors) | Pagination (page and total)

Record    PageContainer
            DetailHeader
              DetailHeaderContent: Avatar size="xl" · DetailHeaderInfo (PageTitle + Badge, DetailHeaderMeta)
              PageActions: outline Button · the next step as the filled one · RowMenu (the rest)
            Tabs label tabs=[{ id, label, count, href }] value={section} > TabPanel id={section} > <Outlet />
            ConfirmDialog (destructive actions from the RowMenu)

Settings  PageContainer maxWidth="4xl"
            PageHeader: PageTitle · PageDescription
            <form id>
              SettingGroup title description action
                SettingToggle (on/off) · SettingRow label description layout="responsive" > control
              SaveBar form isDirty isPending error idle onDiscard     ← the form's last child
            UnsavedChangesDialog {...useUnsavedChangesBlocker(isDirty)}

Analytics PageContainer
            PageHeader: PageTitle · PageActions > DateRangeFilter variant="chip" (period in the URL)
            QueryView query pending={the figures with isLoading} > (report) =>
            StatGrid > Stat label value formatOptions hint isLoading trend={<TrendDelta value tone />}
            grid lg:grid-cols-5 > ChartPanel eyebrow title note legend={<ChartLegend />}
              > TrendChart | BarChart | DonutChart | FunnelChart | GaugeChart (from /charts)
```

Data comes from TanStack Query, and each region that shows one query draws it with `QueryView` (from
`/query`): the `pending` placeholder (`LoadingState` by default) before the first answer, `ErrorState` with
a retry that refetches, `empty` for an empty answer, then the data, with `isUpdating` while the next answer
loads behind it (`placeholderData: keepPreviousData` keeps the rows on screen).

The shell (`AppShell` with `navigation` data, `currentPath`, the account menu built with `MenuTrigger` and
`Menu`, breadcrumbs in `header`, and a `CommandPalette`) is rendered once in the root layout.

## Rules that do not bend

1. **App copy is the app's.** Titles, labels, headers, empty-state lines and button text come through
   props and children, already translated (`m.*()`, `t()`). The library never defaults them. Its own
   strings ("Close", "1–15 of 120", "No results") follow the provider's `locale` in Spanish or English;
   reword them with its `messages`. Pass numbers as numbers and dates as `CalendarDate`, never
   pre-formatted. See `references/i18n.md`.
2. **Tokens only, never hex.** Use semantic tokens (`bg-primary`, `text-muted-foreground`, `border-border`),
   the ramps (`bg-<c>-3 text-<c>-11 border-<c>-a3`), `rounded-field|menu|card|dialog` and `shadow-*`;
   error text is `text-red-11`. Charts take theme names (`chart-1`…`chart-5`, `chart-positive`,
   `chart-negative`, `chart-caution`, `chart-neutral`). Badges and notices take a `tone`. Merge classes
   with `cn`.
3. **Navigation is an `href`.** `ButtonLink`, `Link`, `MenuItem`, `Tab`, `Breadcrumb`, `getRowHref`,
   navigation items, `RowMenu` and command items all take one, and `RouterUIProvider` routes it
   client-side. Never import router code into a component built on the library, nor wrap one in a router
   `Link`. Call `navigate()` yourself only after an action (a save that leads to the new record).
4. **URL state and persistence belong to the app.** Search, filters, sort, page or cursor, the tab
   (`?tab=` or `href` tabs), the open sheet (`?contact=<id>`) and the period live in the router's search
   params, written with `replace: true` while typing. Components are controlled (`value` and `onChange`)
   and store nothing. Column choices (`useColumnState` `value` and `onChange`) and the collapsed rail go
   to the app's storage, which keeps ids and preferences, never personal data.
5. **Accessibility basics.**
   - Name everything that has no visible label: tables and charts (`aria-label`), `Tabs` (`label`), icon
     buttons (`IconButton label` or `aria-label`), unlabeled fields, and a `RowMenu` per record.
   - Icons are `aria-hidden`, and a page has one `PageTitle`, its `h1`.
   - Never nest interactive elements: a row that is a link opens its actions through `RowMenu`.
   - Keep focus rings (`focusRing` on custom controls) and the library's 44px touch targets.
   - Errors appear where the person looks: under the field, in `FormError`, in the `SaveBar` or the
     `ConfirmDialog`. A toast is only for what just happened.
   - Shortcuts are advertised with `aria-keyshortcuts`.

## Speed for people who use it all day

- **One next step.** A record shows its usual next step as the one filled button, named with a verb.
  The second most common action sits beside it in `outline`, and the rest go in `RowMenu` ("⋯"), the
  destructive ones last. Irreversible steps ask once.
- **Forms** put labels above fields. Use two columns only where the form itself is wide, and fold
  optional fields in a `Disclosure` ("More details (optional)").
- **Empty states live where the action is**, with the next step as a button. An editor never reorders
  what someone is editing; it sorts again the next time it opens.
- **Phones** (check at 375, 768 and 1280px wide): the page never scrolls sideways (tables scroll inside
  their frame). Use `PageDescription hideOnPhone` and `Breadcrumbs collapseOnPhone` (the parent becomes
  a back arrow). `FoldingFilters` folds a filter row, secondary buttons become icons with a label, and
  overlay footers stack the main action under the thumb by themselves.
- **Keyboard:** Ctrl+K (⌘K) opens `CommandPalette` from anywhere (mount it once in the shell).
  `useHotkey('n', …)` adds page shortcuts, which already ignore fields and open dialogs. List them in
  `ShortcutsDialog` (`?`).

## Where to look next

- `references/components.md`: every export, one line each (generated).
- `references/patterns.md`: copy-ready recipes for a list, a record, settings, a create dialog, a sheet
  editor, analytics, the app shell, feedback states, and the provider with TanStack Router and Paraglide.
- `references/setup.md`: install, theme, fonts, dark mode, `RouterUIProvider` (or `UIProvider`) and typed
  hrefs.
- `references/i18n.md`: app copy against library strings, overrides, locales, dates and numbers.
- The documentation site renders every example: `vp dev site` in the `project-arbol-ui` repository.
- The JSDoc of each export (in your editor or the installed `dist/*.d.ts`) gives its purpose, every
  prop with its default, and an `@example`. It is the source of truth for props.
